SoulPacks

How to use

1. API

# List
curl -s http://localhost:8000/v1/soulpacks

# Convert only (no DB write)
curl -s -X POST http://localhost:8000/v1/avatars/import-soulpack \
  -H 'content-type: application/json' \
  -d '{"pack_id":"support-agent","persist":false}'

# Ensure avatar
curl -s -X POST http://localhost:8000/v1/avatars/import-soulpack \
  -H 'content-type: application/json' \
  -d '{"pack_id":"companion","persist":true}'

Errors use RFC 7807 codes: SOULPACK_NOT_FOUND, SOULPACK_LICENSE_REJECTED, SOULPACK_INVALID.

2. CLI

cd packages/soulos-core
.venv/bin/python -m cli pack list
.venv/bin/python -m cli pack import support-agent --persist false
.venv/bin/python -m cli pack export companion -o /tmp/my-companion

3. Soul Studio

Run Studio locally (soulos-studio on :8765), open the SoulPacks tab, then Open in Studio or Deploy to kernel.

4. Sidecar seed

python3 examples/soulpack-sidecar/seed_soulpack.py \
  --pack-id support-agent --persist true \
  --kernel http://localhost:8000

Then continue with hybrid prepare → your LLM → complete.

How to improve / author packs

1. Copy an existing pack under packs/soulpacks/ or export one with soulos pack export.
2. Edit SOUL.md (and optional IDENTITY.md / STYLE.md) — keep prose MIT-authored.
3. Update pack.json: id, name, version, license: "MIT", files, and either baseline_msv or msv_preset.
4. Register the pack in packs/soulpacks/catalog.json.
5. Add or extend tests in packages/soulos-core/test_soulpacks.py (compile + MIT checks).
6. Open a PR — CI runs kernel tests and the license copyleft gate.

packs/soulpacks/
  catalog.json
  _presets.yaml
  my-pack/
    pack.json      # license must be MIT
    SOUL.md
    IDENTITY.md    # optional
    STYLE.md       # optional

Docs & plan

• SoulPacks guide
• TDD delivery plan (M1–M5)
• Hybrid API (import-soulpack)
• examples/soulpack-sidecar