William Valentin
64 lines
2.3 KiB
Markdown
64 lines
2.3 KiB
Markdown
# Councils Pipeline
|
|
|
|
Flynn supports a deterministic dual-council orchestration pipeline (`council.run`) that runs two isolated groups (`D`, `P`) through ideation, assessment, grounding, bridge exchange, and meta merge.
|
|
|
|
## Guarantees
|
|
|
|
- Bridge-only cross-council communication.
|
|
- Strict JSON schemas for artifacts (`.strict()` validation).
|
|
- Deterministic orchestrator-owned idea IDs (`D.r1.01`, `P.r2.03`, ...).
|
|
- Canonical JSON serialization for hashing and reproducibility.
|
|
- Deterministic writer-side brief + diff generation (model does not write diffs).
|
|
|
|
## Key Artifacts
|
|
|
|
- `IdeaCard` (content + optional grounding, schema versioned)
|
|
- `IdeaAssessment` (scores/decision per `idea_id`, schema versioned)
|
|
- `CouncilBrief` (`v1`/`v2` group artifact)
|
|
- `BridgePacket` (whitelisted transfer contract)
|
|
- `CouncilDiff` (code-computed deterministic diff)
|
|
- `MetaSelection` (JSON-only selection/merge record)
|
|
- `CouncilRunResult` (`pipeline_version`, hashes, trace, stop snapshot)
|
|
- `conversations` (per-agent call log with prompt payload + raw response)
|
|
|
|
## Tool Interface
|
|
|
|
`council.run` input:
|
|
|
|
```json
|
|
{
|
|
"task": "string",
|
|
"constraints": "object|string?",
|
|
"success_definition": "string?",
|
|
"budget": "object?",
|
|
"timebox": "string|number?",
|
|
"output_format": "string?",
|
|
"max_rounds": "number?",
|
|
"session_id": "string?"
|
|
}
|
|
```
|
|
|
|
`council.run` output behavior:
|
|
|
|
- Tool output returns a concise execution brief suitable for TUI/chat surfaces.
|
|
- Full artifacts are persisted to disk:
|
|
- `${FLYNN_DATA_DIR}/councils/` when `FLYNN_DATA_DIR` is set
|
|
- otherwise `~/.local/share/flynn/councils/`
|
|
- Per run, Flynn writes:
|
|
- `<timestamp>-<slug>.md` summary report with conversation trace and embedded raw JSON
|
|
- `<timestamp>-<slug>.json` full structured `CouncilRunResult`
|
|
|
|
## Determinism Notes
|
|
|
|
- `prompt_payload_hash` is computed from canonical JSON payload passed to model.
|
|
- `artifact_hash` is computed from canonical validated artifact JSON.
|
|
- Trace ordering is deterministic (`phase_index`, then `call_id`), independent of async completion order.
|
|
- Conversation logs are sorted by (`phase_index`, `call_id`) for stable Web UI display.
|
|
|
|
## Safety Rules
|
|
|
|
- Unknown schema keys are rejected.
|
|
- Meta stage may reference existing IDs only.
|
|
- Bridge packets are parse+validate+whitelist+re-serialize before exchange.
|
|
- On bridge validation failure, phase 2 is skipped (fail closed).
|