Metadata-Version: 2.4
Name: aigc-sdk
Version: 0.3.1
Summary: Deterministic, fail-closed governance enforcement for AI model invocations.
Author-email: Neal Adams <neal@nealsolves.com>
License: MIT
Project-URL: Homepage, https://github.com/nealsolves/aigc
Project-URL: Repository, https://github.com/nealsolves/aigc
Project-URL: Documentation, https://github.com/nealsolves/aigc/blob/main/docs/USAGE.md
Project-URL: Issue Tracker, https://github.com/nealsolves/aigc/issues
Project-URL: Changelog, https://github.com/nealsolves/aigc/blob/main/CHANGELOG.md
Keywords: governance,audit,ai,enforcement,deterministic,policy,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Requires-Dist: jsonschema>=4.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=6.0; extra == "dev"
Requires-Dist: pytest-asyncio>=1.0; extra == "dev"
Requires-Dist: flake8>=7.0; extra == "dev"
Dynamic: license-file

# AIGC — Auditable Intelligence Governance Contract

![AIGC Banner](graphics/AIGC_banner.png)

AIGC makes AI invocation governance deterministic, enforceable, and auditable by design.

AIGC enforces deterministic, fail-closed policy evaluation over every model invocation. No silent fallbacks. No prompt-based governance. Core governance gates are unconditionally fail-closed; configured exceptions (risk scoring `warn_only`, sink failure `log` mode) are explicitly scoped and audited.

Every model call is validated against a declared policy, checked for role authorization, schema compliance, and tool constraints, and produces a tamper-evident audit artifact.

Governance is not documentation. It is runtime enforcement.

---

**SDK Implementation:** Reference implementation of constitutional governance for AI-assisted systems.

**Status:** v0.3.1 — 597 tests, 95% coverage. M2: risk scoring, signing (HMAC-SHA256), audit chain (opt-in), composition semantics, pluggable PolicyLoader, policy dates, OTel, policy testing, compliance export CLI, custom gates. Audit schema v1.2. React demo at full v0.3.0 feature parity.

---

## Governance Invariant

> **No AI-influenced behavior is valid unless it is:**
>
> 1. Explicitly specified
> 2. Deterministically enforceable
> 3. Externally observable
> 4. Replayable and auditable
> 5. Governed independently of any specific model or provider

This invariant is not aspirational. Every enforcement path in this SDK is
designed to satisfy all five conditions or fail closed.

## Five Governance Layers

| Layer | Concern | Implementation |
| ----- | ------- | -------------- |
| Behavioral Specification | No implicit behavior | YAML policies validated against JSON Schema (Draft-07) |
| Deterministic Enforcement | Machine-verifiable constraints | `enforce_invocation()` pipeline — fail-closed on any violation |
| Observability | Structured, persistent artifacts | SHA-256 checksummed audit records per invocation |
| Replay & Audit | Replayable execution paths | Golden replays + deterministic artifact generation |
| Model-Independent Governance | Provider-agnostic control | Roles, schemas, and policies — not prompts |

---

## Interactive Demo

An interactive companion to the SDK is deployed at:

**[https://nealsolves.github.io/aigc/](https://nealsolves.github.io/aigc/)**

The demo is a React application with seven hands-on labs, each exercising a specific
governance capability from v0.3.0. It is backed by a FastAPI API server deployed on
Render — no user API keys are required. `demo-app-streamlit/` remains in the repository
as deprecated reference material and is not the forward product surface.

| Lab | Topic | What it demonstrates |
| --- | ----- | -------------------- |
| 1 | Risk Scoring | `strict`, `risk_scored`, and `warn_only` modes; threshold behavior |
| 2 | Signing & Verification | HMAC-SHA256 artifact signing; tamper detection |
| 3 | Audit Chain | Hash-chained audit artifacts; chain continuity verification |
| 4 | Policy Composition | `intersect`, `union`, and `replace` composition strategies |
| 5 | Loaders & Versioning | Pluggable `PolicyLoader`; `effective_date` / `expiration_date` enforcement |
| 6 | Custom Gates | `EnforcementGate` plugins at all four pipeline insertion points |
| 7 | Compliance Dashboard | `aigc compliance export`-style report from a JSONL audit trail |

The demo deploys automatically on every push to `main` that touches `demo-app-react/`
via `.github/workflows/deploy-demo-react.yml`.

---

## Installation

```bash
pip install aigc-sdk
```

The import name is `aigc`:

```python
from aigc import enforce_invocation
```

**From source** (editable install with dev dependencies):

```bash
python3 -m venv aigc-env
source aigc-env/bin/activate
python -m pip install --upgrade pip setuptools wheel
pip install --no-build-isolation -e '.[dev]'
```

**Note:** The `--no-build-isolation` flag is required in network-restricted
environments. It uses the already-installed `setuptools` and `wheel` instead of
trying to download them fresh into an isolated build environment.

If using an internal PyPI mirror or wheelhouse, ensure `pip`, `setuptools`, and
`wheel` are available before running the editable install.

## Public API

Preferred imports:

```python
from aigc import (
    enforce_invocation,
    AIGC,
    InvocationValidationError,
    PreconditionError,
    SchemaValidationError,
    GovernanceViolationError,
)
```

Instance-scoped enforcement (recommended for new code):

```python
from aigc import AIGC
from aigc import JsonFileAuditSink

engine = AIGC(sink=JsonFileAuditSink("audit.jsonl"))
audit = engine.enforce(invocation)
```

## Enforced Controls

### Phase 1 (Core Pipeline)

- Invocation shape validation (typed errors, no raw `KeyError`)
- Policy loading with safe YAML + Draft-07 schema validation
- Role allowlist enforcement
- Preconditions + output schema validation
- Postcondition enforcement (`output_schema_valid`)
- Deterministic audit artifact generation with canonical SHA-256 checksums
- FAIL audit artifacts emitted before exception propagation

### Phase 2 (Full DSL)

- **Conditional guards** — `when/then` rules expand effective policy from
  runtime context; evaluated before role validation; effects are additive
- **Named conditions** — boolean flags resolved from invocation context with
  defaults and required enforcement
- **Tool constraints** — per-tool `max_calls` cap and tool allowlist
  enforcement; violations emit FAIL audits
- **Retry policy** — opt-in `with_retry()` wrapper for transient
  `SchemaValidationError` failures with linear backoff
- **Policy composition** — `extends` inheritance with recursive merge
  (arrays append, dicts recurse, scalars replace) and cycle detection

### Phase 3 (Production Readiness)

- **Async enforcement** — `enforce_invocation_async()` runs policy I/O off the
  event loop via `asyncio.to_thread`; identical governance behavior to sync
- **Pluggable audit sinks** — every enforcement emits to the configured
  sink automatically; configurable failure mode (`log` or `raise`).
  Prefer instance-scoped configuration:

  ```python
  from aigc import AIGC
  from aigc import JsonFileAuditSink
  engine = AIGC(sink=JsonFileAuditSink("audit.jsonl"))
  ```

  The global `set_audit_sink()` function is retained for backward
  compatibility but is not recommended for new code.

- **Instance-scoped enforcement** — `AIGC` class for thread-safe, isolated
  configuration (sink, failure mode, strict mode, redaction patterns)
- **Structured logging** — `aigc.*` logger namespace with `NullHandler` default;
  host applications configure log levels and handlers
- **`@governed` decorator** — wraps sync and async LLM call sites:

  ```python
  from aigc import governed

  @governed(
      policy_file="policies/governance.yaml",
      role="planner",
      model_provider="anthropic",
      model_identifier="claude-sonnet-4-5-20250929",
  )
  async def plan_investigation(input_data: dict, context: dict) -> dict:
      return await llm.generate(input_data)
  ```

### Milestone 2 (Governance Hardening)

- **Risk scoring engine** — factor-based risk computation with
  `strict`, `risk_scored`, and `warn_only` modes; `RiskThresholdError`
  raised in strict mode when threshold exceeded
- **Artifact signing** — HMAC-SHA256 signing via pluggable
  `ArtifactSigner` interface; constant-time signature verification
- **Tamper-evident audit chain** — opt-in `AuditChain` utility for
  hash-chaining artifacts with `chain_id`, `chain_index`,
  `previous_audit_checksum` fields; manual integration by the host
- **Composition restriction semantics** — `intersect`, `union`, and
  `replace` strategies for policy inheritance via `composition_strategy`
- **Pluggable PolicyLoader** — `PolicyLoaderBase` ABC for custom policy
  sources (database, API, vault); `FilePolicyLoader` default
- **Policy version dates** — `effective_date` / `expiration_date`
  enforcement with injectable clock for testing
- **OpenTelemetry integration** — optional spans and gate events; no-op
  when OTel is not installed; governance unaffected by telemetry
- **Policy testing framework** — `PolicyTestCase`, `PolicyTestSuite`,
  `expect_pass()`, `expect_fail()` for policy validation
- **Compliance export CLI** — `aigc compliance export` generates JSON
  compliance reports from JSONL audit trails
- **Custom EnforcementGate plugins** — `EnforcementGate` ABC with four
  insertion points (`pre_authorization`, `post_authorization`,
  `pre_output`, `post_output`) for host-specific gates

## Audit Artifact Contract

Audit artifacts follow `schemas/audit_artifact.schema.json` and include:

- policy identity: `policy_file`, `policy_version`, `policy_schema_version`
- model identity: `model_provider`, `model_identifier`, `role`
- result: `enforcement_result`, structured `failures`
- integrity + auditability: `input_checksum`, `output_checksum`, `timestamp`
- deterministic metadata container: `metadata`

## CI Gates

`.github/workflows/sdk_ci.yml` enforces:

- build-tool bootstrap (`pip`, `setuptools`, `wheel`) and editable install with
  `--no-build-isolation` for restricted-environment parity
- `python -m pytest` with coverage gate (`--cov-fail-under=90`)
- `flake8` for `aigc`
- markdown lint
- policy YAML validation against the Draft-07 policy schema

## Release Checklist

Before tagging a release, confirm all gates pass locally:

```bash
python -m pytest --cov=aigc --cov-report=term-missing --cov-fail-under=90
flake8 aigc
npx markdownlint-cli2 "**/*.md"
python - <<'PY'
import json; from pathlib import Path; import yaml; from jsonschema import Draft7Validator, validate
schema = json.loads(Path("schemas/policy_dsl.schema.json").read_text())
[validate(yaml.safe_load(p.read_text()), schema) or print(f"ok: {p}") for p in Path("policies").glob("*.yaml")]
PY
```

Then tag and push to trigger CI + PyPI publish:

```bash
git tag v<version>
git push origin v<version>
```

## CLI Reference

The `aigc` console script exposes three command groups:

### `aigc policy lint <file...>`

Checks one or more policy YAML files for syntax errors and JSON Schema compliance.
Exits non-zero if any file fails.

```bash
aigc policy lint policies/my_policy.yaml
# OK    policies/my_policy.yaml

aigc policy lint policies/*.yaml
```

### `aigc policy validate <file...>`

Runs lint plus full semantic validation, including `extends` composition and cycle
detection. Use this before deploying a new policy.

```bash
aigc policy validate policies/my_policy.yaml
# OK    policies/my_policy.yaml
```

### `aigc compliance export --input <audit.jsonl> [--output <report.json>]`

Reads a JSONL audit trail produced by the SDK and generates a structured JSON
compliance report (pass/fail counts, compliance rate, failure-gate breakdown,
per-policy summary).

```bash
# Print report to stdout
aigc compliance export --input audit.jsonl

# Write report to a file
aigc compliance export --input audit.jsonl --output report.json

# Include individual artifact records in the report
aigc compliance export --input audit.jsonl --output report.json --include-artifacts
```

---

## Documentation

| Document | Purpose |
| -------- | ------- |
| [Integration Contract](docs/PUBLIC_INTEGRATION_CONTRACT.md) | Runnable hello-world, end-to-end example, extension points, troubleshooting |
| [PROJECT.md](PROJECT.md) | Authoritative structure and architecture |
| [Architecture Design](docs/architecture/AIGC_HIGH_LEVEL_DESIGN.md) | Enforcement pipeline and design principles |
| [Integration Guide](docs/INTEGRATION_GUIDE.md) | Host system integration patterns and compliance checklist |
| [Policy DSL Spec](policies/policy_dsl_spec.md) | Full policy YAML specification |
| [Usage Guide](docs/USAGE.md) | Code examples and best practices |
