Metadata-Version: 2.4
Name: codex-govern
Version: 1.0.0
Summary: 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.
Author: Jermaine Merritt
License: MIT
Project-URL: Homepage, https://codexdominion-schemascodexdominion.vercel.app/dashboard/gateway
Project-URL: Repository, https://github.com/JermaineMerritt-ai/codexdominion-schemas
Project-URL: Documentation, https://codexdominion-schemascodexdominion.vercel.app/dashboard/gateway
Project-URL: Issues, https://github.com/JermaineMerritt-ai/codexdominion-schemas/issues
Keywords: ai-governance,openai,anthropic,llm,governance,policy,audit,compliance,evidence,ai-safety,guardrails
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Dynamic: license-file

# codex-govern

[![PyPI version](https://img.shields.io/pypi/v/codex-govern)](https://pypi.org/project/codex-govern/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)

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

```python
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

```python
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.

```python
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.

```python
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

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

### `govern.stats()` — Gateway Statistics

```python
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

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

### `govern.login(email, password)` — Authenticate

```python
govern.login("user@example.com", "password")
# Token is stored automatically — all subsequent calls are authenticated
```

### `govern.set_token(token)` — Set Token Directly

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

## Response Shape

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

```json
{
  "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

```python
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](https://codexdominion-schemascodexdominion.vercel.app/dashboard/gateway)
- [Mission Control](https://codexdominion-schemascodexdominion.vercel.app/mission-control)
- [GitHub Repository](https://github.com/JermaineMerritt-ai/codexdominion-schemas)

## License

MIT — see [LICENSE](./LICENSE) for details.
