Metadata-Version: 2.4
Name: consilium-py
Version: 1.0.0
Summary: Dialectical code-change deliberation as a Python package
Project-URL: Homepage, https://github.com/alxmax/Consilium-py
Project-URL: Repository, https://github.com/alxmax/Consilium-py
Project-URL: Issues, https://github.com/alxmax/Consilium-py/issues
Author-email: Schipor Alexandru <schipor.alexandru123@gmail.com>
License: License text copyright (c) 2023 MariaDB plc, All Rights Reserved.
        "Business Source License" is a trademark of MariaDB plc.
        
        Parameters
        
        Licensor:             Schipor Alexandru
        Licensed Work:        consilium-py
                              The Licensed Work is (c) 2026 Schipor Alexandru
        Additional Use Grant: You may use, copy, modify, and redistribute the
                              Licensed Work for any non-commercial purpose,
                              including evaluation, education, research, and
                              personal use. Use of the Licensed Work within an
                              organization that generates revenue (directly or
                              indirectly) from products or services that
                              incorporate or are built using the Licensed Work
                              requires a commercial license from the Licensor.
        
        Change Date:          2030-06-06
        
        Change License:       Apache License, Version 2.0
        
        For information about alternative licensing arrangements for the Software,
        please contact the Licensor.
        
        
        Notice
        
        The Business Source License (this document, or the "License") is not an Open
        Source license. However, the Licensed Work will eventually be made available
        under an Open Source License, as stated in this License.
        
        For more information on the use of the Business Source License for MariaDB
        products, please visit the MariaDB Business Source License FAQ at
        https://mariadb.com/bsl-faq-mariadb.
        
        For more information on the use of the Business Source License generally,
        please visit the Adopting and Developing Business Source License FAQ at
        https://mariadb.com/bsl-faq-adopting.
        
        -----------------------------------------------------------------------------
        
        Business Source License 1.1
        
        Terms
        
        The Licensor hereby grants you the right to copy, modify, create derivative
        works, redistribute, and make non-production use of the Licensed Work. The
        Licensor may make an Additional Use Grant, above, permitting limited
        production use.
        
        Effective on the Change Date, or the fourth anniversary of the first publicly
        available distribution of a specific version of the Licensed Work under this
        License, whichever comes first, the Licensor hereby grants you rights under
        the terms of the Change License, and the rights granted in the paragraph
        above terminate.
        
        If your use of the Licensed Work does not comply with the requirements
        currently in effect as described in this License, you must purchase a
        commercial license from the Licensor, its affiliated entities, or authorized
        resellers, or you must refrain from using the Licensed Work.
        
        All copies of the original and modified Licensed Work, and derivative works
        of the Licensed Work, are subject to this License. This License applies
        separately for each version of the Licensed Work and the Change Date may vary
        for each version of the Licensed Work released by Licensor.
        
        You must conspicuously display this License on each original or modified copy
        of the Licensed Work. If you receive the Licensed Work in original or
        modified form from a third party, the terms and conditions set forth in this
        License apply to your use of that work.
        
        Any use of the Licensed Work in violation of this License will automatically
        terminate your rights under this License for the current and all other
        versions of the Licensed Work.
        
        This License does not grant you any right in any trademark or logo of
        Licensor or its affiliates (provided that you may use a trademark or logo of
        Licensor as expressly required by this License).
        
        TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
        AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
        EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
        TITLE.
        
        MariaDB hereby grants you permission to use this License's text to license
        your works, and to refer to it using the trademark "Business Source License",
        as long as you comply with the Covenants of Licensor below.
        
        Covenants of Licensor
        
        In consideration of the right to use this License's text and the "Business
        Source License" name and trademark, Licensor covenants to MariaDB, and to all
        other recipients of the licensed work to be provided by Licensor:
        
        1. To specify as the Change License the GPL Version 2.0 or any later version,
           or a license that is compatible with GPL Version 2.0 or a later version,
           where "compatible" means that software provided under the Change License can
           be included in a program with software provided under GPL Version 2.0 or a
           later version. Licensor may specify additional Change Licenses without
           limitation.
        
        2. To either: (a) specify an additional grant of rights to use that does not
           impose any additional restriction on the right granted in this License, as
           the Additional Use Grant; or (b) insert the text "None".
        
        3. To specify a Change Date.
        
        4. Not to modify this License in any other way.
License-File: LICENSE
Keywords: agentic,cli,code-review,deliberation,llm,multi-agent,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.25.0
Requires-Dist: click>=8.1
Requires-Dist: litellm>=1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: tenacity>=8.0
Provides-Extra: dev
Requires-Dist: pyright; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Provides-Extra: langgraph
Requires-Dist: langchain-core<0.3,>=0.2; extra == 'langgraph'
Requires-Dist: langgraph<0.3,>=0.2; extra == 'langgraph'
Provides-Extra: rag
Requires-Dist: chromadb<0.6,>=0.4; extra == 'rag'
Provides-Extra: server
Requires-Dist: fastapi>=0.100; extra == 'server'
Requires-Dist: uvicorn>=0.20; extra == 'server'
Description-Content-Type: text/markdown

# consilium-py

Dialectical code-change deliberation as a standalone Python package.

Same deliberation engine as the [Consilium Claude Code skill](https://github.com/alxmax/Consilium),
usable without Claude Code — from any terminal, CI pipeline, Python script, or HTTP API.

```bash
pip install consilium-py
consilium deliberate "Add Redis caching to the API"
```

## How it works

Three AI voices deliberate on your proposal in a structured pipeline:

1. **Conservator** — assesses risk, reversibility, and regression potential
2. **Generator** — proposes 3–5 approaches with trade-off analysis  
3. **Control** — audits for technical correctness and glossary compliance

The aggregator produces a verdict: `GO`, `MODIFY`, `STOP`, `BLOCK`, or `ESCALATE`.
Confidence score (0.0–1.0) reflects inter-voice agreement.

For a visual walkthrough, open [`docs/index.html`](docs/index.html) — a "how it works" page with
links to the requirement map and the architecture diagram — or the full architecture poster
[`docs/consilium_architecture.html`](docs/consilium_architecture.html).

## Install

```bash
pip install consilium-py
export OPENROUTER_API_KEY=sk-or-...
```

### Optional extras

| Extra | What it adds | Install |
|---|---|---|
| `[server]` | FastAPI HTTP server — `POST /deliberate` over HTTP | `pip install 'consilium-py[server]'` |
| `[rag]` | ChromaDB context injection — retrieves similar past decisions **and ingested reference docs** ([details](#rag--document-ingestion)) | `pip install 'consilium-py[rag]'` |
| `[langgraph]` | LangGraph orchestration mode replacing the sequential pipeline | `pip install 'consilium-py[langgraph]'` |

## Deliberation modes

| Mode | Description |
|---|---|
| `sequential` *(default)* | Generator → Conservator → Control in a single context chain |
| `dialectic` | Sequential + Skeptic challenger on the chosen candidate |
| `trias` | 3 parallel personalities (Pioneer, Architect, Steward) voting on a shared candidate set |
| `langgraph` | LangGraph-orchestrated pipeline; requires `[langgraph]` extra |

## Usage

### CLI

```bash
# Default (sequential mode, text output)
consilium deliberate "Refactor the auth module"

# With context files
consilium deliberate "Refactor the auth module" -c src/auth.py -c src/middleware.py

# Different mode + JSON output
consilium deliberate "Add health check endpoint" --mode trias --output json

# Review the current git diff
consilium check

# Use a different model (or set CONSILIUM_MODEL env var)
consilium deliberate "Add caching" --model gemini/gemini-2.5-pro
consilium deliberate "Add caching" --model openai/gpt-4o

# Explain a codebase (summary, public API, dependencies, gotchas)
consilium explain src/consilium/voices.py
consilium explain src/consilium/ --output json

# Start the web UI (requires the [server] extra) — picks a free port, opens a browser
consilium serve
consilium serve --port 9000 --no-browser
```

### Python API

```python
from consilium import deliberate

# Basic
report = deliberate("Add Redis caching to the API")
print(report.verdict)        # GO / MODIFY / STOP / BLOCK / ESCALATE
print(report.confidence)     # 0.0 – 1.0
print(report.recommendation)

# With mode and context
report = deliberate(
    "Refactor auth module",
    context=open("src/auth.py").read(),
    mode="dialectic",
    model="gemini/gemini-2.0-flash",
)

# RAG: inject similar past decisions + ingested docs as context (requires [rag] extra)
report = deliberate("Add rate limiting", rag=True)
```

### RAG & document ingestion

The `[rag]` extra pulls two kinds of context into a deliberation, each retrieved
by cosine similarity from a local ChromaDB store (`~/.consilium/chroma/`):

- **`SIMILAR PAST DECISIONS`** — your own past deliberation runs. Low-confidence
  and `STOP`/`BLOCK` runs are excluded by design (a failed past call isn't guidance).
- **`RELEVANT DOCS`** — chunks of reference documents you've ingested (coding
  standards, an architecture note, an API guide), cited by source in the report.
  So Control can check a change against *"conform CODING_STANDARDS.md"*.

```bash
pip install 'consilium-py[rag]'

consilium index                 # index your past runs (~/.consilium/runs/)
consilium ingest docs/          # chunk + index a doc or directory into the corpus
consilium ingest CODING.md      # …one file at a time works too

consilium deliberate "Add a cache layer" --rag     # inject both blocks
```

`ingest` chunks each `.md`/`.txt`/`.py`/`.rst` file (1200-char windows, 200
overlap), skipping binaries, files over 1 MB, and symlinks that escape the target.
Re-ingesting a file replaces its chunks (no stale orphans). Retrieved docs are
deduplicated by source, so one big file can't crowd out the others.

**Toggling:** `--rag` / `--no-rag`, defaulting from the `CONSILIUM_RAG` env var —
so you can set `CONSILIUM_RAG=1` locally and still force `--no-rag` for a single run.

> **On determinism:** RAG is **off by default** on purpose. Injecting past runs
> makes a deliberation's output depend on your history, which is at odds with the
> project's reproducibility goal. The `docs` path (a fixed, committed corpus) is the
> one that could ever be made default-safe — pinning/versioning a corpus is noted
> as future work, not done yet.

### HTTP API

Requires the `[server]` extra. Runs the three-voice deliberation over HTTP — useful for CI pipelines, polyglot codebases, or quick demos.

```bash
pip install 'consilium-py[server]'

# Easiest: consilium serve picks a free port, opens a browser to the HTML UI
export ANTHROPIC_API_KEY=sk-ant-...
consilium serve

# Or run uvicorn directly for more control (no auto port/browser handling)
uvicorn consilium.server:app --port 8123

# Or use claude-cli — no API key, just a Claude subscription
CONSILIUM_MODEL=claude-cli consilium serve
```

```bash
curl -X POST http://localhost:8123/deliberate \
  -H "Content-Type: application/json" \
  -d '{"proposal": "Add a /health endpoint to the auth service"}'
# → {"verdict":"GO","confidence":0.5,"recommendation":...}
```

Request body fields: `proposal` (required), `context`, `mode` (`sequential` / `dialectic` / `trias`), `model` — all optional except `proposal`. If `model` is omitted, `CONSILIUM_MODEL` env var is used.

### No-API-key backend (claude-cli)

If you have a Claude subscription (Claude Code CLI), you can run deliberations without any API key:

```bash
consilium deliberate "Add caching" --model claude-cli
```

```python
report = deliberate("Add caching", model="claude-cli")
```

Each voice call routes through `claude -p` (Claude Code CLI). Slower than a direct API call but useful for demos, local exploration, or when you don't have an API key.

### Provider-agnostic (LiteLLM)

Any model accessible via LiteLLM can be used by passing `provider/model`:

```bash
export OPENAI_API_KEY=sk-...
consilium deliberate "Add caching" --model openai/gpt-4o
```

```python
report = deliberate("Add caching", model="openai/gpt-4o")
```

The `CONSILIUM_MODEL` environment variable overrides the `--model` / `model=` parameter:

```bash
export CONSILIUM_MODEL=openai/gpt-4o
consilium deliberate "Add caching"
```

### Using OpenRouter (default)

OpenRouter gives access to Gemini, Claude, GPT, and hundreds of other models through a
single API key. This is the default provider.

```bash
export OPENROUTER_API_KEY=sk-or-...
```

```bash
# CLI — default model is openrouter/google/gemini-2.0-flash-001
consilium deliberate "Add caching"
consilium deliberate "Refactor auth" --model openrouter/google/gemini-2.5-pro
consilium deliberate "Add caching" --model openrouter/anthropic/claude-sonnet-4-5

# Or set once and forget
export CONSILIUM_MODEL=openrouter/google/gemini-2.5-flash
consilium deliberate "Add caching"
consilium check
```

```python
# Python API
from consilium import deliberate

report = deliberate("Add caching", model="openrouter/google/gemini-2.0-flash-001")
print(report.verdict)
print(report.recommendation)
```

> **Model strings:** use the `openrouter/` prefix followed by the exact model ID from the  
> [OpenRouter model list](https://openrouter.ai/models) — e.g. `openrouter/google/gemini-2.5-pro`.
> A `404 No endpoints found` means the model isn't available on your account (add credits or
> try a `:free` variant like `openrouter/google/gemini-2.0-flash-exp:free`).

## Deploy

Terraform for running the [HTTP API](#http-api) on GCP Cloud Run lives in
[`infra/`](infra/README.md) — private by default, API key in Secret Manager, no plain
secrets in Cloud Run env vars, Terraform state in a versioned GCS bucket (not local). See
[`infra/README.md`](infra/README.md) for the build/push/apply steps.

## Development

```bash
pip install -e ".[dev,server,rag,langgraph]"

python -m pytest          # full suite — voices are mocked, no API calls
pyright src/              # type check
python scripts/reqmap.py gate   # requirement-traceability drift gate (CI-style check)
```

Every source file that implements a capability carries a `# implements: <ID>` comment; its
tests carry `# tested-by: <ID>`. [`requirements/_map.md`](requirements/_map.md) is the generated
source-of-truth map (also viewable as [`requirements/_map.html`](requirements/_map.html)) — the
`gate` command above fails the build if code and requirements drift apart.

CI ([`.github/workflows/ci.yml`](.github/workflows/ci.yml)) runs the test suite on a **Python
3.11 + 3.12 matrix** plus the drift gate on every push. Two versions, not one, because the
package declares `requires-python = ">=3.11"` — testing both proves the floor it advertises
actually holds, so a 3.11 user can't hit a version-specific break that only 3.12 was tested against.

## Requirements

- Python 3.11+
- `OPENROUTER_API_KEY` — required for the default OpenRouter models
- `ANTHROPIC_API_KEY` — required when using bare Anthropic/Claude model names (e.g. `claude-sonnet-4-6`)
- Provider-specific env vars for other providers via LiteLLM (`OPENAI_API_KEY`, `GEMINI_API_KEY`, etc.)
- No API key needed when using `--model claude-cli` — requires the [Claude Code CLI](https://claude.ai/code) installed and authenticated

## Related

- **[Consilium skill](https://github.com/alxmax/Consilium)** — same engine as a Claude Code skill, with Trias, Dialectic, and Skeptic modes. Zero dependencies (stdlib-only). Runs inside Claude Code.

## License

See [LICENSE](LICENSE).
