Metadata-Version: 2.4
Name: cortexhub
Version: 0.5.27
Summary: CortexHub Python SDK — Runtime governance for AI systems. One decorator, any tool, any framework.
Project-URL: Homepage, https://cortexhub.ai
Project-URL: Documentation, https://docs.cortexhub.ai
Project-URL: Examples, https://github.com/CortexHub-AI/examples/
Author-email: CortexHub <hello@cortexhub.ai>
License: MIT
License-File: LICENSE
Keywords: agents,ai,authorization,governance,policy
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.13,>=3.10
Requires-Dist: cedarpy>=4.0.0
Requires-Dist: cryptography>=43.0.0
Requires-Dist: detect-secrets>=1.5.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: opentelemetry-api>=1.20.0
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0
Requires-Dist: opentelemetry-sdk>=1.20.0
Requires-Dist: presidio-analyzer>=2.2.360
Requires-Dist: presidio-anonymizer>=2.2.360
Requires-Dist: pydantic>=2.9.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: spacy-lookups-data>=1.0.0
Requires-Dist: spacy>=3.8.0
Requires-Dist: structlog>=24.4.0
Provides-Extra: agents
Requires-Dist: langchain-core>=0.3.0; extra == 'agents'
Requires-Dist: langchain-openai>=0.1.0; extra == 'agents'
Requires-Dist: langgraph>=0.2.0; extra == 'agents'
Requires-Dist: openai-agents>=0.14.0; extra == 'agents'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.34.0; extra == 'anthropic'
Provides-Extra: autogen
Requires-Dist: autogen-agentchat>=0.2.0; extra == 'autogen'
Provides-Extra: claude
Requires-Dist: anthropic>=0.34.0; extra == 'claude'
Provides-Extra: crewai
Requires-Dist: crewai>=0.76.0; extra == 'crewai'
Provides-Extra: google-adk
Requires-Dist: google-adk>=0.1.0; extra == 'google-adk'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3.0; extra == 'langchain'
Provides-Extra: langgraph
Requires-Dist: langchain-core>=0.3.0; extra == 'langgraph'
Requires-Dist: langchain-openai>=0.1.0; extra == 'langgraph'
Requires-Dist: langgraph>=0.2.0; extra == 'langgraph'
Provides-Extra: llama-index
Requires-Dist: llama-index-core>=0.11.0; extra == 'llama-index'
Provides-Extra: openai-agent
Requires-Dist: openai-agents>=0.14.0; extra == 'openai-agent'
Provides-Extra: openai-agents
Requires-Dist: openai-agents>=0.14.0; extra == 'openai-agents'
Provides-Extra: pydantic-ai
Requires-Dist: pydantic-ai>=0.0.14; extra == 'pydantic-ai'
Provides-Extra: semantic-kernel
Requires-Dist: semantic-kernel>=1.0.0; extra == 'semantic-kernel'
Description-Content-Type: text/markdown

# CortexHub Python SDK

Runtime governance for AI systems. One decorator. Any tool. Any framework.

```bash
pip install cortexhub
```

Python 3.10–3.12.

### Optional installs (match your agent stack)

Use bracket extras so peer dependencies install in one step — same shape as the [demo app](https://github.com/CortexHub-AI/examples):

| Extra | Typical use | Pair with `cortexhub.init(framework=...)` |
|-------|-------------|-------------------------------------------|
| `openai-agents` or `openai-agent` | [OpenAI Agents SDK](https://github.com/openai/openai-agents-python) | `openai_agents` |
| `langchain` | LangChain / shared `ChatModel` | `langchain` |
| `langgraph` | LangGraph + OpenAI chat models (pulls `langgraph`, `langchain-openai`, …) | `langgraph` |
| `anthropic` or `claude` | Claude / Anthropic Messages API | `anthropic`, `claude`, or `claude_agents` |
| `crewai`, `llama-index`, `autogen`, `pydantic-ai`, `semantic-kernel`, `google-adk` | Those ecosystems | `llama_index`: auto **`llm.call`** + **`cortexhub.llm.thought`** via callbacks; others: fleet label + **`cx.llm_call`** / **`record_llm_result`** / **`record_llm_thought`** unless you route via another hooked client |
| `agents` | LangGraph + OpenAI Agents together (demo-style) | Set `framework=` per vertical |

\* **Automatic `llm.call` hooks** today: **OpenAI Agents**, **LangChain / LangGraph** (`BaseChatModel.invoke` / `ainvoke`), **Anthropic** (`messages.create`, non-streaming), **LlamaIndex** (`CallbackManager` / `CBEventType.LLM`, non-streaming turn completion). Same **`@cx.tool`** governance everywhere; other stacks use **`cx.llm_call`** / **`cx.record_llm_result`** / **`cx.record_llm_thought`** or a hooked client above.

```bash
pip install 'cortexhub[agents]'   # LangGraph + OpenAI Agents (examples repo backend)
# pip also accepts: pip install 'cortexhub[langgraph,openai-agents]'
```

## Quick start

Identity comes from your **agent key** only — the control plane assigns the canonical agent id. Set `CORTEXHUB_AGENT_KEY` (or pass `agent_key=` to `init()`).

```python
import cortexhub

cx = cortexhub.init()  # requires CORTEXHUB_AGENT_KEY (or pass agent_key=)

@cx.tool(classification="write")
def process_payment(customer_id: str, amount: str, reference: str) -> dict:
    """Process a payment."""
    return payment_service.charge(customer_id, amount, reference)

# Policies, approvals, and audit trail are configured in the control plane.
```

## Configuration

| Env var | Description |
|--------|-------------|
| `CORTEXHUB_AGENT_KEY` | Agent identity secret (required for cloud enforcement) |
| `CORTEXHUB_DEBUG` | Set to `1` or `true` for readable SDK logs: tool + arguments, policy name + condition, and decision |
| `CORTEXHUB_LOG_LEVEL` | e.g. `DEBUG`, `INFO` (default `INFO`) |

### Debug logging

With `CORTEXHUB_DEBUG=1` (or `CORTEXHUB_DEBUG_POLICY=1`), the SDK logs in real time:

- **Tool encountered** — tool name and argument names/values (values redacted when privacy mode is on)
- **Policy evaluated** — policy name, condition/reasoning, and decision (allow / deny / escalate)
- **Decision** — final effect, policy, and reason for the current tool call

Useful for seeing exactly what CortexHub is evaluating and why a tool was allowed, blocked, or sent for approval.

### OpenAI Agents SDK (`llm.call` telemetry)

If you use the [OpenAI Agents SDK](https://github.com/openai/openai-agents-python), initialise with **`framework="openai_agents"`** so each model turn is captured as **`llm.call`** spans (assistant reasoning text and tool-call intent), merged automatically with any **`hooks=`** you pass to **`Runner.run`**.

```bash
pip install 'cortexhub[openai-agents]'
# or: pip install 'cortexhub[openai-agent]'
```

```python
cx = cortexhub.init(framework="openai_agents")
```

---

[Documentation](https://docs.cortexhub.ai) · [Control plane](https://app.cortexhub.ai)
