aigc-sdk 0.1.2

Deterministic, fail-closed governance enforcement for AI model invocations.

AIGC — Auditable Intelligence Governance Contract

Reference implementation of constitutional governance for AI-assisted systems.

AIGC enforces deterministic, fail-closed policy evaluation over every model invocation — no silent fallbacks, no advisory-only checks, no prompt-based governance.

Status: Feature-complete — 180 tests, 100% coverage, all three phases shipped.

---

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

---

Installation

pip install aigc-sdk

The import name is aigc:

from aigc import enforce_invocation

From source (editable install with dev dependencies):

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:

from aigc.enforcement import enforce_invocation
from aigc.errors import (
    InvocationValidationError,
    PreconditionError,
    SchemaValidationError,
    GovernanceViolationError,
)

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 — register a sink once; every enforcement emits to it automatically:

  from aigc.sinks import JsonFileAuditSink, set_audit_sink
  set_audit_sink(JsonFileAuditSink("audit.jsonl"))
  

• Structured logging — aigc.* logger namespace with NullHandler default; host applications configure log levels and handlers

• @governed decorator — wraps sync and async LLM call sites:

  from aigc.decorators 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)
  

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:

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:

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

Documentation

Document	Purpose
Integration Contract	Runnable hello-world, end-to-end example, extension points, troubleshooting
PROJECT.md	Authoritative structure and architecture
Architecture Design	Enforcement pipeline and design principles
Integration Guide	Host system integration patterns and compliance checklist
Policy DSL Spec	Full policy YAML specification
Usage Guide	Code examples and best practices