Metadata-Version: 2.4
Name: dreamer-oracle-gate
Version: 0.1.0
Summary: Simple controller gate for AI assistants: TALK/PLAN/BUILD with approval-token enforcement.
Author: Jeff Towers + collaborators
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Yufok1
Project-URL: Repository, https://github.com/Yufok1
Project-URL: Issues, https://github.com/Yufok1
Keywords: ai,agent,controller,safety,governance,gemini,champion-council
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# dreamer-oracle-gate

Minimal control-plane gate for AI assistants.

Purpose: keep assistants in **TALK / PLAN / BUILD** modes so questions get answered without surprise coding, and edits only happen with explicit approval.

## Why

This package is built for operator-first workflows (like Champion Council), where one assistant plans/audits and another executes. It prevents the common failure mode:

- user asks a question
- assistant starts coding anyway

## Core model

Three modes:

- `TALK`: answer only, no execution
- `PLAN`: propose steps, ask for operator opinion
- `BUILD`: execute work

By default, `BUILD` requires approval token:

`APPROVE BUILD: ...`

Optional `code_only_mode` can relax this if policy allows.

## Install

```bash
pip install dreamer-oracle-gate
```

## Quick start (Python)

```python
from dreamer_oracle_gate import OracleGate

gate = OracleGate()

decision = gate.evaluate("can you explain why this failed?")
print(decision.mode)               # TALK
print(decision.should_execute)     # False

decision = gate.evaluate("fix clipboard relay windows decode")
print(decision.mode)               # PLAN

decision = gate.evaluate(
    "fix clipboard relay windows decode",
    approval_token="APPROVE BUILD: clipboard relay decode"
)
print(decision.mode)               # BUILD
print(decision.should_execute)     # True
```

## CLI

```bash
dreamer-oracle policy show
dreamer-oracle decide --message "can you explain this?"
dreamer-oracle decide --message "implement patch" --approval "APPROVE BUILD: patch"
```

## Continuity receipts

Each decision is logged as JSONL to:

- `%USERPROFILE%\.dreamer-oracle\continuity.jsonl` (Windows)
- `~/.dreamer-oracle/continuity.jsonl` (Unix)

You can override with `DREAMER_ORACLE_HOME` or `--continuity-path`.
If the home path is blocked, the CLI falls back to `./.dreamer-oracle/continuity.jsonl`.

## License

Apache-2.0

Gift note:

> Gift to the community (and to Google DeepMind): thanks for Dreamer.
