Metadata-Version: 2.4
Name: ai-council-orch
Version: 0.2.1
Summary: Software orchestrator that runs the AI Council protocol over an instance's state files. Framework consumer, not part of the framework core.
Author: The AI Council contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/jeffrey19810822-blip/ai-council-orchestrator
Project-URL: Repository, https://github.com/jeffrey19810822-blip/ai-council-orchestrator
Project-URL: Issues, https://github.com/jeffrey19810822-blip/ai-council-orchestrator/issues
Project-URL: Framework, https://github.com/jeffrey19810822-blip/ai-council
Keywords: ai-council,orchestration,decision-records,multi-agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Provides-Extra: llm
Requires-Dist: anthropic>=0.40; extra == "llm"
Dynamic: license-file

# AI Council Orchestrator

Software that runs the [AI Council](https://github.com/jeffrey19810822-blip/ai-council)
protocol over a project instance's state files.

This repository is a **consumer** of the AI Council framework, not part of its
core. The framework core stays documentation and method only; the orchestrator
is code and ships separately. See the framework's `orchestrator-design.md`
(Build Placement) for why.

## Status

Pre-alpha **walking skeleton**. It reads and safely updates state files, can
drive a guarded execution loop, and has the first file-based slice of the
discussion engine. Working slices today:

- Parse an instance's `docs/todo.md` task matrix per the framework's
  `state-schema.md`.
- Validate it: canonical columns, allowed statuses, unique IDs (hard errors);
  missing owner/reviewer/validation and owner-equals-reviewer (warnings).
- Print it as a table or emit it as JSON.
- Parse fenced handoff, execution-result, and review-result objects from
  Markdown state files.
- Append well-formed state objects to `docs/log.md`.
- Set task status in `docs/todo.md` with round-trip checks.
- Run the execution engine loop with explicit approval and reviewer gates.
- Show a single-instance summary across todo, decisions, discussion readiness,
  and state objects.
- Show a read-only Command Center summary across one or more instances, with
  `--sort-by` (issues, todo, decisions, discussion_incomplete) and `--filter`
  (has-issues, has-errors, has-warnings, incomplete-discussion) for navigation.
- Serve the same Command Center report as a read-only local web view.
- Validate discussion-engine stage readiness for a decision record, with
  advisory content-quality checks (unfilled Clean Input subsections, empty or
  duplicated proposals).
- Parse decision records, persist proposal-author handoffs, capture proposal
  outputs, render anonymous peer-review packets, persist review handoffs, and
  capture reviews into Round 2 for the discussion engine.
- Draft proposal, review, and synthesis handoffs through the optional `llm`
  extra without writing decision records.
- Run the proposal/review/synthesis draft pipeline into handoff files without
  capturing anything into the decision record.
- Render synthesis packets, persist synthesis handoffs, and capture synthesis
  output into Round 3.
- Render final decision packets, persist final decision handoffs, and capture
  final decision fields into Round 4 while preserving the task matrix.

## First principle

The protocol and the state files are the source of truth. This software
automates work on top of them; it never becomes the record of truth.

> If the orchestrator is turned off, the instance must still be fully workable
> by hand from its files alone.

Any internal state this tool keeps must be rebuildable from the files.

## Quickstart

```bash
git submodule update --init --recursive

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Read the bundled sample instance:
ai-council-orch show-todo

# Summarize the bundled sample instance:
ai-council-orch show-instance
ai-council-orch show-command-center
ai-council-orch serve-command-center

# Read a real instance directory:
ai-council-orch show-todo /path/to/instance
ai-council-orch show-instance /path/to/instance
ai-council-orch show-command-center /path/to/instance-a /path/to/instance-b

# Emit JSON:
ai-council-orch show-todo --json

# Prepare an independent-proposal author packet from a decision record:
ai-council-orch proposal-packet examples/sample-instance/docs/decisions/2026-01-01-sample-flow.md --slot A

# Check whether decision records are ready for each discussion stage:
ai-council-orch check-discussion
ai-council-orch check-discussion /path/to/instance
ai-council-orch check-discussion /path/to/instance/docs/decisions/decision.md

# Persist a fillable proposal handoff, then capture the completed response:
ai-council-orch write-proposal-handoff /path/to/instance/docs/decisions/decision.md --slot B --out /tmp/proposal-B.md
ai-council-orch draft-proposal /path/to/instance/docs/decisions/decision.md --slot B --out /tmp/proposal-B.md
ai-council-orch capture-proposal /path/to/instance/docs/decisions/decision.md /tmp/proposal-B.md --slot B --source-label Author-B

# Draft proposals, anonymous reviews, and synthesis handoffs in one pass.
# This writes only handoff files under /tmp/council-drafts; capture remains manual.
ai-council-orch run-discussion /path/to/instance/docs/decisions/decision.md --out-dir /tmp/council-drafts

# Prepare an anonymous peer-review packet from a decision record:
ai-council-orch review-packet examples/sample-instance/docs/decisions/2026-01-01-sample-flow.md

# Persist a fillable review handoff for one anonymous proposal, then capture it into Round 2:
ai-council-orch write-review-handoff /path/to/instance/docs/decisions/decision.md --proposal 2 --out /tmp/review-2.md
ai-council-orch draft-review /path/to/instance/docs/decisions/decision.md --proposal 2 --out /tmp/review-2.md
ai-council-orch capture-review /path/to/instance/docs/decisions/decision.md /tmp/review-2.md --proposal 2

# Prepare synthesis context, persist a fillable handoff, then capture it into Round 3:
ai-council-orch synthesis-packet /path/to/instance/docs/decisions/decision.md
ai-council-orch write-synthesis-handoff /path/to/instance/docs/decisions/decision.md --out /tmp/synthesis.md
ai-council-orch draft-synthesis /path/to/instance/docs/decisions/decision.md --out /tmp/synthesis.md
ai-council-orch capture-synthesis /path/to/instance/docs/decisions/decision.md /tmp/synthesis.md

# Prepare final decision context, persist a fillable handoff, then capture it into Round 4:
ai-council-orch final-decision-packet /path/to/instance/docs/decisions/decision.md
ai-council-orch write-final-decision-handoff /path/to/instance/docs/decisions/decision.md --out /tmp/final-decision.md
ai-council-orch capture-final-decision /path/to/instance/docs/decisions/decision.md /tmp/final-decision.md

# Run the tests:
pytest
```

`show-todo` exits `0` on a clean read, `1` when the matrix has schema errors,
and `2` when the file cannot be found or parsed at all.

## Layout

```text
src/ai_council_orchestrator/
  schema.py       Python mirror of state-schema.md objects
  todo.py         parse and validate docs/todo.md
  decisions.py    parse decision records and build/write discussion packets
  llm.py          optional LLM drafting clients for fillable handoffs
  objects.py      parse fenced handoff/result/review objects
  web.py          read-only Command Center HTTP view
  writeback.py    update task matrix status and append docs/log.md objects
  engine.py       guarded execution-engine loop
  cli.py          the ai-council-orch command
examples/
  sample-instance/docs/         domain-neutral fixture state files
tests/
  test_*.py
.ai-council/    framework reference as a git submodule
```

## Relationship to the framework

The framework is referenced under `.ai-council/ai-council/`, the same path a
project instance uses. In this repository that path is a git submodule pinned
to a reviewed framework commit. The orchestrator reads real instances through
their files and treats `state-schema.md` as the interface. See
[`.ai-council/README.md`](.ai-council/README.md) for clone and initialization
notes.

## Roadmap

**Now:** state readers, safe write-back, guarded execution loop, and proposal,
review, synthesis, and final decision packet/handoff/capture flows, with
single-/multi-instance summaries, discussion-stage readiness checks, advisory
content-quality validation, optional LLM draft handoffs and discussion draft
pipeline, and Command Center sort/filter/web navigation.

## Non-goals

- Not a replacement for a project's domain business application or interface.
- Not a chat product; conversation is not the record of truth.
- Not a required dependency for using the protocol.
- Not a place for project-specific business logic to accumulate.

## License

MIT. See `LICENSE`.
