Metadata-Version: 2.5
Name: context-lineage
Version: 0.1.1
Summary: AST-grounded code lineage, progressive context, and anti-hallucination verification for AI coding agents
Project-URL: Homepage, https://github.com/swapnilwaramwar/ContextLineage
Project-URL: Repository, https://github.com/swapnilwaramwar/ContextLineage
Project-URL: Documentation, https://github.com/swapnilwaramwar/ContextLineage#readme
Project-URL: Issues, https://github.com/swapnilwaramwar/ContextLineage/issues
Author: ContextLineage Contributors
License: MIT
License-File: LICENSE
Keywords: ai-agents,anti-hallucination,ast,coding-agents,context-optimization,crewai,dbt,langchain,lineage,python,token-reduction
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.9
Provides-Extra: all
Requires-Dist: crewai>=0.28; extra == 'all'
Requires-Dist: dbt-core>=1.5; extra == 'all'
Requires-Dist: langchain-core>=0.1; extra == 'all'
Requires-Dist: langchain-text-splitters>=0.1; extra == 'all'
Requires-Dist: mypy>=1.0; extra == 'all'
Requires-Dist: pre-commit>=3.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.21; extra == 'all'
Requires-Dist: pytest-cov>=4.0; extra == 'all'
Requires-Dist: pytest>=7.0; extra == 'all'
Requires-Dist: ruff>=0.3; extra == 'all'
Provides-Extra: crewai
Requires-Dist: crewai>=0.28; extra == 'crewai'
Provides-Extra: dbt
Requires-Dist: dbt-core>=1.5; extra == 'dbt'
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1; extra == 'langchain'
Requires-Dist: langchain-text-splitters>=0.1; extra == 'langchain'
Description-Content-Type: text/markdown

<div align="center">

# 🌲 ContextLineage

**AST-Grounded Code Lineage & Progressive Context for AI Coding Agents**

*Stop burning 50,000+ tokens on full-codebase dumps. Give your agents progressive context, AST call graphs, and deterministic anti-hallucination guardrails.*

[![PyPI version](https://img.shields.io/pypi/v/context-lineage.svg?color=blue)](https://pypi.org/project/context-lineage/)
[![Python versions](https://img.shields.io/pypi/pyversions/context-lineage.svg)](https://pypi.org/project/context-lineage/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![CI Tests](https://img.shields.io/badge/Tests-83%20Passed-brightgreen.svg)](https://github.com/swapnilwaramwar/ContextLineage/actions)
[![Token Savings](https://img.shields.io/badge/Token%20Savings-63%25-orange.svg)](BENCHMARK_REPORT.md)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

</div>

---

## Setup — 2 Commands

```bash
pip install context-lineage
ctx setup src/
```

**That's it.** Claude Code, Cursor, and any other AI coding tool on your project will now automatically read a structured map of your codebase instead of guessing from raw source files.

Commit the generated files so every developer and every AI session uses them:

```bash
git add CLAUDE.md AGENTS.md .cursorrules
git commit -m "chore: add ContextLineage AI context"
```

### What `ctx setup` generates

| File | Who reads it | What it contains |
| :--- | :--- | :--- |
| `CLAUDE.md` | Claude Code (automatic) | Module map, entry points, call graph, dependency contracts |
| `.cursorrules` | Cursor (automatic) | Same structured codebase context |
| `AGENTS.md` | Any AI agent | Instructions: use `ctx verify` before writing code, read `CLAUDE.md` first |
| Git pre-commit hook | Auto-runs on every `git commit` | Keeps all files fresh — zero maintenance |

---

## Why This Exists

AI coding agents fail on real codebases in two ways:

**Context Overflow** — Dumping all source files into the prompt burns 50,000+ tokens per turn, runs up huge API bills, and causes LLM reasoning to degrade (*"Lost in the Middle"* effect).

**Context Starvation** — Reading only file names or unstructured docs causes agents to hallucinate non-existent functions, reversed caller/callee directions, and phantom circular dependencies.

`ContextLineage` fixes both. It builds a structured AST knowledge graph of your codebase and serves it progressively — giving agents exactly what they need, nothing more.

---

## What's Under the Hood

```
Your Python Codebase
        ↓
   ctx setup src/
        ↓
┌─────────────────────────────────────────┐
│  1. AST Dependency & Call Graph         │  Who calls what, what imports what
│  2. 4-Tier Progressive Disclosure       │  Overview → Summaries → Symbols → Source
│  3. Anti-Hallucination Verifier         │  verify_claim checks facts before writing
└─────────────────────────────────────────┘
        ↓
   CLAUDE.md / .cursorrules / AGENTS.md
        ↓
Claude Code / Cursor / Devin / Any Agent
```

### Progressive Disclosure (how tokens are saved)

| Level | Content | Tokens |
| :--- | :--- | :--- |
| **Level 0** | Architecture overview, entry points, leaf modules, cycle check | ~50 |
| **Level 1** | Module purpose, key exports, direct dependencies | ~120 / module |
| **Level 2** | Function signatures, caller/callee chains, semantic contracts | ~250 / symbol |
| **Level 3** | Full source code — loaded only for files being modified | Full |

---

## Additional CLI Commands

```bash
# Auto-fix docstring drift when your code changes
ctx validate src/ --fix

# Verify a claim before writing code (prevents hallucinations)
ctx verify "run_pipeline calls extract_data" -d src/

# Understand impact before refactoring
ctx query impact pipeline.stages.extract -d src/

# Trace call chains through your codebase
ctx query lineage pipeline.orchestrator -d src/

# Manually regenerate context files at any time
ctx setup src/
```

---

## Python API

```python
from pathlib import Path
from contextlineage.agent_skill import create_code_explorer_skill
from contextlineage.context_packer import create_context_packer

skill = create_code_explorer_skill(Path("src/"), token_budget=8000)
skill.initialize()

# Verify a claim against AST ground truth
result = skill.verify_claim("run_pipeline calls extract_data")
# → {"verified": True, "confidence": 0.95, "evidence": ["AST verified: ..."]}

# Pack context for LLM prompt injection
packer = create_context_packer(skill, max_tokens=8000)
packed = packer.pack_for_task("trace_dataflow", "pipeline.orchestrator")
prompt = f"Codebase context:\n{packed.to_markdown()}\n\nTask: {user_task}"
```

---

## Real-World Benchmark

Evaluated on a 17-module real-world codebase:

| Task | Naive (All Files) | ContextLineage | Savings |
| :--- | :--- | :--- | :--- |
| Architecture Overview | 6,463 tokens | 1,806 tokens | **72%** |
| Impact Analysis | 6,463 tokens | 3,288 tokens | **49%** |
| Fact Verification | 6,463 tokens | 150 tokens | **97%** |
| **Average across tasks** | **5,559 tokens** | **2,058 tokens** | **63%** |

Anti-hallucination accuracy: **100%** (6/6 true and false claims correctly classified by AST).

→ [Full benchmark details](BENCHMARK_REPORT.md)

---

## LangChain & CrewAI

```python
# LangChain
from contextlineage.integrations.langchain import FrontmatterLoader, FrontmatterRetriever
loader = FrontmatterLoader("manifest.json")
retriever = FrontmatterRetriever(loader.manifest, k=5, token_budget=8000)

# CrewAI
from contextlineage.integrations.crewai import create_frontmatter_tools
tools = create_frontmatter_tools("manifest.json")
agent = Agent(role="Code Explorer", tools=tools)
```

---

## dbt Support (Coming Soon)

ContextLineage is expanding to dbt SQL/Jinja models — parsing `{{ ref() }}` and `{{ source() }}` DAGs, extracting column contracts from `schema.yml`, and providing the same progressive disclosure for dimensional modeling projects.

→ [dbt Architecture Specification](docs/dbt-roadmap.md)

---

## Contributing

```bash
git clone https://github.com/swapnilwaramwar/ContextLineage.git
cd ContextLineage
pip install -e ".[dev]"
pytest tests/
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

<div align="center">
MIT License · Built for the age of autonomous coding agents
</div>
