codex-govern 1.0.0

Govern any AI call in 2 lines. Drop-in governance SDK for OpenAI, Anthropic, Google, and any LLM — policy evaluation, evidence generation, and audit-ready compliance metadata on every request.

codex-govern

Govern any AI call in 2 lines. Drop-in governance SDK for OpenAI, Anthropic, Google, and any LLM — policy evaluation, evidence generation, and audit-ready compliance metadata on every request.

pip install codex-govern

Why codex-govern?

Every AI call your application makes should be governed — policy-checked, evidence-stamped, and audit-ready. codex-govern wraps your existing AI calls with zero refactoring:

• Policy enforcement — ALLOW / DENY / REQUIRE_APPROVAL on every request
• Evidence generation — SHA-256 checksum + evidence bundle per call
• Audit trail — every request logged with model, tokens, latency, decision
• Multi-provider — OpenAI, Anthropic, Google, and more through one interface
• Minimal dependency — only requests (no heavy frameworks)
• Python 3.9+ — works everywhere Python runs

Quick Start

from codex_govern import CodexGovern

govern = CodexGovern(
    base_url="https://your-gateway.example.com",
    token="your-jwt-token",
)

# Governed chat completion — same shape as OpenAI, plus governance metadata
result = govern.chat(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Summarize the quarterly report."}],
    mission="DOCUMENT_ANALYSIS",
)

print(result["choices"][0]["message"]["content"])   # AI response
print(result["governance"]["live"])                 # True = real model call
print(result["governance"]["policyDecision"])       # "ALLOW"
print(result["governance"]["checksumSha256"])       # SHA-256 evidence hash

How It Works

Your code
  ↓
codex-govern SDK
  ↓
CodexDominion Governance Gateway
  ↓
┌─────────────────────────────────────────────┐
│ 1. Policy evaluation (allow / deny / approve)│
│ 2. Model execution (live or simulated)       │
│ 3. Evidence generation (SHA-256 checksum)    │
│ 4. Audit logging (tokens, latency, decision) │
└─────────────────────────────────────────────┘
  ↓
Response + governance metadata

API Reference

Constructor

govern = CodexGovern(
    base_url: str,              # Gateway URL
    token: str,                 # JWT auth token
    default_model: str = "gpt-4o-mini",      # Default model
    default_mission: str = "CHAT_COMPLETION", # Default mission type
    timeout: int = 30,          # Request timeout in seconds
)

govern.chat(...) — Governed Chat Completion

Send a governed chat request. Routes through Policy Engine → Model Execution → Evidence Generation.

result = govern.chat(
    messages=[{"role": "user", "content": "Hello"}],
    model="gpt-4o-mini",          # optional, uses default
    mission="CHAT_COMPLETION",    # optional, uses default
    provider="openai",            # optional, auto-detected
    temperature=0.7,              # optional
    max_tokens=1000,              # optional
    metadata={"tag": "demo"},     # optional, attached to governance record
)

govern.ask(prompt, ...) — Quick One-Liner

Returns the assistant's response content directly as a string.

answer = govern.ask("What is governed AI?")
print(answer)  # "Governed AI is..."

# With options
answer = govern.ask(
    "Explain this code",
    model="gpt-4o",
    mission="CODE_REVIEW",
    system_prompt="You are a senior engineer.",
)

govern.models() — Available Models

for m in govern.models():
    status = "LIVE" if m["live"] else "SIMULATED"
    print(f"{m['id']}: {status}")

govern.stats() — Gateway Statistics

stats = govern.stats()
print(f"{stats['totalRequests']} total, {stats['totalLive']} live")
print(f"Policy: {stats['policyBreakdown']['ALLOW']} allowed, {stats['policyBreakdown']['DENY']} denied")

govern.requests(limit=50) — Recent Requests

for r in govern.requests(limit=10):
    print(f"{r['model']} → {r['policyDecision']} ({r['latencyMs']}ms)")

govern.login(email, password) — Authenticate

govern.login("[e-mail]", "password")
# Token is stored automatically — all subsequent calls are authenticated

govern.set_token(token) — Set Token Directly

govern.set_token("your-new-jwt-token")

Response Shape

Every govern.chat() response includes standard AI fields plus governance metadata:

{
  "id": "550e8400-...",
  "model": "gpt-4o-mini",
  "choices": [
    {"message": {"role": "assistant", "content": "..."}}
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 31,
    "total_tokens": 49
  },
  "governance": {
    "governed": true,
    "live": true,
    "policyDecision": "ALLOW",
    "evidenceId": "ev-...",
    "checksumSha256": "sha256:51dbddd5...",
    "totalLatencyMs": 1293
  }
}

Error Handling

from codex_govern import CodexGovern, CodexGovernError

try:
    result = govern.chat(messages=[{"role": "user", "content": "Hello"}])
except CodexGovernError as e:
    print(f"Governance error {e.status}: {e}")
    print(f"Body: {e.body}")

Architecture

┌──────────────────────────────────────────────────────┐
│                    codex-govern SDK                   │
│        (Python 3.9+ · requests · Typed)              │
└────────────────────────┬─────────────────────────────┘
                         │ HTTPS / JWT
┌────────────────────────▼─────────────────────────────┐
│           CodexDominion Governance Gateway            │
│                                                      │
│  ┌──────────┐  ┌──────────┐  ┌───────────────────┐  │
│  │  Policy   │→│  Model   │→│     Evidence       │  │
│  │  Engine   │  │ Execution│  │   Generation       │  │
│  └──────────┘  └──────────┘  └───────────────────┘  │
│                                                      │
│  Providers: OpenAI · Anthropic · Google · More       │
└──────────────────────────────────────────────────────┘

Requirements

• Python 3.9+
• requests (only runtime dependency)

Links

• Gateway Dashboard
• Mission Control
• GitHub Repository

License

MIT — see LICENSE for details.