chaoscypher-cortex 0.1.0__tar.gz

chaoscypher_cortex-0.1.0/PKG-INFO

@@ -0,0 +1,296 @@
+Metadata-Version: 2.4
+Name: chaoscypher-cortex
+Version: 0.1.0
+Summary: Chaos Cypher Cortex - Full-featured knowledge graph platform (processing center)
+Author-email: Denis MacPherson <denis@chaoscypher.com>
+License-Expression: AGPL-3.0-only
+Project-URL: Homepage, https://github.com/chaoscypherinc/chaoscypher
+Project-URL: Documentation, https://github.com/chaoscypherinc/chaoscypher#readme
+Project-URL: Repository, https://github.com/chaoscypherinc/chaoscypher
+Project-URL: Issues, https://github.com/chaoscypherinc/chaoscypher/issues
+Keywords: knowledge-graph,api,fastapi,ai,workflows
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: chaoscypher-core>=0.1.0
+Requires-Dist: fastapi<1,>=0.135.0
+Requires-Dist: uvicorn<1,>=0.44.0
+Requires-Dist: sqlmodel<0.1,>=0.0.38
+Requires-Dist: pydantic<3,>=2.12.0
+Requires-Dist: pydantic-settings<3,>=2.13.0
+Requires-Dist: email-validator<3,>=2.3.0
+Requires-Dist: python-dotenv<2,>=1.2.0
+Requires-Dist: dynaconf<4,>=3.2.13
+Requires-Dist: valkey<7,>=6.1.0
+Requires-Dist: python-multipart<0.1,>=0.0.24
+Requires-Dist: sse-starlette<4,>=3.3.0
+Requires-Dist: structlog<26,>=25.5.0
+Requires-Dist: mcp<2,>=1.27.0
+Requires-Dist: zxcvbn<5,>=4.5.0
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=9.0.0; extra == "dev"
+Requires-Dist: pytest-cov<8,>=7.1.0; extra == "dev"
+Requires-Dist: pytest-asyncio<2,>=1.3.0; extra == "dev"
+Requires-Dist: httpx<1,>=0.28.0; extra == "dev"
+
+# ChaosCypher Cortex
+
+**Full-featured knowledge graph backend API - Processing center**
+
+Cortex is the main backend API for ChaosCypher, providing comprehensive CRUD operations, workflow execution, document source processing, AI-powered chat, and knowledge graph management using Vertical Slice Architecture (VSA).
+
+## Features
+
+- 📊 **Knowledge Graph Management**: Full CRUD for nodes, edges, and templates
+- 💬 **AI Chat**: Conversational interface with RAG and tool use
+- 📁 **Document Source Processing**: Process PDFs, text files, CSVs into knowledge graphs
+- 🔄 **Workflow Engine**: Execute multi-step AI research workflows with triggers
+- 🔍 **Search**: FTS5 full-text + sqlite-vec vector search; multi-hop GraphRAG retrieval
+- 🔌 **MCP Server**: Expose graph operations as Model Context Protocol tools
+- ⚙️ **Settings Management**: Configure LLM providers, databases, and system settings
+- 🔐 **Single-User Auth**: nginx `auth_request` gates every API call (no admin/user split)
+- 🗄️ **Multi-Database**: Isolated workspaces with independent graphs
+
+## Architecture
+
+Cortex is part of the ChaosCypher neural architecture:
+
+- **Core** - Brain (business logic)
+- **Cortex** - Processing center (full backend) 👈 You are here
+- **Neuron** - Worker cells (background processing)
+- **Interface** - Interaction layer (UI)
+
+### Vertical Slice Architecture (VSA)
+
+Cortex uses VSA with self-contained feature slices. Each slice contains its
+own routes, service logic, and Pydantic models. The authoritative list is the
+set of directories under
+`packages/cortex/src/chaoscypher_cortex/features/`:
+
+```
+packages/cortex/src/chaoscypher_cortex/
+├── features/                 # VSA slices (chats, sources, nodes, edges,
+│                             # templates, search, llm, queue, settings,
+│                             # settings_public, workflows, triggers, tools,
+│                             # dashboard, graph, graph_snapshot, mcp, lexicon,
+│                             # backup, export, quality, counts, health,
+│                             # diagnostics, logs, pause, upgrade, edition,
+│                             # databases, local_auth, admin_plugins)
+├── shared/                   # Shared infrastructure
+│   ├── api/                 # Auth dependencies, error handling, pagination
+│   ├── database/            # Database session
+│   ├── llm/                 # LLM factory
+│   └── queue/               # Queue utilities
+└── main.py                   # FastAPI application + router registration
+```
+
+Each feature slice contains:
+- `models.py` - Pydantic DTOs (Request/Response)
+- `repository.py` - Data access layer
+- `service.py` - Business logic
+- `api.py` - REST endpoints + DI factory
+- `__init__.py` - Barrel exports
+
+## Installation
+
+```bash
+# From source (workspace sync — installs core + cortex + all dev tools)
+uv sync --all-packages --extra dev
+
+# Single-package mode (cortex + its core dep only)
+uv sync --package chaoscypher-cortex
+```
+
+The repo uses uv workspaces (see `pyproject.toml` `[tool.uv.workspace]`); `pip
+install -e` is no longer the supported install path. Install uv via
+[the official installer](https://docs.astral.sh/uv/getting-started/installation/)
+before running these commands.
+
+## Usage
+
+### Standalone
+
+```bash
+# Start Cortex server
+cc-cortex start
+
+# Custom host/port
+cc-cortex start --host 0.0.0.0 --port 8080
+
+# With environment variables
+QUEUE_HOST=localhost QUEUE_PORT=6379 cc-cortex start
+```
+
+### Docker
+
+```bash
+# Development
+docker compose -f packages/docker/multi-container/docker-compose.dev.yml up cortex
+
+# Production
+docker run -p 8080:8080 -e QUEUE_HOST=valkey -e QUEUE_PORT=6379 chaoscypher-cortex
+```
+
+### Programmatic
+
+```python
+from chaoscypher_cortex.main import create_app
+
+app = create_app()
+
+# Run with uvicorn
+import uvicorn
+uvicorn.run(app, host="0.0.0.0", port=8080)
+```
+
+## Configuration
+
+Configure via environment variables or `packages/docker/data/settings.yaml`:
+
+```bash
+# Queue (Valkey)
+QUEUE_HOST=localhost
+QUEUE_PORT=6379
+
+# Database
+CHAOSCYPHER_DATA_DIR=~/.local/share/chaoscypher
+CHAOSCYPHER_CONFIG_DIR=~/.config/chaoscypher
+
+# Logging
+LOG_LEVEL=INFO
+USE_JSON_LOGGING=false
+
+# LLM Provider
+LLM_CHAT_PROVIDER=ollama
+LLM_CHAT_MODEL=llama3.2
+LLM_EMBEDDING_PROVIDER=ollama
+LLM_EMBEDDING_MODEL=snowflake-arctic-embed2
+
+# API Keys (if using cloud providers)
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GOOGLE_API_KEY=...
+```
+
+## API Endpoints
+
+Routes live under `/api/v1/` and are gated by nginx `auth_request` (no
+register/login flow inside Cortex). The full surface includes:
+
+- **Knowledge graph** — `/nodes`, `/edges`, `/templates`, `/graph`
+- **Sources** — `/sources` (upload, list, extract, commit, citations, chunks). `SourceResponse` exposes user upload-time choices via the nested `upload_options` object (`auto_analyze`, `enable_normalization`, `enable_vision`, `content_filtering`, `filtering_mode`, `extraction_depth`, `forced_domain`), per-stage drop / merge counters via `quality_metrics` (45 typed counters + companion fields like `loader_encoding_used`), and search-index health via `quality_metrics.vector_indexing_status` (`pending` / `indexed` / `degraded` / `failed`). New persisted upload settings must round-trip through `upload_options`, never as siblings on `SourceResponse` — see `packages/docs/docs/reference/api/sources.md`.
+- **Search** — `/search` (FTS5, vector, hybrid, GraphRAG)
+- **Chat** — `/chats`, `/chats/{id}/messages`
+- **Workflows** — `/workflows`, `/workflows/{id}/execute`, `/triggers`, `/tools`
+- **Settings** — `/settings`, `/settings/reset` (plus scoped `/settings/reset/{scope}` variants)
+- **Queue** — `/queue/tasks`, `/queue/status`
+- **Operations** — `/llm/instances`, `/databases`, `/exports`, `/backup`
+- **Diagnostics** — `/health`, `/diagnostics`, `/logs`, `/pause`, `/edition`
+- **MCP** — `/mcp/sse`, `/mcp/messages`
+
+The complete reference (request/response shapes, query params, error envelopes)
+is in `packages/docs/docs/reference/api/` and at the live OpenAPI page:
+http://localhost:8080/docs (when running).
+
+## Development
+
+### Project Structure
+
+```
+packages/cortex/
+├── src/chaoscypher_cortex/
+│   ├── features/           # VSA feature slices
+│   ├── shared/             # Shared infrastructure
+│   └── main.py             # FastAPI app
+├── tests/                  # Test suite
+├── Dockerfile              # Production image
+├── Dockerfile.dev          # Development image
+└── pyproject.toml          # Package configuration
+```
+
+### Adding New Features
+
+1. Create directory: `features/{feature}/`
+2. Define DTOs: `{feature}/models.py`
+3. Create repository: `{feature}/repository.py`
+4. Create service: `{feature}/service.py`
+5. Create API + factory: `{feature}/api.py`
+6. Export: `{feature}/__init__.py`
+7. Register router in `main.py`
+
+Example:
+
+```python
+# features/my_feature/models.py
+from pydantic import BaseModel
+
+class MyFeatureRequest(BaseModel):
+    name: str
+
+class MyFeatureResponse(BaseModel):
+    id: str
+    name: str
+
+# features/my_feature/service.py
+class MyFeatureService:
+    def create(self, data: dict) -> dict:
+        # Business logic
+        return {"id": "123", "name": data["name"]}
+
+# features/my_feature/api.py
+from fastapi import APIRouter, Depends
+
+router = APIRouter(prefix="/api/v1/my-feature", tags=["My Feature"])
+
+def get_service() -> MyFeatureService:
+    return MyFeatureService()
+
+@router.post("/", response_model=MyFeatureResponse)
+def create_item(
+    request: MyFeatureRequest,
+    service: Annotated[MyFeatureService, Depends(get_service)]
+):
+    return service.create(request.model_dump())
+```
+
+### Testing
+
+```bash
+# Run all tests
+pytest
+
+# Unit tests only
+pytest -m unit
+
+# Integration tests
+pytest -m integration
+
+# With coverage
+pytest --cov=chaoscypher_cortex --cov-report=html
+```
+
+### Hot-Reload Development
+
+```bash
+# Using watchdog
+watchmedo auto-restart -d src -p '*.py' -- cc-cortex start
+
+# Using Docker
+docker compose -f packages/docker/multi-container/docker-compose.dev.yml up cortex
+```
+
+## Dependencies
+
+- **Core**: `chaoscypher-core` - Business logic
+- **FastAPI**: Web framework
+- **SQLModel**: Database ORM
+- **ARQ**: Background task queue
+- **Structlog**: Structured logging
+- **Pydantic**: Data validation
+
+## License
+
+AGPL-3.0 License - See LICENSE file for details

chaoscypher_cortex-0.1.0/README.md

@@ -0,0 +1,258 @@
+# ChaosCypher Cortex
+
+**Full-featured knowledge graph backend API - Processing center**
+
+Cortex is the main backend API for ChaosCypher, providing comprehensive CRUD operations, workflow execution, document source processing, AI-powered chat, and knowledge graph management using Vertical Slice Architecture (VSA).
+
+## Features
+
+- 📊 **Knowledge Graph Management**: Full CRUD for nodes, edges, and templates
+- 💬 **AI Chat**: Conversational interface with RAG and tool use
+- 📁 **Document Source Processing**: Process PDFs, text files, CSVs into knowledge graphs
+- 🔄 **Workflow Engine**: Execute multi-step AI research workflows with triggers
+- 🔍 **Search**: FTS5 full-text + sqlite-vec vector search; multi-hop GraphRAG retrieval
+- 🔌 **MCP Server**: Expose graph operations as Model Context Protocol tools
+- ⚙️ **Settings Management**: Configure LLM providers, databases, and system settings
+- 🔐 **Single-User Auth**: nginx `auth_request` gates every API call (no admin/user split)
+- 🗄️ **Multi-Database**: Isolated workspaces with independent graphs
+
+## Architecture
+
+Cortex is part of the ChaosCypher neural architecture:
+
+- **Core** - Brain (business logic)
+- **Cortex** - Processing center (full backend) 👈 You are here
+- **Neuron** - Worker cells (background processing)
+- **Interface** - Interaction layer (UI)
+
+### Vertical Slice Architecture (VSA)
+
+Cortex uses VSA with self-contained feature slices. Each slice contains its
+own routes, service logic, and Pydantic models. The authoritative list is the
+set of directories under
+`packages/cortex/src/chaoscypher_cortex/features/`:
+
+```
+packages/cortex/src/chaoscypher_cortex/
+├── features/                 # VSA slices (chats, sources, nodes, edges,
+│                             # templates, search, llm, queue, settings,
+│                             # settings_public, workflows, triggers, tools,
+│                             # dashboard, graph, graph_snapshot, mcp, lexicon,
+│                             # backup, export, quality, counts, health,
+│                             # diagnostics, logs, pause, upgrade, edition,
+│                             # databases, local_auth, admin_plugins)
+├── shared/                   # Shared infrastructure
+│   ├── api/                 # Auth dependencies, error handling, pagination
+│   ├── database/            # Database session
+│   ├── llm/                 # LLM factory
+│   └── queue/               # Queue utilities
+└── main.py                   # FastAPI application + router registration
+```
+
+Each feature slice contains:
+- `models.py` - Pydantic DTOs (Request/Response)
+- `repository.py` - Data access layer
+- `service.py` - Business logic
+- `api.py` - REST endpoints + DI factory
+- `__init__.py` - Barrel exports
+
+## Installation
+
+```bash
+# From source (workspace sync — installs core + cortex + all dev tools)
+uv sync --all-packages --extra dev
+
+# Single-package mode (cortex + its core dep only)
+uv sync --package chaoscypher-cortex
+```
+
+The repo uses uv workspaces (see `pyproject.toml` `[tool.uv.workspace]`); `pip
+install -e` is no longer the supported install path. Install uv via
+[the official installer](https://docs.astral.sh/uv/getting-started/installation/)
+before running these commands.
+
+## Usage
+
+### Standalone
+
+```bash
+# Start Cortex server
+cc-cortex start
+
+# Custom host/port
+cc-cortex start --host 0.0.0.0 --port 8080
+
+# With environment variables
+QUEUE_HOST=localhost QUEUE_PORT=6379 cc-cortex start
+```
+
+### Docker
+
+```bash
+# Development
+docker compose -f packages/docker/multi-container/docker-compose.dev.yml up cortex
+
+# Production
+docker run -p 8080:8080 -e QUEUE_HOST=valkey -e QUEUE_PORT=6379 chaoscypher-cortex
+```
+
+### Programmatic
+
+```python
+from chaoscypher_cortex.main import create_app
+
+app = create_app()
+
+# Run with uvicorn
+import uvicorn
+uvicorn.run(app, host="0.0.0.0", port=8080)
+```
+
+## Configuration
+
+Configure via environment variables or `packages/docker/data/settings.yaml`:
+
+```bash
+# Queue (Valkey)
+QUEUE_HOST=localhost
+QUEUE_PORT=6379
+
+# Database
+CHAOSCYPHER_DATA_DIR=~/.local/share/chaoscypher
+CHAOSCYPHER_CONFIG_DIR=~/.config/chaoscypher
+
+# Logging
+LOG_LEVEL=INFO
+USE_JSON_LOGGING=false
+
+# LLM Provider
+LLM_CHAT_PROVIDER=ollama
+LLM_CHAT_MODEL=llama3.2
+LLM_EMBEDDING_PROVIDER=ollama
+LLM_EMBEDDING_MODEL=snowflake-arctic-embed2
+
+# API Keys (if using cloud providers)
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GOOGLE_API_KEY=...
+```
+
+## API Endpoints
+
+Routes live under `/api/v1/` and are gated by nginx `auth_request` (no
+register/login flow inside Cortex). The full surface includes:
+
+- **Knowledge graph** — `/nodes`, `/edges`, `/templates`, `/graph`
+- **Sources** — `/sources` (upload, list, extract, commit, citations, chunks). `SourceResponse` exposes user upload-time choices via the nested `upload_options` object (`auto_analyze`, `enable_normalization`, `enable_vision`, `content_filtering`, `filtering_mode`, `extraction_depth`, `forced_domain`), per-stage drop / merge counters via `quality_metrics` (45 typed counters + companion fields like `loader_encoding_used`), and search-index health via `quality_metrics.vector_indexing_status` (`pending` / `indexed` / `degraded` / `failed`). New persisted upload settings must round-trip through `upload_options`, never as siblings on `SourceResponse` — see `packages/docs/docs/reference/api/sources.md`.
+- **Search** — `/search` (FTS5, vector, hybrid, GraphRAG)
+- **Chat** — `/chats`, `/chats/{id}/messages`
+- **Workflows** — `/workflows`, `/workflows/{id}/execute`, `/triggers`, `/tools`
+- **Settings** — `/settings`, `/settings/reset` (plus scoped `/settings/reset/{scope}` variants)
+- **Queue** — `/queue/tasks`, `/queue/status`
+- **Operations** — `/llm/instances`, `/databases`, `/exports`, `/backup`
+- **Diagnostics** — `/health`, `/diagnostics`, `/logs`, `/pause`, `/edition`
+- **MCP** — `/mcp/sse`, `/mcp/messages`
+
+The complete reference (request/response shapes, query params, error envelopes)
+is in `packages/docs/docs/reference/api/` and at the live OpenAPI page:
+http://localhost:8080/docs (when running).
+
+## Development
+
+### Project Structure
+
+```
+packages/cortex/
+├── src/chaoscypher_cortex/
+│   ├── features/           # VSA feature slices
+│   ├── shared/             # Shared infrastructure
+│   └── main.py             # FastAPI app
+├── tests/                  # Test suite
+├── Dockerfile              # Production image
+├── Dockerfile.dev          # Development image
+└── pyproject.toml          # Package configuration
+```
+
+### Adding New Features
+
+1. Create directory: `features/{feature}/`
+2. Define DTOs: `{feature}/models.py`
+3. Create repository: `{feature}/repository.py`
+4. Create service: `{feature}/service.py`
+5. Create API + factory: `{feature}/api.py`
+6. Export: `{feature}/__init__.py`
+7. Register router in `main.py`
+
+Example:
+
+```python
+# features/my_feature/models.py
+from pydantic import BaseModel
+
+class MyFeatureRequest(BaseModel):
+    name: str
+
+class MyFeatureResponse(BaseModel):
+    id: str
+    name: str
+
+# features/my_feature/service.py
+class MyFeatureService:
+    def create(self, data: dict) -> dict:
+        # Business logic
+        return {"id": "123", "name": data["name"]}
+
+# features/my_feature/api.py
+from fastapi import APIRouter, Depends
+
+router = APIRouter(prefix="/api/v1/my-feature", tags=["My Feature"])
+
+def get_service() -> MyFeatureService:
+    return MyFeatureService()
+
+@router.post("/", response_model=MyFeatureResponse)
+def create_item(
+    request: MyFeatureRequest,
+    service: Annotated[MyFeatureService, Depends(get_service)]
+):
+    return service.create(request.model_dump())
+```
+
+### Testing
+
+```bash
+# Run all tests
+pytest
+
+# Unit tests only
+pytest -m unit
+
+# Integration tests
+pytest -m integration
+
+# With coverage
+pytest --cov=chaoscypher_cortex --cov-report=html
+```
+
+### Hot-Reload Development
+
+```bash
+# Using watchdog
+watchmedo auto-restart -d src -p '*.py' -- cc-cortex start
+
+# Using Docker
+docker compose -f packages/docker/multi-container/docker-compose.dev.yml up cortex
+```
+
+## Dependencies
+
+- **Core**: `chaoscypher-core` - Business logic
+- **FastAPI**: Web framework
+- **SQLModel**: Database ORM
+- **ARQ**: Background task queue
+- **Structlog**: Structured logging
+- **Pydantic**: Data validation
+
+## License
+
+AGPL-3.0 License - See LICENSE file for details

chaoscypher_cortex-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["setuptools>=82.0.0,<90", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chaoscypher-cortex"
+version = "0.1.0"
+description = "Chaos Cypher Cortex - Full-featured knowledge graph platform (processing center)"
+readme = "README.md"
+license = "AGPL-3.0-only"
+authors = [
+    {name = "Denis MacPherson", email = "denis@chaoscypher.com"}
+]
+keywords = ["knowledge-graph", "api", "fastapi", "ai", "workflows"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+]
+requires-python = ">=3.14"
+dependencies = [
+    "chaoscypher-core>=0.1.0",
+    "fastapi>=0.135.0,<1",
+    "uvicorn>=0.44.0,<1",
+    "sqlmodel>=0.0.38,<0.1",
+    "pydantic>=2.12.0,<3",
+    "pydantic-settings>=2.13.0,<3",
+    "email-validator>=2.3.0,<3",
+    "python-dotenv>=1.2.0,<2",
+    "dynaconf>=3.2.13,<4",
+    "valkey>=6.1.0,<7",
+    "python-multipart>=0.0.24,<0.1",
+    "sse-starlette>=3.3.0,<4",
+    "structlog>=25.5.0,<26",
+    "mcp>=1.27.0,<2",
+    "zxcvbn>=4.5.0,<5",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0.0,<10",
+    "pytest-cov>=7.1.0,<8",
+    "pytest-asyncio>=1.3.0,<2",
+    "httpx>=0.28.0,<1",
+]
+
+[project.scripts]
+cc-cortex = "chaoscypher_cortex.main:cli"
+
+[project.urls]
+Homepage = "https://github.com/chaoscypherinc/chaoscypher"
+Documentation = "https://github.com/chaoscypherinc/chaoscypher#readme"
+Repository = "https://github.com/chaoscypherinc/chaoscypher"
+Issues = "https://github.com/chaoscypherinc/chaoscypher/issues"
+
+[tool.pytest.ini_options]
+pythonpath = ["src", "../core/src"]
+markers = [
+    "unit: pure-unit tests (no I/O, no DB, no network) — opt-in via -m unit",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+chaoscypher_cortex = ["py.typed"]

chaoscypher_cortex-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

chaoscypher_cortex-0.1.0/src/chaoscypher_cortex/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (C) 2024-2026 Chaos Cypher, Inc.
+# SPDX-License-Identifier: AGPL-3.0-only
+
+"""Knowledge Engine Backend."""

chaoscypher_cortex-0.1.0/src/chaoscypher_cortex/api/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (C) 2024-2026 Chaos Cypher, Inc.
+# SPDX-License-Identifier: AGPL-3.0-only
+
+"""API package for Chaos Cypher Cortex."""

chaoscypher_cortex-0.1.0/src/chaoscypher_cortex/api/v1/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (C) 2024-2026 Chaos Cypher, Inc.
+# SPDX-License-Identifier: AGPL-3.0-only
+
+"""API v1 package for Chaos Cypher Cortex."""