Metadata-Version: 2.4
Name: kulai
Version: 0.2.2
Summary: AI asset and workflow package manager — resolve and download model dependencies for ComfyUI and other AI software
Author-email: BarkinMaddox <m4dmaddox@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/BarkinMaddox/kulai
Project-URL: Issues, https://github.com/BarkinMaddox/kulai/issues
Keywords: kulai,comfyui,stable-diffusion,models,downloader,workflow,package-manager
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.9
Requires-Dist: requests>=2.28
Requires-Dist: rapidfuzz>=3.0
Requires-Dist: huggingface-hub>=0.20
Requires-Dist: toml>=0.10
Requires-Dist: pyyaml>=6.0
Dynamic: license-file

# kulai

AI asset and workflow package manager — download, track, and share model dependencies for ComfyUI, A1111, Forge, InvokeAI, SwarmUI, and more.

---

## What it does

Model workflows reference assets by filename only — no URLs, no sources, no way for someone else to reproduce your setup. `kulai` fixes that.

- **Resolve** a workflow and auto-find every model on HuggingFace and Civitai
- **Install** a `.kula` file to reproduce someone else's exact setup in one command
- **Wizard** to build a `.kula` file interactively — paste a Civitai or HuggingFace URL and it fills in filename, SHA256, VRAM hint, and type automatically
- **Check** which assets from a workflow are already present locally (no downloads, no API calls)
- **Generate** a `.kula` file from an existing workflow automatically

---

## Installation

```bash
pip install kulai
```

Or with pipx (recommended — keeps it isolated):

```bash
pipx install kulai
pipx ensurepath
```

**Requires Python 3.10+**

---

## .kula files

A `.kula` file is a portable manifest that lists every model a workflow needs, where to get it, and its SHA256 hash for verification. Share it alongside your workflow and anyone can reproduce your setup with one command.

```toml
[meta]
name    = "My Workflow"
author  = "you"
version = "1.0"

[[resource]]
display_name = "WAI Realism"
type         = "checkpoints"
required     = true
vram_gb      = 6.9
file_name    = "waiREALISM_v10.safetensors"
sha256       = "1E6EB29C..."
destination  = "models/checkpoints"

[resource.sources]
civitai = "https://civitai.com/api/download/models/2514670"

[[resource]]
display_name = "Some LoRA"
type         = "loras"
required     = false
file_name    = "my_lora.safetensors"

[resource.sources]
huggingface = "https://huggingface.co/someone/repo/resolve/main/my_lora.safetensors"
```

---

## Quick start

### Install a workflow's dependencies

```bash
kulai install my_workflow.kula
```

### Build a .kula file interactively

```bash
kulai wizard
```

Paste any Civitai or HuggingFace URL and kulai fills in everything it can — filename, SHA256, VRAM, asset type — ready for you to review and confirm.

### Generate a .kula from an existing workflow

```bash
kulai generate my_workflow.json
```

### Check what's already installed

```bash
kulai check my_workflow.json
```

### Resolve and download a workflow (no .kula file needed)

```bash
kulai resolve my_workflow.json
```

---

## Commands

### `install`

```bash
kulai install KULA_FILE [OPTIONS]
```

| Option | Description |
|--------|-------------|
| `--required-only` | Skip optional resources and custom nodes |
| `--nodes-only` | Clone custom nodes only, skip model downloads |
| `--variant NAME` | Override default variant for all resources (e.g. `fp16`, `q8`) |
| `--download-dir PATH` | Override destination for all resources |
| `--concurrent N` | Parallel downloads (1–16) |
| `--yes` / `-y` | Skip confirmation prompt |
| `--no-civitai-info` | Skip saving `.civitai.info` metadata sidecars |

### `wizard`

```bash
kulai wizard [--output FILE]
```

Interactive step-by-step builder. Works for any AI software — not ComfyUI-specific.

- Paste a Civitai URL (`civitai.com` or `civitai.red`) and it fetches filename, SHA256, size, and asset type from the API
- Paste a HuggingFace URL and it parses repo and filename
- VRAM hint is inferred from file size automatically
- Destination is inferred from asset type automatically
- Supports multiple quality variants per resource (fp16, fp8, q8, etc.)

### `generate`

```bash
kulai generate WORKFLOW [--output FILE] [--mode auto|semi-auto] [--no-cache]
```

Parses a ComfyUI workflow JSON, resolves every asset, and writes a `.kula` file. Use `--mode auto` to skip the interactive review.

### `check`

```bash
kulai check WORKFLOW [--verbose]
```

Scans local model directories and reports which assets are present and which are missing. No API calls, no downloads.

### `resolve`

```bash
kulai resolve [WORKFLOW] [OPTIONS]
```

| Option | Description |
|--------|-------------|
| `--auto` | Skip prompts; use HIGH confidence resolutions only |
| `--auto-all` | Skip prompts; use all resolutions |
| `--dry-run` | Show what would be downloaded without downloading |
| `--no-cache` | Ignore cached mappings |
| `--download-dir PATH` | Override destination directory |
| `--concurrent N` | Parallel downloads (1–16) |

### `config-init`

```bash
kulai config-init [--software PROFILE]
```

First-time setup wizard. Supported software profiles: `comfyui`, `a1111`, `forge`, `invokeai`, `swarmui`.

### `cache-list` / `cache-clear`

```bash
kulai cache-list
kulai cache-clear [NAME]
```

View or remove cached asset-to-source mappings.

### `config-show`

```bash
kulai config-show
```

Print the active config with API keys redacted.

---

## Civitai support

kulai supports both `civitai.com` and `civitai.red` (NSFW mirror) — paste URLs from either and the right API and download endpoint is used automatically.

Paste a model page URL in the wizard and kulai fetches metadata from the API:

```
https://civitai.com/models/971952/my-model?modelVersionId=1674551
https://civitai.red/models/123456/nsfw-model?modelVersionId=789012
```

When installing Civitai resources, `.civitai.info` sidecar files are saved alongside each model (ComfyUI Manager compatible). Disable with `--no-civitai-info`.

---

## API keys

kulai works without API keys for most public models. Keys unlock extra access:

| Key | Where to get it | What it unlocks |
|-----|----------------|-----------------|
| HuggingFace | [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) | Gated / private models |
| Civitai | [civitai.com/user/account](https://civitai.com/user/account) | Downloading (searching is free) |

Set via environment variable:

```bash
# Linux / Mac
export KULAI_HF_TOKEN="hf_..."
export KULAI_CIVITAI_TOKEN="..."

# Windows PowerShell
$env:KULAI_HF_TOKEN="hf_..."
$env:KULAI_CIVITAI_TOKEN="..."
```

Or in the config file:

```toml
[api_keys]
huggingface = "hf_..."
civitai      = "..."
```

---

## Configuration

**Location:**
- Linux / Mac: `~/.config/kulai/config.toml`
- Windows: `C:\Users\<you>\.config\kulai\config.toml`

```toml
comfyui_dir = "C:/programs/ComfyUI"

# Model paths are inferred from comfyui_dir automatically.
# Uncomment to override individual paths:
# [paths]
# checkpoints   = "D:/models/checkpoints"
# loras         = "D:/models/loras"
# vae           = "D:/models/vae"
# text_encoders = "D:/models/text_encoders"
# unet          = "D:/models/unet"

[api_keys]
huggingface = ""
civitai      = ""

[download]
concurrent  = 2
max_retries = 3

[resolution]
preferred_source           = "huggingface"   # "huggingface" | "civitai" | "any"
auto_confidence_threshold  = "high"
```

---

## Download features

- **Concurrent downloads** — configurable parallel transfers
- **Resume support** — picks up interrupted downloads where they left off
- **SHA-256 verification** — warns on mismatch, never silently deletes files
- **Disk space check** — warns before starting if space is tight
- **Smart skipping** — files already present are never re-downloaded
- **Civitai.info sidecars** — saves ComfyUI Manager compatible metadata alongside Civitai downloads

---

## Supported asset types

| Type | Default folder |
|------|---------------|
| Checkpoints | `models/checkpoints` |
| LoRAs / LyCORIS | `models/loras` |
| VAE | `models/vae` |
| Text encoders / CLIP | `models/text_encoders` |
| UNet / diffusion models | `models/unet` |
| ControlNet | `models/controlnet` |
| Upscale models | `models/upscale_models` |
| Embeddings | `models/embeddings` |
| IP-Adapter | `models/ipadapter` |
| Face restore / detection | `models/facerestore_models` |

Path layout adapts per software profile (`comfyui`, `a1111`, `forge`, `invokeai`, `swarmui`).

---

## Troubleshooting

**"Gated model / access denied"**
Visit the model page on HuggingFace and request access, then retry.

**"Civitai token required to download"**
Searching is free but downloading requires a token. Set `KULAI_CIVITAI_TOKEN` or add it to the config.

**SHA-256 mismatch warning**
The file is kept. Run `kulai cache-clear model.safetensors` and re-resolve with `--no-cache` to try again.

**Downloads are slow**
```bash
kulai install workflow.kula --concurrent 4
```

---

## Development

```bash
git clone https://github.com/BarkinMad/Kulai.git
cd Kulai
python -m venv .venv
.venv\Scripts\activate      # Windows
source .venv/bin/activate   # Linux / Mac
pip install -e .

pytest tests/ -v
```

---

## License

MIT — see [LICENSE](LICENSE) for details.
