cortexos 0.2.1

CortexOS Python SDK — hallucination detection for LLM agents

CortexOS Python SDK

The official Python SDK for Cortexa — hallucination detection and verification for LLM agents.

Quickstart

pip install cortexos

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

Installation

pip install cortexos

Usage

Simple API

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

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

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

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

Configuration

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

Or use environment variables:

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

Running tests

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