Metadata-Version: 2.4
Name: aperion-cortex
Version: 0.1.0
Summary: The Cortex - Unified memory and state management service for Aperion
Project-URL: Homepage, https://github.com/aperion-ai/aperion-state-gateway
Project-URL: Documentation, https://github.com/aperion-ai/aperion-state-gateway#readme
Project-URL: Repository, https://github.com/aperion-ai/aperion-state-gateway
Author-email: Aperion Team <team@aperion.ai>
License: MIT
License-File: LICENSE
Keywords: ai,context,memory,state-management,vector-search
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: chromadb>=0.4.0
Requires-Dist: fastapi>=0.109.0
Requires-Dist: httpx>=0.26.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: python-jose[cryptography]>=3.3.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: structlog>=24.1.0
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: uvicorn[standard]>=0.27.0
Provides-Extra: dev
Requires-Dist: httpx>=0.26.0; extra == 'dev'
Requires-Dist: mypy>=1.7.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: huggingface
Requires-Dist: sentence-transformers>=2.2.0; extra == 'huggingface'
Provides-Extra: openai
Requires-Dist: openai>=1.6.0; extra == 'openai'
Description-Content-Type: text/markdown

# Aperion State Gateway — "The Cortex"

> Unified memory and state management service for the Aperion AI platform.

The Cortex separates **Reasoning** (transient LLM processing) from **Memory** (persistent storage), providing a centralized service for context packing, vector search, and the event ledger.

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        THE CORTEX                                │
│                     (Port 4949)                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │   HOT       │  │   WARM      │  │         COLD            │  │
│  │   STATE     │  │   CONTEXT   │  │        STORAGE          │  │
│  │             │  │             │  │                         │  │
│  │ - Sessions  │  │ - Token     │  │ - Vector DB (Chroma)    │  │
│  │ - Fast KV   │  │   Packing   │  │ - SQLite Archives       │  │
│  │ - TTL Cache │  │ - LLM-ready │  │ - Training Ledger       │  │
│  │             │  │   Output    │  │                         │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
                            │
                            ▼
            ┌───────────────────────────────┐
            │     API Endpoints (REST)      │
            │                               │
            │  GET  /state/snapshot         │
            │  POST /vector/search          │
            │  GET  /db/schema/{name}       │
            │  POST /audit/record           │
            │  GET  /events/stream (SSE)    │
            └───────────────────────────────┘
```

## Memory Tiering

### Hot State
Active session data with low-latency access. In-memory with optional Redis backend.

### Warm Context
The "Context Window" manager. Accepts raw messages/files and returns a token-optimized `ContextPack` ready for the LLM.

### Cold Storage
Long-term persistence via Vector DB (ChromaDB/FAISS) and SQLite.

## Quick Start

```bash
# Install dependencies
pip install -e ".[dev]"

# Run the service
aperion-cortex --port 4949

# Or with uvicorn directly
uvicorn aperion_cortex.service.app:app --host 0.0.0.0 --port 4949
```

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/state/snapshot` | GET | Returns signed ContextPack |
| `/vector/search` | POST | Semantic search |
| `/db/list` | GET | List databases |
| `/db/schema/{name}` | GET | Database introspection |
| `/audit/record` | POST | Log agent execution |
| `/events/stream` | GET | SSE event stream |
| `/healthz` | GET | Health check |

## Docker

```bash
docker build -t aperion-cortex .
docker run -p 4949:4949 aperion-cortex
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `CORTEX_PORT` | `4949` | Service port |
| `CORTEX_SIGNING_KEY` | (required) | Key for signing ContextPacks |
| `CORTEX_DB_PATH` | `data/cortex.db` | SQLite database path |
| `CORTEX_VECTOR_BACKEND` | `chroma` | Vector store: `chroma` or `faiss` |
| `CORTEX_EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Sentence transformer model |
| `CORTEX_LOG_LEVEL` | `INFO` | Logging level |

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=aperion_cortex --cov-report=html

# Lint
ruff check src tests

# Type check
mypy src
```

## License

MIT
