Metadata-Version: 2.4
Name: autogovern
Version: 0.3.0
Summary: Generate and maintain governance documentation for AI agents.
Author: Daemon Systems
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.13.4
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=13.7.1
Requires-Dist: typer>=0.27.0
Requires-Dist: opentelemetry-api>=1.20.0 ; extra == 'tracing'
Requires-Dist: opentelemetry-sdk>=1.20.0 ; extra == 'tracing'
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0 ; extra == 'tracing'
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/daemon-systems/auto-govern
Project-URL: Repository, https://github.com/daemon-systems/auto-govern
Project-URL: Issues, https://github.com/daemon-systems/auto-govern/issues
Provides-Extra: tracing
Description-Content-Type: text/markdown

# Auto Govern

Generate and maintain governance documentation for AI agents, directly from the agent's codebase.

## Install

```bash
# With uv (recommended)
uv tool install autogovern

# With pipx
pipx install autogovern

# Or with pip
pip install autogovern
```

One-line installers (install `uv` first if needed, then the tool):

```bash
# POSIX (Linux/macOS)
curl -fsSL https://raw.githubusercontent.com/daemon-systems/auto-govern/main/install/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/daemon-systems/auto-govern/main/install/install.ps1 | iex
```

A hosted install page with copy-button tabs is on the roadmap; the scripts
above are committed in `install/` and work from any stable URL.

### Upgrade from 0.2

The PyPI distribution remains `autogovern`. Upgrade it in place:

```bash
uv tool upgrade autogovern
```

Version 0.3 adds `auto-govern` as the primary command. It continues to accept
the `autogovern` command and read `.autogovern/` configuration. New
configuration is written to `.auto-govern/`.

## Quickstart

### Vanilla mode (no init required)

```bash
export AUTOGOVERN_API_BASE=https://openrouter.ai/api/v1
export AUTOGOVERN_MODEL=anthropic/claude-3.5-sonnet
export AUTOGOVERN_API_KEY_ENV=OPENROUTER_API_KEY
export OPENROUTER_API_KEY=your-key-here

auto-govern generate /path/to/agent-repo
```

Docs are generated into `governance/`. They are generic because no organisational context was provided. The more context you give it, the better the docs.

### Enhanced mode (with init)

```bash
auto-govern init          # wizard: config, context, hooks, CI
auto-govern scan          # build the AgentProfile and AgentCard
auto-govern generate      # write the governance document set
auto-govern check         # verify docs are current
```

`init` writes `.auto-govern/config.yaml` (provider settings) and `.auto-govern/context.yaml` (organisational context: risk appetite, oversight model, jurisdictions, owner). It also installs a pre-commit hook and writes forge-appropriate CI configuration.

## Commands

```bash
auto-govern init          # wizard: config, context, hooks, CI
auto-govern scan          # build and print the AgentProfile
auto-govern generate      # full or incremental doc generation
auto-govern diff          # show which sections would change and why
auto-govern check         # CI gate: report stale docs; --fix regenerates
auto-govern explain <doc> # plain-language provenance for a document
auto-govern hook install  # re-install hooks manually
auto-govern hook run      # heuristic impact check (pre-commit entrypoint)
```

### Global flags

The inspection and generation commands (`scan`, `generate`, `diff`, `check`,
`explain`) accept:

- `--json` — machine-readable JSON output
- `--config <path>` — alternate config file
- `--model <id>` — override the configured model for one run
- `--strict` — treat advisory scores as failures (`check` only)

### Headless mode

```bash
# Generate from a profile JSON without scanning a repo
auto-govern generate --profile agent-profile.json

# Check against a headless profile
auto-govern check --profile agent-profile.json

# Or pipe the profile straight in (no temp file)
cat agent-profile.json | auto-govern check --profile -
```

## Custom framework packs

The bundled framework pack (templates, knowledge base, style authority, and
the mapping of documents to their inputs) is data, not code — and you can
replace it. Point `framework_pack` in `.auto-govern/config.yaml` at your own
pack directory (relative to the repo root, so it travels with the repo):

```yaml
framework_pack: governance-pack/   # contains pack.yaml + markdown content
```

or set `AUTOGOVERN_FRAMEWORK_PACK` in vanilla mode. A pack is validated
when it loads: every file reference and every declared document input is
checked up front, so a broken pack fails with a message naming the exact
document and reference — never a crash halfway through generation. Copy the
bundled pack (`src/autogovern/frameworks/pack.yaml`) as a starting point.

## Reliability

- **Atomic generation** — every document in a run is staged and committed
  as one batch. If the model provider fails mid-run, nothing is written;
  the previous document set stays exactly as it was.
- **Per-agent verdicts** — on multi-agent repos, `check` reports every
  agent's status in one run (human output and `--json`).
- **Zero-LLM checks** — a clean `check` makes no model calls at all.

## Configuration

`.auto-govern/config.yaml`:

```yaml
model_provider:
  api_base: https://openrouter.ai/api/v1
  model: <model-id>
  api_key_env: OPENROUTER_API_KEY
  temperature: 0
watched_paths:
  - CLAUDE.md
  - .mcp.json
  - prompts/**
  # ...
thresholds:
  material: 80
  immaterial: 20
documents:
  system-card: true
  risk-assessment: true
  # ...
```

The API key is read from the named environment variable at runtime and never written to disk.

## CI setup

`auto-govern init` detects your forge from the git remote and writes CI configuration:

- **GitHub** — `.github/workflows/auto-govern.yml`
- **Forgejo** — `.forgejo/workflows/auto-govern.yml`
- **Bitbucket** — `bitbucket-pipelines.yml`
- **Other** — prints the command to add

In CI, run:

```bash
auto-govern check --json --strict
```

For auto-fix mode (commits regenerated docs):

```bash
auto-govern check --fix
git add governance/ && git commit -m "auto-govern: regenerated docs"
```

## How it works

1. **Scan** reads the repo (instruction files, MCP configs, model config, dependencies, prompts) and builds an AgentProfile with provenance on every field.
2. **Generate** writes the governance document set from the profile plus the organisational context. Each section receives only its declared inputs (token-efficient). Incremental: only sections whose inputs changed are regenerated.
3. **Check** rebuilds the profile, diffs against `governance/profile.lock`, and scores the change. Material changes (new tool, model swap, autonomy change) are detected deterministically without an LLM. Prompt content changes go to a semantic scorer.
4. **Idempotent** — a second `generate` with no changes writes nothing.

## Documentation

- `../docs/SPEC.md` — the full build specification
- `../docs/BUILDPLAN.md` — the phased build plan
- `../docs/BUILDLOG.md` — the build log, one line per phase

## Roadmap

- Hosted install page with copy-button install commands
- Standalone binaries (PyInstaller) and an npm wrapper for JS-native teams
- Homebrew tap

## License

Apache-2.0
