Metadata-Version: 2.5
Name: synod-council
Version: 0.2.0
Summary: Durable, symmetric deliberation between two AI agents — with isolated git worktrees, peer review, adversarial review, and approval workflow.
Author: Narumi Abe
License: MIT License
        
        Copyright (c) 2026 Narumi Abe
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agents,ai,code-review,deliberation,mcp,multi-agent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# Synod

**Durable, symmetric deliberation between two AI agents** — with isolated git worktrees,
peer review, automated validation, and an explicit approval workflow.

Synod started life as the "council" inside a personal AI infrastructure where two
autonomous agents (an orchestrator and an executor) needed to make *real* decisions and
*real* code changes together — without one of them silently becoming the other's rubber
stamp.

## Why

Most multi-agent frameworks are orchestration theater: one agent calls another as a tool
and calls the output "collaboration". Synod is built around a different premise — two
agents that are **peers by construction**:

- **Symmetric protocol** — either agent can initiate; the protocol has no privileged side.
- **Identity contract** — every prompt re-establishes who the agent is, so a weak or
  distracted model can't drift into answering *as* its peer.
- **Bias-resistant synthesis** — the synthesizer for each problem is chosen by hashing
  the problem text, not by who spoke first.
- **Durable state** — every session lives in SQLite with explicit stages (`plan`,
  `review`, `synthesize`, `ratify`, ...). A crashed run leaves an inspectable trail, not
  a mystery.
- **Code changes land through worktrees** — each session gets its own git worktree and
  branch. Agents never push to `main`; a human-facing approval step stands between
  "looks done" and "published".
- **Validation with remediation** — checks run after implementation, failures go back to
  the implementing agent with bounded retries before a human ever sees it.

## Install

```bash
pipx install synod-council
```

Or from source:

```bash
git clone https://github.com/naruminho/synod-council
cd synod && pip install .
```

## Usage

### Library

```python
from synod.deliberation import Deliberator, Store, HTTPAdapter

adapters = {
    "Alice": HTTPAdapter("Alice", "http://127.0.0.1:9001/ask"),
    "Bob":   HTTPAdapter("Bob",   "http://127.0.0.1:9002/ask"),
}
synod = Deliberator(adapters, Store("council.db"))
result = synod.run("Should we use SQLite or Postgres for this workload?", initiator="Alice")
print(result.decision, result.confidence, result.status)  # consensus | reconciled
```

### MCP server

Synod ships an [MCP](https://modelcontextprotocol.io) server so any MCP-capable client
(Claude Desktop, Claude Code, Cursor, ...) can start a deliberation:

```
synod-mcp   # stdio transport
```

Add it to your client config and ask your agents to *deliberate* instead of guessing.

### HTTP server

```bash
synod-server --port 8790
curl -X POST http://127.0.0.1:8790/run -d '{"problem": "...", "initiator": "Alice"}'
```

## How a deliberation flows

```
plan (parallel) → cross-review (parallel) → synthesis → [ratification → reconciliation?]
```

If reviewers raise unresolved blockers, or confidence lands below 0.7, the candidate
decision goes to ratification by the non-synthesizing peer; a rejection forces explicit
reconciliation instead of silent consensus.

## Status

Extracted and battle-tested from a production personal infrastructure where it has been
deciding architecture and shipping code since 2026. The two-agent design is intentional;
N-participant support is on the roadmap.

## License

[MIT](LICENSE)
