aigc-sdk 0.3.1

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

AIGC — Auditable Intelligence Governance Contract

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/

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

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 import (
    enforce_invocation,
    AIGC,
    InvocationValidationError,
    PreconditionError,
    SchemaValidationError,
    GovernanceViolationError,
)

Instance-scoped enforcement (recommended for new code):

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:

  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:

  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:

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>

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.

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.

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).

# 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	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