cobb/skald

Kayos f71b533e52 v0.2 scaffold: vendor clawdforge SDK + forge module + Whisper plan

The Rust SDK already existed at Sulkta-Coop/clawdforge clients/rust/ — async,
reqwest-based, bearer-auth, exposes Client::run() + Session for multi-turn.
Vendoring it into vendor/clawdforge so skald is self-contained: no
git-submodule + no needing the clawdforge repo cloned next to skald.
Trade-off accepted: updates require manual re-copy until both sides
stabilize and we publish to a private cargo registry.

What landed:

- vendor/clawdforge/ — full SDK source from Sulkta-Coop/clawdforge HEAD.
  Pinned in skald-core/Cargo.toml as a path dep.
- skald-core/src/forge.rs — three-pass orchestration shell. Forge wraps
  clawdforge::Client; generate() / cleanup() / audit() each build a
  RunRequest with the right system prompt + model alias (always opus),
  call client.run(), return a PassOutput.
  Prompt templates are TODO stubs (SYSTEM_GEN_TODO etc) — filling in the
  actual prose-craft prompts is its own deep session.
- skald-core/src/config.rs — ForgeConfig { base_url, app_token, model }.
  Resolved by the binary from env (CLAWDFORGE_URL + CLAWDFORGE_TOKEN);
  lib stays env-agnostic.
- skald-core::AuditFinding + AuditResponse — parse shape for what the
  third-Opus canon audit returns, ready to map onto audit_findings rows.
- docs/tts-pipeline.md — full plan for v0.2 narration + post-TTS audit
  chain. Whisper-large-v3 STT does text-to-text verification on every
  render; an optional Gemini Flash audio pass catches subjective issues
  (prosody, tone) Whisper can't see. Reroll loop on crit findings.

What's still stubbed:

- Prompt templates in forge.rs (gen / cleanup / audit) — placeholders
  that describe the role but don't constrain output shape yet.
- context.rs (assemble the LLM context blob from DB rows) — entire module
  TBD.
- No CLI subcommand yet for invoking forge — that comes after context.rs.

Naming note: in Rust 2024 'gen' is a reserved keyword (for generators),
so the method is Forge::generate(), not Forge::gen().

2026-05-13 10:18:56 -07:00

3.3 KiB

Raw Blame History

skald

Long-form story-writer with canon-keeping, sequel continuity, and (future) self-hosted audiobook narration. Database is the source of truth — the writer is the tooling.

Named for the Old Norse poets who composed and memorized kings' sagas across generations.

Status: v0.1 — scaffold

What's wired:

Rust workspace (skald-core + skald)
Postgres schema for stories, characters, canon facts, chapters, passages, generation runs, audit findings, tags
pgvector extension installed for future similarity search
skald import-markdown ingests a story file (chapters + bible) into the schema
skald serve exposes /health and runs migrations on boot
Single-container deploy: postgres + skald in one image

Wired (this commit):

clawdforge Rust SDK vendored at vendor/clawdforge/ (upstream: Sulkta-Coop/clawdforge clients/rust/)
skald-core::forge — three-pass orchestration shell (gen / cleanup / audit). Prompts are TODO stubs; pipeline plumbing is in place.

Not yet wired:

Web UI (the inbox + browse + queue surface)
Prompt templates for the three passes (heavy prompt-engineering work — own session)
skald-core::context — assemble the LLM context blob from DB rows (bible + characters + parent prose summaries + similarity-matched passages)
Embeddings backfill + ivfflat index
TTS sidecar container + post-render audit chain (see docs/tts-pipeline.md)

v0.1 smoke

docker compose -p skald up -d
docker exec skald skald import-markdown \
    --path /seed/coast-down.md \
    --title "The Coast-Down"

curl http://lucy:7780/health
# → { ok: true, db_ok: true, story_count: 1, ... }

Schema (cheat sheet)

stories         → meta + status + parent/root for series
characters      → real or fictional, story-scoped
canon_facts     → setting, mystery, theme, rule, historical_anchor, hook
chapters        → full prose body
chapter_summaries → short summaries for cheap context loading
passages        → paragraph-level + embedding vector(1536)
generation_runs → every LLM call logged
audit_findings  → canon audit output (severity + area)
tags            → arbitrary labels

Architecture (v0.1 + the plan)

┌─────────────────────────────────┐
│  skald container                │
│  ┌───────────┐  ┌────────────┐  │
│  │ postgres  │  │ skald-rust │  │
│  │ pgvector  │←─│ axum + cli │  │
│  │ localhost │  │ :7780      │  │
│  └───────────┘  └─────┬──────┘  │
└─────────────────────────┼────────┘
                          │ HTTP (future)
                          ↓
                    ┌──────────┐
                    │clawdforge│
                    └─────┬────┘
                          ↓
                     opus calls

v1.0+: extract postgres to its own container on db-net. skald becomes pure stateless rust, connects via DATABASE_URL. Migration is a connection-string change + a network move; the binary doesn't care where the DB lives.

License

MIT.

3.3 KiB Raw Blame History