# @isis - Generative AI Factory

Isis is Oshun's generative AI factory, responsible for all AI-powered content
generation including images, video, audio, 3D models, and text.

## Overview

| Aspect              | Description                    |
| ------------------- | ------------------------------ |
| **Domain**          | Generative AI & Asset Creation |
| **Scope Tag**       | `scope:isis`                   |
| **API Port**        | 4001                           |
| **Database Schema** | `isis`                         |

## Capabilities

- **Image Generation**: Stable Diffusion, DALL-E, Midjourney-style
- **Video Generation**: Zeroscope, Runway, text-to-video
- **Audio Generation**: TTS, music, sound effects
- **3D Generation**: Point-E, NeRF, Gaussian splatting
- **Text Generation**: LLM integration (GPT-4, Claude, Gemini)
- **Workflow Orchestration**: Multi-step AI pipelines

## Libraries

```
libs/isis/
├── client/              # TypeScript client for other domains
├── job-envelope/        # Canonical queue envelope schema
├── database/            # Prisma schema & utilities
├── workflows/           # ComfyUI workflow registry
├── comfyui-nodes/       # Custom ComfyUI nodes
├── ai-providers/        # Provider adapters
│   ├── openai/
│   ├── anthropic/
│   ├── stability/
│   ├── elevenlabs/
│   ├── runway/
│   └── replicate/
├── 3d-generation/       # 3D asset generation
├── 3d-browser/          # Browser-first 3D viewing and editing
├── ai-video/            # Video generation
├── audio-generation/    # Audio/TTS generation
├── outputs/             # Output manifest management
└── gaussian-splatting/  # NeRF/Gaussian splatting
```

## Quick Start

### Using the Client

```typescript
import { createIsisClient } from '@isis/client';

const isis = createIsisClient({
  baseUrl: process.env.ISIS_API_URL || 'http://localhost:4001',
});

// Generate an image
const job = await isis.generation.create({
  type: 'image',
  prompt: 'A majestic dragon flying over mountains',
  model: 'stable-diffusion-xl',
  parameters: {
    width: 1024,
    height: 1024,
    steps: 50,
  },
});

// Wait for completion
const result = await isis.generation.waitForCompletion(job.id);
console.log(`Generated: ${result.url}`);
```

### Running Locally

```bash
# Start Isis API
nx serve isis-api

# Run tests
nx test @isis/client

# Build all Isis libraries
nx run-many --target=build --projects=tag:scope:isis
```

## API Endpoints

| Method | Endpoint                         | Description           |
| ------ | -------------------------------- | --------------------- |
| POST   | `/v1/generation/jobs`            | Create generation job |
| GET    | `/v1/generation/jobs/:id`        | Get job status        |
| GET    | `/v1/generation/jobs/:id/result` | Get generation result |
| DELETE | `/v1/generation/jobs/:id`        | Cancel job            |
| GET    | `/v1/assets/:id`                 | Get generated asset   |
| GET    | `/v1/models`                     | List available models |
| POST   | `/v1/workflows`                  | Execute workflow      |

## Events

| Event                  | Description                |
| ---------------------- | -------------------------- |
| `isis.job.started`     | Generation job started     |
| `isis.job.progress`    | Job progress update        |
| `isis.job.completed`   | Job completed successfully |
| `isis.job.failed`      | Job failed                 |
| `isis.asset.generated` | Asset created from job     |

## Configuration

```bash
# Required
ISIS_DATABASE_URL=postgresql://...?schema=isis
REDIS_URL=redis://localhost:6379

# AI Providers
ISIS_OPENAI_API_KEY=sk-...
ISIS_ANTHROPIC_API_KEY=sk-ant-...
ISIS_REPLICATE_API_TOKEN=r8_...
ISIS_STABILITY_API_KEY=sk-...

# Storage
ASSET_BUCKET=oshun-assets
ASSET_CDN_URL=https://cdn.oshun.io
```

## Local Development

Start the full development environment:

```bash
# Start infrastructure (PostgreSQL, Redis, MinIO)
docker compose -f docker/docker-compose.dev.yml up -d

# Run database migrations
pnpm nx run @isis/database:prisma:migrate:dev
pnpm nx run @isis/workflow-registry:db:migrate

# Start the Generation API
pnpm nx serve isis-generation-api
```

**Note**: GPU workers require NVIDIA GPU with CUDA support. See Docker profile
`with-gpu`.

See [CLAUDE.md](/CLAUDE.md) for detailed local development setup.

## Related Documentation

- [API Reference](/docs/api/isis/)
- [Cross-Domain Integration](/docs/guides/cross-domain-integration.md)
- [AI Provider Setup](/docs/setup/ai-providers.md)
