# SDK Reference

## What the SDK Is

`cex_sdk` is a Python package for embedding CEXAI capabilities in your own applications. It provides:

- **CEXAgent**: Build artifacts programmatically through the 8F pipeline
- **chat()**: Thin synchronous LLM call with auto-detected provider routing
- **Toolkit / @cex_tool**: Define tools that LLMs can invoke
- **Workflow**: Compose multi-step DAGs with conditions, loops, and parallelism
- **Knowledge pipeline**: Read documents (PDF, CSV, JSON, markdown, web), chunk them, embed them, and rerank results
- **Guardrails**: PII detection and prompt injection guards
- **Schema validation**: Input/output validation for artifact quality gates

Install with:

```bash
pip install -e .   # from repo root
```

---

## What the SDK Is NOT

The SDK is **not** the production CLI runtime. The 153 CLI tools in `_tools/cex_*.py` are the battle-tested runtime that powers daily builds, missions, and overnight loops. The SDK is a separate codebase designed for a different use case.

| Surface | Location | Purpose | Maturity |
|---------|----------|---------|----------|
| **CLI tools** | `_tools/cex_*.py` | Run builds, dispatch nuclei, validate, evolve -- the operational runtime | Production (150+ tools, daily use) |
| **SDK** | `cex_sdk/` | Embed CEX in your Python apps, call LLMs, build artifacts from code | Early (real core + some scaffolds) |

If you want to **use** CEXAI: start with the CLI tools and slash commands (see [cli-reference.md](cli-reference.md)).

If you want to **embed** CEXAI in a Python application: the SDK is the right entry point.

---

## Architecture

The SDK is organized into 17 packages:

```
cex_sdk/
  agent/          # CEXAgent: 8F-aware build layer
  architecture/   # Agent cards, capability registry, component maps
  config/         # Env config, feature flags, rate limits, retry policies
  eval/           # Evaluation framework (pre/post checks)
  guardrails/     # PII detection, prompt injection guard
  knowledge/      # Document readers, chunkers, embedders, rerankers
  memory/         # Memory manager, compression, stores
  models/         # LLM providers (Anthropic, OpenAI, Google, Ollama, LiteLLM, OpenRouter)
  output/         # Formatters, parsers, streaming, validators
  reasoning/      # Structured reasoning steps
  schema/         # Input schemas, data contracts, type defs, validators
  session/        # Session state management
  tests/          # SDK integrity tests
  tools/          # Toolkit base, @cex_tool decorator, MCP client, builtins
  tracing/        # Trace exporter for 8F observability
  utils/          # Logging, timer utilities
  vectordb/       # Vector store abstraction (ChromaDB adapter)
  workflow/       # Workflow engine: Step, Parallel, Loop, Condition, Router
```

---

## Core API

### CEXAgent

The main entry point for programmatic artifact building.

```python
from cex_sdk import CEXAgent

agent = CEXAgent(
    nucleus="n03",                # nucleus identity
    kind="knowledge_card",        # artifact type (optional, inferred from intent)
    model="sonnet",               # LLM alias (auto-resolves to latest); or use full slug
    repo_root=".",                # path to CEX repo
    min_score=8.0,                # minimum quality threshold
)
```

#### agent.build(intent, system="", **kwargs) -> BuildResult

Runs F1 through F8 and returns a BuildResult:

```python
result = agent.build("best practices for API rate limiting")

result.artifact       # str -- generated markdown with frontmatter
result.kind           # str -- resolved kind (e.g. "knowledge_card")
result.pillar         # str -- resolved pillar (e.g. "P01")
result.score          # float -- quality score 0-10
result.passed         # bool -- True if score >= min_score
result.trace          # str -- pipeline trace
result.errors         # list[str] -- validation errors
result.signal_path    # str | None -- signal file path
result.context_chars  # int -- total context characters injected
```

#### agent.validate(payload) -> ValidatorResult

Run F7 validation standalone. Returns `.score`, `.passed`, `.errors`.

#### agent.signal(score, status="complete") -> str

Emit an F8 completion signal manually. Returns the signal file path.

---

### chat()

Thin synchronous LLM call with auto-detected provider routing.

```python
from cex_sdk import chat

response = chat("Explain microservices in 3 sentences")
response = chat("Translate to French", model="gpt-4o", system="You are a translator.")
response = chat("Summarize this", model="llama3.1:8b")  # routes to Ollama
```

**Parameters:** `prompt` (str), `model` (str, default from nucleus_models.yaml), `provider` (str, default "auto"), `max_tokens` (int, default 4096), `system` (str).

**Auto-detection:** `claude-*` -> Anthropic, `gpt-*`/`o1-*`/`o3-*` -> OpenAI, else -> Ollama.

---

### Toolkit and @cex_tool

Define tool collections that LLMs can invoke:

```python
from cex_sdk import Toolkit, cex_tool

class SearchTools(Toolkit):
    @cex_tool(name="search_docs", description="Search the knowledge base")
    def search(self, query: str) -> str:
        return do_search(query)
```

Builtin tools: `file_tools`, `python_tools`, `shell_tools`, `web_tools` (in `cex_sdk/tools/builtin/`).

---

### Workflow

Compose multi-step workflows with DAG primitives:

```python
from cex_sdk import Workflow, Step, Parallel

wf = Workflow(name="research_and_write")
wf.add(Step(name="research", fn=research_fn))
wf.add(Parallel(steps=[Step(name="a", fn=draft_a), Step(name="b", fn=draft_b)]))
result = wf.run(context={"topic": "rate limiting"})
```

Primitives: `Step`, `Parallel`, `Loop`, `Condition`, `Router`.

---

## Package Reference

### cex_sdk.models (6 providers)

| Module | Provider | Status |
|--------|----------|--------|
| `providers/anthropic.py` | Anthropic (Claude) | Real -- production |
| `providers/openai.py` | OpenAI (GPT, o1, o3) | Real -- production |
| `providers/google.py` | Google (Gemini) | Real -- production |
| `providers/ollama.py` | Ollama (local) | Real -- production |
| `providers/litellm.py` | LiteLLM proxy | Real -- production |
| `providers/openrouter.py` | OpenRouter | Real -- production |
| `chat.py` | Unified chat() | Real -- auto-detects provider |
| `structured.py` | Structured output parsing | Real |
| `metrics.py` | Token/cost metrics | Real |

### cex_sdk.agent (8F pipeline)

| Module | Purpose | Status |
|--------|---------|--------|
| `cex_agent.py` | CEXAgent class (190 lines) | Real -- wraps full F1-F8 |
| `context_loader.py` | Load builder ISOs, KCs, brand config | Real |
| `f8_pipeline.py` | Kind/pillar resolution, system prompt assembly | Real |
| `signal_emitter.py` | F8 completion signal writer | Real |

### cex_sdk.knowledge (readers + chunkers + embedders)

| Module | Purpose | Status |
|--------|---------|--------|
| `reader/markdown.py` | Markdown reader (19 lines) | Real -- minimal |
| `reader/pdf.py` | PDF reader | Real |
| `reader/csv_reader.py` | CSV reader | Real |
| `reader/json_reader.py` | JSON reader | Real |
| `reader/web.py` | Web page reader | Real |
| `chunking/fixed.py` | Fixed-size chunking | Real |
| `chunking/recursive.py` | Recursive text splitting | Real |
| `chunking/markdown_chunking.py` | Markdown-aware chunking | Real |
| `embedder/openai_embedder.py` | OpenAI embeddings | Real |
| `embedder/ollama_embedder.py` | Ollama embeddings | Real |
| `reranker/cohere_reranker.py` | Cohere reranking | Scaffold -- requires Cohere API key |
| `document.py` | Document data class | Real |

### cex_sdk.schema (validation)

| Module | Purpose | Status |
|--------|---------|--------|
| `validator.py` | F7 quality gates (198 lines) | Real -- full H01-H07 |
| `input_schema.py` | Input validation schemas | Real |
| `data_contract.py` | Data contract definitions | Scaffold |
| `type_def.py` | Custom type definitions | Scaffold |

### cex_sdk.guardrails

| Module | Purpose | Status |
|--------|---------|--------|
| `pii.py` | PII detection (SSN, CC, email, phone, CPF, CNPJ) | Real -- 79 lines, regex-based |
| `prompt_injection.py` | Prompt injection guard | Real |

### cex_sdk.memory

| Module | Purpose | Status |
|--------|---------|--------|
| `manager.py` | Memory extraction and management (165 lines) | Real |
| `compression.py` | Memory compression | Scaffold -- interface only |
| `stores/__init__.py` | Store backends | Scaffold -- empty |

### cex_sdk.workflow

| Module | Purpose | Status |
|--------|---------|--------|
| `workflow.py` | Workflow orchestrator (116 lines) | Real |
| `step.py` | Step primitive | Real |
| `parallel.py` | Parallel execution | Real |
| `loop.py` | Loop primitive | Real |
| `condition.py` | Conditional branching | Real |
| `router.py` | Dynamic routing | Real |
| `types.py` | Shared types | Real |

### cex_sdk.tools

| Module | Purpose | Status |
|--------|---------|--------|
| `toolkit.py` | Toolkit base class (124 lines) | Real |
| `decorator.py` | @cex_tool decorator | Real |
| `function.py` | Function wrapper for tool calls | Real |
| `mcp/client.py` | MCP client integration | Scaffold |
| `builtin/file_tools.py` | File read/write tools | Real |
| `builtin/python_tools.py` | Python execution tools | Real |
| `builtin/shell_tools.py` | Shell command tools | Real |
| `builtin/web_tools.py` | Web fetch tools | Real |

### cex_sdk.output

| Module | Purpose | Status |
|--------|---------|--------|
| `formatter.py` | Output formatting (84 lines) | Real |
| `parser.py` | Output parsing | Real |
| `streaming.py` | Streaming response handler | Scaffold |
| `validator.py` | Output validation | Real |

### cex_sdk.config

| Module | Purpose | Status |
|--------|---------|--------|
| `env_config.py` | Environment config (80 lines) | Real |
| `feature_flag.py` | Feature flag management | Scaffold |
| `rate_limit.py` | Rate limit configuration | Scaffold |
| `retry_policy.py` | Retry policy definitions | Scaffold |

### cex_sdk.eval

| Module | Purpose | Status |
|--------|---------|--------|
| `base.py` | Evaluation framework (110 lines) | Real -- abstract base with pre/post check |

### cex_sdk.architecture

| Module | Purpose | Status |
|--------|---------|--------|
| `agent_card.py` | Agent card data model (100 lines) | Real |
| `capability_registry.py` | Capability index | Real |
| `component_map.py` | Component map model | Scaffold |
| `decision_record.py` | Decision record model | Scaffold |

### cex_sdk.tracing

| Module | Purpose | Status |
|--------|---------|--------|
| `exporter.py` | Trace exporter (109 lines) | Real -- writes JSON traces |

### cex_sdk.session

| Module | Purpose | Status |
|--------|---------|--------|
| `base.py` | Session state (93 lines) | Real |

### cex_sdk.reasoning

| Module | Purpose | Status |
|--------|---------|--------|
| `step.py` | Structured reasoning steps (76 lines) | Real -- requires pydantic |

### cex_sdk.vectordb

| Module | Purpose | Status |
|--------|---------|--------|
| `base.py` | Vector store abstraction | Real |
| `chroma.py` | ChromaDB adapter (79 lines) | Real -- requires chromadb |

---

## Maturity Summary

| Category | Real | Scaffold | Total |
|----------|------|----------|-------|
| Agent (8F pipeline) | 4 | 0 | 4 |
| Models (LLM providers) | 9 | 0 | 9 |
| Knowledge (readers/chunkers/embedders) | 11 | 1 | 12 |
| Schema (validation) | 2 | 2 | 4 |
| Guardrails | 2 | 0 | 2 |
| Memory | 1 | 2 | 3 |
| Workflow | 7 | 0 | 7 |
| Tools | 7 | 1 | 8 |
| Output | 3 | 1 | 4 |
| Config | 1 | 3 | 4 |
| Eval | 1 | 0 | 1 |
| Architecture | 2 | 2 | 4 |
| Tracing | 1 | 0 | 1 |
| Session | 1 | 0 | 1 |
| Reasoning | 1 | 0 | 1 |
| VectorDB | 2 | 0 | 2 |
| **Total** | **55** | **12** | **67** |

Real means the module has working logic beyond a class definition. Scaffold means it defines interfaces or data classes but has no functional implementation yet. Both are importable.

---

## Quick Start

```python
# Minimal example: build one artifact
from cex_sdk import CEXAgent

agent = CEXAgent(nucleus="n03", kind="knowledge_card")
result = agent.build("API rate limiting patterns")
print(result.score, result.passed)

# Minimal example: LLM call without the 8F pipeline
from cex_sdk import chat

answer = chat("Summarize CQRS in 3 sentences")
print(answer)

# Minimal example: tool-augmented agent
from cex_sdk import Toolkit, cex_tool

class MyTools(Toolkit):
    @cex_tool(name="lookup", description="Look up a term")
    def lookup(self, term: str) -> str:
        return f"Definition of {term}: ..."
```

Dependencies: `pip install -e .` from the repo root installs the SDK and its core dependencies. Provider-specific packages (anthropic, openai, google-genai, chromadb) are optional -- install only what you use.

---

## Known Limitations

| Area | Limitation | Workaround |
|------|-----------|------------|
| MCP client | `cex_sdk/tools/mcp/client.py` is a scaffold | Use the CLI tool `cex_preflight_mcp.py` instead |
| Memory stores | `cex_sdk/memory/stores/` is empty | Use `cex_memory.py` CLI tool for persistence |
| Streaming | `cex_sdk/output/streaming.py` is a scaffold | Use provider SDKs directly for streaming |
| Data contracts | `cex_sdk/schema/data_contract.py` is a scaffold | Define schemas in `_schema.yaml` files |
| Feature flags | `cex_sdk/config/feature_flag.py` is a scaffold | Use environment variables or YAML config |
| Cohere reranker | Requires Cohere API key | Use `cex_reranker.py` CLI tool (Haiku-based) |

The SDK is version 10.2.0 and under active development. The CLI tools (`_tools/cex_*.py`) are the production-grade runtime. Use the SDK when you need to embed CEX capabilities in your own Python applications.

---

## Contributing to the SDK

### How to promote a scaffold to real

1. Pick a scaffold module from the maturity matrix above
2. Read its base class or interface definition
3. Implement the methods with real logic
4. Add a test in `cex_sdk/tests/`
5. Run `python -m pytest cex_sdk/tests/` to verify
6. Submit a PR -- the scaffold-to-real pattern is the highest-leverage SDK contribution

### Code rules

- ASCII-only in all `.py` files (see [ASCII rule](../CLAUDE.md))
- Every module declares its kind, pillar, and 8F function in a header comment
- Provider modules must handle missing API keys gracefully (raise a clear error, do not crash silently)
- Prefer dataclasses over pydantic unless structured output parsing requires it
- No `print()` statements -- use `cex_sdk.utils.log` for all output

### Testing

```bash
python -m pytest cex_sdk/tests/                    # SDK tests
python _tools/cex_system_test.py --quick           # full system validation
```

---

## See Also

- [CLI Reference](cli-reference.md) -- the 153 operational tools
- [Concepts](concepts.md) -- 8F, 12P, GDP, kinds, nuclei
- [Quickstart](quickstart.md) -- first build walkthrough