dvergr Documentation

New to dvergr? Start with Getting Started.

🚀 Getting started

• Main README — project overview + quickstart
• Getting Started — first-room tutorial: REPL + CLI paths, tagged messages, streaming
• REPL meta-harness contract — deterministic, provider-free end-to-end test
• Configuration — config + state layers, the .dvergr/ layout
• Provider & model setup — API keys, providers, the models.edn registry
• CLI reference — dvergr-cli: flags, persistence, telemetry

📚 Concepts

• Rooms & Agents — the core model: Rooms + Participants on a Bus, addressing (DM vs broadcast), forks
• Programming Model — the compositional kernel: tagged messages, capability routing, dynamic subscriptions, escalation
• Recursive work orchestration — Rooms, threads, tasks, executions, recursive Workrooms, and provider-neutral collaboration
• Runs — durable execution identity, lifecycle subscription, correlation, and targeted cancellation
• Agent programs — immutable specialized-agent rosters, Run-backed hiring, Spindel composition, and fork-safe state placement
• Forks, worlds, and settlement — the cross-project Yggdrasil/Spindel/Dvergr/Simmis fork contract, ownership laws, and use-case coverage
• Discourse Theory — why "discourse": speech acts, theory of mind, and the Rational-Speech-Acts/FRP lineage (short, optional)
• Architecture — the L0–L7 layer map, subsystem graph, inbound message flow, per-file table
• State Model — the three-tier copy-on-write state + workspace model

🔧 Reference

• Tools & the SCI sandbox — the tool registry + the sandbox agents run code in, and its safety boundaries
• Media — voice, vision & files — speech-to-text across every frontend, image describe/extract, document text, the /drive mount
• Channels — Telegram — bridging a chat surface into Rooms: setup, allowlist, voice/documents, slash commands
• Scheduling — per-room recurring / one-shot tasks, incl. deterministic :code schedules
• Boundary secret injection — how an agent uses an API key it never sees (credential handling + the :secrets config)
• Process model — the pausable/resumable Process abstraction
• Benchmarks — native, oracle-verified public benchmarks (tau2-bench retail), headless runs, pass^k

🤝 Contributing

• CONTRIBUTING — the L0–L7 layer convention, running tests, repo layout, commit style

🧪 Examples & notebooks

Literate Clay notebooks (notebooks/notebooks/) — live-running, browsable at replikativ.github.io/dvergr; build with clj -M:clay -m notebooks.render. Start with getting_started.clj, then humans_and_agents, auditor, escalation, streaming, and llm_agent.

Runnable scenario scripts (examples/) — what the notebooks import; run with clj -M:examples -m <ns> (or -X:examples humans-and-agents/run):

• humans_and_agents.clj — humans + scripted agents, background tasks, propose/accept-reject, substrate forks
• scenario_manager_escalation.clj — capability routing for :escalation/budget (no hardcoded managers)
• scenario_streaming_partial.clj — per-consumer buffer policy: sliding-1 UI vs fixed-buffer audit
• scenario_auditor.clj — d/subscribe! tag-watchers alongside an inbox

See also

• Spindel — the FRP runtime dvergr is built on
• Datahike — the immutable Datalog database for conversation + knowledge
• Yggdrasil — copy-on-write branching across git + Datahike