<div align="center">

# CogniGraph

### Dev Intelligence Layer — Graphs That Think

Turn any codebase into a reasoning-ready knowledge graph.<br/>
One command. Any IDE. Any AI tool. Zero cloud infrastructure.

[![PyPI version](https://badge.fury.io/py/cognigraph.svg)](https://pypi.org/project/cognigraph/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Tests: 745 passing](https://img.shields.io/badge/tests-745%20passing-brightgreen.svg)]()
[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-8A2BE2.svg)]()
[![Patent: EP26162901.8](https://img.shields.io/badge/patent-EP26162901.8-orange.svg)](NOTICE)

</div>

---

> **What if your development environment understood your entire codebase — and kept learning?**
>
> CogniGraph transforms any codebase into a knowledge graph where every module, service, and config is a node backed by an autonomous LLM agent. Query it from any IDE, any AI tool, or plain terminal. One `pip install`, one `kogni init`, and your dev environment becomes intelligent.

---

## Quick Start

```bash
pip install cognigraph[api]
cd your-project
kogni init
```

That's it. CogniGraph scans your repo, builds a knowledge graph, and configures your IDE. Works with:

| IDE / Tool | Integration | Command |
|-----------|-------------|---------|
| **Claude Code** | MCP server + CLAUDE.md | `kogni init` (auto-detected) |
| **Cursor** | MCP server + .cursorrules | `kogni init --ide cursor` |
| **VS Code + Copilot** | MCP server + copilot-instructions | `kogni init --ide vscode` |
| **Windsurf** | MCP server + .windsurfrules | `kogni init --ide windsurf` |
| **Codex / Replit / JetBrains** | CLI + Python SDK | `kogni init --ide generic` |
| **Plain terminal** | Full CLI | `kogni init --ide generic` |
| **CI/CD pipelines** | Python SDK | `pip install cognigraph` |

No cloud account. No infrastructure. Your machine, your API keys, your data.

---

## What You Get

### CLI (any terminal, any IDE)
```bash
kogni run "What depends on the auth service?"     # Graph reasoning
kogni context auth-lambda                           # 500-token focused context
kogni inspect --stats                               # Graph statistics
kogni scan repo .                                   # Rebuild knowledge graph
kogni rebuild                                        # Rebuild chunks from source files
kogni rebuild --force                                # Force re-read ALL source files
kogni doctor                                        # Health check
kogni setup-guide                                   # Backend setup help
kogni register                                       # Register for updates (optional)
kogni activate <key>                                 # Activate team/enterprise license
kogni billing                                        # View tier & usage
```

### Python SDK (any Python environment)
```python
from cognigraph import CogniGraph

# Load graph — auto-creates backend from cognigraph.yaml config
graph = CogniGraph.from_json("cognigraph.json", config="cognigraph.yaml")

result = graph.reason("How does GDPR conflict with the AI Act?")
print(result.answer)          # Multi-agent synthesized answer
print(f"Cost: ${result.cost_usd:.4f}")  # Transparent cost tracking

# Rebuild chunks from source files (e.g., after code changes)
graph.rebuild_chunks(force=True)
```

### REST API (any HTTP client — Copilot, Postman, custom tools, bots)
```bash
# Start the server
kogni serve                          # localhost:8000

# Query from anything that speaks HTTP
curl -X POST http://localhost:8000/reason \
  -H "Content-Type: application/json" \
  -d '{"query": "What depends on the auth service?"}'
```
```json
{
  "answer": "The auth service is depended on by...",
  "confidence": 0.87,
  "cost_usd": 0.0023,
  "latency_ms": 1250.5
}
```

**Endpoints:** `/reason` (single query), `/reason/batch` (up to 50), `/graph/stats`, `/nodes/{id}`, `/health`<br/>
**Auth:** API key via `X-API-Key` header or Bearer token<br/>
**Docs:** Interactive Swagger UI at `http://localhost:8000/docs`<br/>
**Full reference:** [docs/api-reference.md](docs/api-reference.md)

### MCP Tools (Claude Code, Cursor, VS Code, Windsurf)
| Tool | Purpose |
|------|---------|
| `kogni_context` | 500-token focused context (replaces 20-60K file reads) |
| `kogni_reason` | Multi-agent graph reasoning |
| `kogni_inspect` | Graph structure inspection |
| `kogni_preflight` | Pre-change safety check |
| `kogni_impact` | "What breaks if I change X?" |
| `kogni_lessons` | Surface past mistakes before you repeat them |
| `kogni_learn` | Teach the graph new knowledge |

---

## How It Works

```
Your Codebase ──→ kogni init ──→ Knowledge Graph (cognigraph.json)
                                        │
         ┌──────────┬──────────┬────────┼────────┐
         ▼          ▼          ▼        ▼        ▼
       CLI      REST API    Python   MCP      Direct
    (terminal)  (HTTP)      SDK      Server   JSON read
         │          │          │        │        │
         ▼          ▼          ▼        ▼        ▼
    Any IDE    Any tool     Scripts  Claude   Custom
    terminal   Copilot      CI/CD   Cursor   parsers
               Postman      Jupyter VS Code
               Slack bots   Replit  Windsurf
```

**The knowledge graph is the product.** Once built, query it however you want:

| Access Method | Use When | Example |
|--------------|----------|---------|
| `kogni run` | Quick terminal query | `kogni run "what calls payments?"` |
| `kogni serve` | Any HTTP client needs access | `curl localhost:8000/reason` |
| Python SDK | Scripts, notebooks, pipelines | `graph.reason("query")` |
| MCP Server | AI-powered IDE with MCP support | Auto-available after `kogni init` |
| Read JSON | Custom integration, any language | Parse `cognigraph.json` directly |

**Model-agnostic.** Use free local models (Ollama), cloud APIs (Anthropic, OpenAI), or enterprise backends (AWS Bedrock). Smart routing sends complex queries to capable models and simple ones to cheap models, all within your cost budget.

---

## 14 Innovations (Patent EP26162901.8)

| # | Innovation | What it does |
|---|-----------|-------------|
| 1 | **ChunkScorer Activation** | Per-chunk semantic scoring — each chunk scored independently against query (v0.10.0, replaces PCST) |
| 2 | **MasterObserver** | Zero-cost transparency layer for reasoning traces |
| 3 | **Convergent Message Passing** | Agents talk until they agree, then stop |
| 4 | **Backend Fallback Chain** | Auto-fallback across models with cost budgets |
| 5 | **Hierarchical Aggregation** | Topology-aware answer synthesis |
| 6 | **SemanticSHACLGate** | 3-layer OWL-aware governance validation |
| 7 | **Constrained F1** | Joint quality + governance evaluation metric |
| 8 | **OntologyGenerator** | Auto-generate OWL+SHACL from documents |
| 9 | **Adaptive Activation** | Dynamic node selection from query complexity |
| 10 | **Online Graph Learning** | Bayesian edge weight updates from usage |
| 11 | **LoRA Auto-Selection** | Per-entity adapter matching |
| 12 | **TAMR+ Connector** | Retrieval-to-reasoning pipeline |
| 13 | **Multi-Resolution Embeddings** | Hybrid skill matching (regex + semantic) |
| 14 | **CypherActivation** | Neo4j vector search on chunk embeddings — bypasses graph algorithms entirely (opt-in) |

All 14 innovations are **free for every developer**. No license key required.

---

## Backends

| Backend | Models | Cost | Install |
|---------|--------|------|---------|
| **Ollama** | Any local model (Qwen, Llama, etc.) | **$0** (local) | `pip install cognigraph[api]` |
| **Anthropic** | Claude Haiku / Sonnet / Opus | $5 free credits | `pip install cognigraph[api]` |
| **OpenAI** | GPT-4o / GPT-4o-mini | $5 free credits | `pip install cognigraph[api]` |
| **AWS Bedrock** | Claude, Titan, Llama, Mistral | AWS Free Tier | `pip install cognigraph[api]` |
| **vLLM** | GPU inference + LoRA | $0 (your GPU) | `pip install cognigraph[gpu]` |
| **llama.cpp** | CPU GGUF models | $0 (your CPU) | `pip install cognigraph[cpu]` |

```bash
kogni setup-guide              # See all options with setup steps
kogni setup-guide ollama       # Free, local, no API key needed
kogni setup-guide anthropic    # Best quality, $5 free credits
kogni doctor                   # Verify everything works
```

---

## Pricing — 100% Free for Developers

CogniGraph follows the **open-core model**: everything a solo developer needs is free forever. We monetize team and enterprise collaboration features.

| | Community (Free) | Team | Enterprise |
|---|:---:|:---:|:---:|
| **Price** | **$0 forever** | $29/dev/month | Custom |
| All 14 innovations | ✓ | ✓ | ✓ |
| All MCP tools (7 tools) | ✓ | ✓ | ✓ |
| All backends (Ollama, Anthropic, OpenAI, Bedrock, vLLM) | ✓ | ✓ | ✓ |
| CLI + Python SDK + REST API | ✓ | ✓ | ✓ |
| Unlimited queries | ✓ | ✓ | ✓ |
| Auto-growing knowledge graph | ✓ | ✓ | ✓ |
| Session continuity workspace | ✓ | ✓ | ✓ |
| SemanticSHACL governance | ✓ | ✓ | ✓ |
| Multi-IDE support | ✓ | ✓ | ✓ |
| Commercial use | ✓ | ✓ | ✓ |
| Shared KG sync across team | — | ✓ | ✓ |
| Multi-developer coordination | — | ✓ | ✓ |
| Team analytics & insights | — | ✓ | ✓ |
| Custom ontologies | — | ✓ | ✓ |
| Private deployment | — | — | ✓ |
| Compliance & audit trail | — | — | ✓ |
| SLA support | — | — | ✓ |

**Why free?** We believe every developer deserves intelligent tooling regardless of budget. The innovations that save you tokens and time should not be behind a paywall. Teams pay for collaboration — individuals never pay.

---

## Benchmarks

| Metric | CogniGraph | Single-Agent Baseline | Improvement |
|--------|-----------|----------------------|-------------|
| Constrained F1 | **0.757** | 0.328 | **+131%** |
| Governance Accuracy | **99.7%** | N/A | — |
| Token Efficiency | **500 tokens/query** | 20-60K tokens | **40-120x** |

---

## Governance

The **SemanticSHACLGate** enforces 3-layer semantic validation on every reasoning output:

1. **Framework Fidelity** — agents cite correct regulatory frameworks
2. **Scope Boundary** — responses stay within assigned domain
3. **Cross-Reference Integrity** — proper attribution across domains

**MultiGov-30 benchmark: 99.7% governance accuracy** (FF: 100%, SB: 100%, CR: 98.3%).

---

## Patent & IP Notice

CogniGraph implements methods described in **European Patent Application EP26162901.8** (filed 6 March 2026, Quantamix Solutions B.V.). See [NOTICE](NOTICE) for details.

All 14 innovations are free to use under Apache 2.0. The patent protects the specific methods — you can use CogniGraph freely in any project, commercial or otherwise.

---

## What's New in v0.10.1

**Innovation table updated** — README now accurately reflects v0.10.0 architecture:

- **Innovation #1 updated:** "PCST Activation" → **"ChunkScorer Activation"** — per-chunk semantic scoring is the actual default since v0.10.0
- **Innovation #14 added:** **"CypherActivation"** — Neo4j vector search on chunk embeddings, bypasses graph algorithms entirely (opt-in, shipped in v0.9.0)
- **Innovation count:** 13 → **14** (updated across all references)

---

## What's New in v0.10.0

**ChunkScorer replaces PCST as default activation** — The #1 blocker (Bug 1, P0) is fixed:

- **ChunkScorer (new default):** Each chunk gets its own embedding and is scored independently against the query. A query about "ProductList function" directly matches the chunk containing that function, regardless of what else the file contains. No more activating `tailwind.config.ts` instead of `Products.tsx`.
- **PCST demoted to legacy:** Still available via `strategy: "pcst"` in config, but no longer the default. PCST's graph-structure bias toward hub nodes was fundamentally wrong for code search.
- **Multiple nodes activated:** ChunkScorer returns all nodes above `min_score` threshold (configurable), not just 1. Message-passing between agents actually works now.
- **Bug 7 fix:** Bedrock auth detection now uses `boto3.Session().get_credentials()` — works with IAM profiles, SSO, env vars, and `~/.aws/credentials`.
- **Bug 9 fix:** Added control character escaping to JSON repair chain (LLMs produce literal newlines in strings).
- **Bug 19 fix:** `ReasoningResult.content` backward-compat property added (alias for `.answer`).
- **Default strategy changed:** `activation.strategy` defaults to `"chunk"` (was `"pcst"`).

**9 new tests** for ChunkScorer. **745 tests passing** (up from 736).

---

## What's New in v0.9.0

**Neo4j Backend + Critical Bug Fixes** — CogniGraph now supports Neo4j as a first-class backend alongside JSON/NetworkX:

- **Neo4j backend:** `CogniGraph.from_neo4j()` / `to_neo4j()` for loading and exporting graphs
- **CypherActivation:** Vector search on chunk embeddings via Cypher replaces PCST for Neo4j mode — faster and more accurate node activation
- **Schema management:** `create_schema()` creates constraints + vector index on `:Chunk` nodes
- **Chunk-level storage:** `:CogniNode`→`:HAS_CHUNK`→`:Chunk` with optional embeddings
- **Bug 1 (P0) fix:** Chunk-aware scoring now uses 500 chars from top 5 chunks with function/class prioritization (was 200 chars from 3 chunks)
- **Bug 18 fix:** Confidence calibration now uses relevance-weighted scoring instead of simple averaging
- **Bug 7 fix:** Bedrock `api_key_env` corrected to `AWS_ACCESS_KEY_ID`
- **Bug 9 fix:** JSON repair now strips comments before fixing quotes/commas
- **Bug 14 fix:** `out/` directory added to scan skip list
- **Bug 16 fix:** SkillAdmin embedding log messages no longer repeat per query
- **Bug 17 fix:** `kogni doctor` checks both `kogni` and `cognigraph` MCP keys

**37 new tests** (8 chunk scoring + 5 confidence calibration + 13 Neo4j connector + 7 CypherActivation + 4 graph Neo4j). **736 tests passing** (up from 699).

---

## What's New in v0.8.0

**Context-Aware Query Reformulator (ADR-104)** — Queries are now automatically enhanced with conversation context before PCST activation:
- Auto-hardened in Claude Code / Cursor / Codex (zero extra cost — uses existing conversation context)
- Pronoun resolution: "what does this do?" → resolves "this" from chat history
- Attachment support: screenshots, error logs, diagrams are described and woven into queries
- File + symbol injection: current file and active symbols ground vague queries
- LLM mode for standalone SDK users (configurable, optional)
- Fail-open: if reformulation fails, original query passes through unchanged

**49 new tests** for query reformulation. **699 tests passing** (up from 650).

---

## What's New in v0.7.9

**Content-Aware PCST Activation (ADR-103)** — 3-layer fix ensures PCST always selects content-bearing nodes over empty structural connectors (directories, namespaces):
- Layer 1: `log₂(2 + chunk_count)` content richness multiplier in relevance scoring
- Layer 2: Post-PCST filter replaces zero-chunk nodes with content-bearing neighbours
- Layer 3: Direct file lookup bypass when query mentions a specific filename

**6 Bug Fixes:**
- Bedrock config writes `region` instead of `api_key` (P2)
- `kogni grow --full` respects SKIP_DIRS exclusions (P2)
- `kogni doctor` detects MCP registration for all IDEs (P2)
- `kogni init` prompts before overwriting cognigraph.yaml (P3)
- SkillAdmin duplicate logging prevented (P3)
- 33 new tests for content-aware PCST activation

**650 tests passing** (up from 617).

---

## What's New in v0.7.7

**Chunk Pipeline (breaking fix)** — Every node now auto-loads evidence chunks from source files at graph load time. Hand-built KGs that previously had zero chunks now get full evidence for reasoning. New `kogni rebuild` command and `graph.rebuild_chunks()` API.

**13 Bug Fixes** — All issues from end-to-end testing resolved:
- Agents no longer refuse queries with "outside my domain" (P0)
- REST API Pydantic forward reference crash fixed (P0)
- Server auto-creates real backend from config instead of MockBackend (P0)
- `from_json()` accepts config path as string (P1)
- Auto-backend creation when no backend set (P1)
- Bedrock cross-region inference profile guidance (P2)
- Metrics no longer double-count token savings (P2)
- JSON repair for LLM ontology generation (5 strategies) (P2)
- NetworkX FutureWarning suppressed (P3)
- MCP server reports correct version (P3)

**Lead Generation** — `kogni register`, `kogni activate`, `kogni billing` commands. Stripe webhook handler for automated license delivery.

**617 tests passing** (up from 554).

---

## Citation

```bibtex
@article{kumar2026cognigraph,
  title   = {CogniGraph: Governed Intelligence through Graph-of-Agents Reasoning
             over Knowledge Graph Topologies with Semantic SHACL Validation},
  author  = {Kumar, Harish},
  year    = {2026},
  institution = {Quantamix Solutions B.V.},
  note    = {European Patent Application EP26162901.8},
  url     = {https://github.com/quantamixsol/cognigraph}
}
```

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and PR guidelines.

## License

[Apache 2.0](LICENSE) — use it commercially, modify it freely, just keep the attribution.
