Metadata-Version: 2.4
Name: cognitive-agent-substrate
Version: 0.1.0
Summary: Heterogeneous Knowledge Graph engine for structured LLM reasoning
Author: Ahmet Yigit Sertel
License-Expression: MIT
Project-URL: Homepage, https://github.com/AhmetYSertel/Cognitive-Agent-Substrate-CAS
Project-URL: Repository, https://github.com/AhmetYSertel/Cognitive-Agent-Substrate-CAS
Project-URL: Issues, https://github.com/AhmetYSertel/Cognitive-Agent-Substrate-CAS/issues
Keywords: knowledge-graph,llm,rag,embeddings,reasoning,cognitive-agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: scikit-learn>=1.4
Requires-Dist: sentence-transformers>=2.6
Requires-Dist: openai>=1.25
Provides-Extra: dev
Requires-Dist: matplotlib>=3.8; extra == "dev"
Requires-Dist: networkx>=3.3; extra == "dev"
Dynamic: license-file

# CAS — Cognitive Agent Substrate

A structured knowledge representation and retrieval system built around a **Heterogeneous Knowledge Graph (HKG)**. CAS organizes information across layered node types (L1–L5), enables graph-traversal-based reasoning, and compresses context into topology chains for efficient LLM consumption.

---

## Architecture

```
cas/
├── core.py              # HKG storage engine (SQLite + in-memory cache)
├── embeddings.py        # Embedding engine (MiniLM local / OpenAI API)
├── l4_knowledge.py      # L4: graph traversal, path convergence, topology chains
├── l5_personalization.py# L5: user profile modeling and personalized routing
└── synthetic_data.py    # Synthetic graph and data generators for experiments
```

### Node Types

| Layer | Type | Description |
|-------|------|-------------|
| L1 | `SEMANTIC` | Raw semantic chunks, embedded and clustered |
| L2 | `FACT` | Extracted facts and structured propositions |
| L3 | `TRACE` | Causal event traces and audit logs |
| L4 | `MACRO` | Generalized macro-nodes via cluster inheritance |

### Edge Types

| Type | Discount | Description |
|------|----------|-------------|
| `SEMANTIC` | 0.7 | Similarity-based links between chunks |
| `CAUSAL` | 1.0 | Directed causal relationships |
| `MACRO` | 0.9 | Cluster-level generalization edges |

---

## Experiments

Eight experiments validate the core claims of the CAS framework. Results and figures are included.

| # | Name | Key Result |
|---|------|------------|
| E1 | Epistemic Accuracy | Pearson r = 0.71 (path convergence ↔ answer quality); Top-1 accuracy 80% |
| E2 | Generalization Quality | Macro-node inheritance: precision 0.84 / recall 0.68 at threshold 0.7 |
| E3 | Compression Efficiency | Topology chains reduce token count by **72.2%** vs raw context |
| E4 | Traversal Scalability | Median latency 1.26 ms at 25K nodes / 250K edges |
| E5 | Personalization Cost | Routing savings via L5 user profiles |
| E6 | Causal Reasoning | Causal blast-radius propagation and containment |
| E7 | End-to-End Quality | L4 topology chains: judge score 4.52 vs baseline-RAG 4.36, with 22% fewer tokens |
| E8 | Personalization Quality | Cross-domain user adaptation metrics |

### Reproduce figures

```bash
python experiments/run_all.py
```

Each experiment can also be run individually:

```bash
python -m experiments.e1_epistemic.run
python -m experiments.e3_compression.run
# etc.
```

Figures are written to `experiments/<name>/figures/` and results to `experiments/<name>/results.json`.

---

## Setup

**Requirements:** Python 3.10+

```bash
pip install -r requirements.txt
```

**API key (optional — only needed for OpenAI embedding backend):**

```bash
cp .env.example .env
# edit .env and add your key
```

The default embedding backend is local MiniLM (`all-MiniLM-L6-v2`) and requires no API key.

---

## Quick Start

```python
from cas.core import HKGStore, Node, Edge, NodeType, EdgeType
from cas.embeddings import EmbeddingEngine
from cas.l4_knowledge import L4KnowledgeConsolidation

# Build a graph
store = HKGStore()
engine = EmbeddingEngine()

node = Node(node_id="n1", node_type=NodeType.L1_SEMANTIC, content="The cat is a mammal")
node.embedding = engine.encode("The cat is a mammal")[0]
store.add_node(node)

# Traverse and produce a topology chain
l4 = L4KnowledgeConsolidation(store, engine)
result = l4.query("What animals are mammals?")
print(result.chain_text)
```

---

## Experiment Results

### E1 — Epistemic Accuracy

Path convergence score reliably predicts answer quality (Pearson r = 0.71).

| Metric | Value |
|--------|-------|
| Mean answer similarity | 85.2% |
| Top-1 accuracy | 80% |
| Hit-10 accuracy | 90% |
| Mean traversal latency | 11 ms |

![E1 Convergence vs Quality](experiments/e1_epistemic/figures/convergence_vs_quality.png)
![E1 Per-Query Top-1](experiments/e1_epistemic/figures/per_query_top1.png)

### E3 — Compression Efficiency

Topology chains compress graph context to ~28% of raw token count while preserving reasoning structure.

| Metric | Value |
|--------|-------|
| Mean raw tokens | 69.8 |
| Mean chain tokens | 19.0 |
| Mean reduction | **72.2%** |

![E3 Compression](experiments/e3_compression/figures/compression.png)

### E4 — Traversal Scalability

Traversal latency stays sub-linear as graph size grows from 1K to 25K nodes.

| Nodes | Median latency | p99 latency | Memory |
|-------|---------------|-------------|--------|
| 1,000 | 0.76 ms | 2.01 ms | 1 MB |
| 5,000 | 1.17 ms | 4.07 ms | 5 MB |
| 10,000 | 1.12 ms | 2.73 ms | 10 MB |
| 25,000 | 1.26 ms | 3.16 ms | 24 MB |

![E4 Scalability](experiments/e4_scalability/figures/latency_vs_scale.png)

### E7 — End-to-End Quality

L4 topology chains match or exceed baseline RAG quality with fewer tokens.

| Condition | Judge score (/5) | Input tokens |
|-----------|-----------------|--------------|
| Baseline RAG | 4.36 | 493 |
| RAG filtered | 4.32 | 387 |
| **L4 Topology** | **4.52** | **386** |

![E7 Judge Scores](experiments/e7_endtoend/figures/judge_by_condition.png)
![E7 BERTScore](experiments/e7_endtoend/figures/bertscore_by_condition.png)

---

## Author

Ahmet Yigit Sertel — April 2026
