Metadata-Version: 2.4
Name: cortexos
Version: 0.2.2
Summary: CortexOS Python SDK — hallucination detection for LLM agents
License: MIT
Project-URL: Homepage, https://cortexa.ink
Project-URL: Documentation, https://cortexa.ink/docs
Project-URL: Repository, https://github.com/Tactacion/cortexos-sdk
Project-URL: Bug Tracker, https://github.com/Tactacion/cortexos-sdk/issues
Keywords: llm,memory,attribution,rag,ai,hallucination
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2.7
Provides-Extra: tui
Requires-Dist: textual<1,>=0.80; extra == "tui"
Requires-Dist: httpx-sse<1,>=0.4; extra == "tui"
Requires-Dist: click<9,>=8; extra == "tui"
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: pytest-asyncio<1,>=0.23; extra == "dev"
Requires-Dist: respx<1,>=0.21; extra == "dev"
Dynamic: license-file

# CortexOS Python SDK

The official Python SDK for [Cortexa](https://cortexa.ink) — hallucination detection and verification for LLM agents.

## Quickstart

```bash
pip install cortexos
```

```python
import cortexos

cortexos.configure(api_key="your-key")

result = cortexos.check(
    response="The return window is 30 days",
    sources=["Return policy: 30-day window for all items."]
)
print(f"Hallucination Index: {result.hallucination_index}")
# → Hallucination Index: 0.0
```

Get an API key at [cortexa.ink](https://cortexa.ink)

## Installation

```bash
pip install cortexos
```

## Usage

### Simple API

```python
import cortexos

# Configure once
cortexos.configure(api_key="cx-...")

# Check an LLM response against source documents
result = cortexos.check(
    response="The product ships in 2-3 business days",
    sources=["Shipping: 2-3 business day delivery for all orders."]
)
print(result.hallucination_index)  # 0.0 = fully grounded
print(result.passed)               # True (HI < 0.3)

# Gate a memory before storing
gate = cortexos.gate(
    memory="Revenue grew 500% last quarter",
    sources=["Revenue grew 10% in Q4."]
)
print(gate.grounded)  # False
print(gate.flagged_claims)  # [{"text": "...", "verdict": "NUM_MISMATCH"}]
```

### Client API

```python
from cortexos import Cortex

cx = Cortex(api_key="cx-...", base_url="https://api.cortexa.ink")

result = cx.check(
    response="The return window is 30 days",
    sources=["Return policy: 30-day window for all items."],
)
print(result.hallucination_index)
```

### Async usage

```python
import asyncio
from cortexos import AsyncCortex

async def main():
    async with AsyncCortex(api_key="cx-...") as cx:
        result = await cx.check(
            response="The return window is 30 days",
            sources=["Return policy: 30-day window for all items."],
        )
        print(result.hallucination_index)

asyncio.run(main())
```

## API reference

### `Cortex` / `AsyncCortex`

| Method | Description |
|--------|-------------|
| `check(response, sources)` | Full hallucination check with per-claim verdicts |
| `gate(memory, sources)` | Gate check: should this memory be stored? |
| `health()` | Check server health |

### Top-level functions

| Function | Description |
|----------|-------------|
| `cortexos.check(response, sources)` | One-liner hallucination check |
| `cortexos.gate(memory, sources)` | One-liner gate check |
| `cortexos.configure(api_key, base_url)` | Set module-level defaults |

### Types

- **`CheckResult`** — `hallucination_index`, `total_claims`, `grounded_count`, `hallucinated_count`, `claims`, `passed`
- **`ClaimResult`** — `text`, `grounded`, `verdict`, `reason`, `source_quote`, `confidence`
- **`GateResult`** — `grounded`, `hallucination_index`, `flagged_claims`

### Errors

| Exception | When |
|-----------|------|
| `CortexError` | Base class for all SDK errors |
| `AuthError` | Invalid or missing API key (401/403) |
| `RateLimitError` | Too many requests (429); has `.retry_after` |
| `ServerError` | Unexpected 5xx from the server |

## TUI Monitor

```bash
pip install "cortexos[tui]"
cortexos monitor --api-key cx-... --url https://api.cortexa.ink
```

## Configuration

```python
cx = Cortex(
    api_key="cx-...",
    base_url="https://api.cortexa.ink",
    timeout=30.0,
    max_retries=3,
)
```

Or use environment variables:

```bash
export CORTEX_API_KEY=cx-...
export CORTEX_URL=https://api.cortexa.ink
```

## Running tests

```bash
pip install "cortexos[dev]"
pytest tests/test_client.py -v
```
