Metadata-Version: 2.5
Name: context-lineage
Version: 0.2.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 & Deterministic Navigation for AI Coding Agents**

*Stop burning 50,000+ tokens on full-codebase dumps. Give your agents progressive context, AST call graphs, pointer-first navigation, 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://img.shields.io/pypi/pyversions/context-lineage.svg)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![CI Tests](https://img.shields.io/badge/Tests-98%20Passed-brightgreen.svg)](https://github.com/swapnilwaramwar/ContextLineage/actions)
[![Token Savings](https://img.shields.io/badge/Token%20Savings-92%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 . <project dir>
```

**That's it.** Claude Code, Cursor, and other coding agents receive a compact command index (~219 tokens). It tells them when to run ContextLineage for live, AST-grounded pointers instead of loading a stale module dump into every session.

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) | Compact command index, entry-point summary, and live-query triggers |
| `.cursorrules` | Cursor (automatic) | Same compact command index |
| `AGENTS.md` | Any AI agent | Instructions to use `ctx verify`, `ctx query`, and `ctx pack` before asserting code facts |
| Git pre-commit hook | Auto-runs on every `git commit` | Keeps all files fresh on every commit — 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 as **actionable file:line pointers** — giving agents the exact 20–50 lines they need to inspect directly from source.

---

## What's Under the Hood

```
Your Python Codebase
        ↓
   ctx setup src/
        ↓
┌─────────────────────────────────────────┐
│  1. AST Dependency & Call Graph         │  Who calls what, what imports what
│  2. Pointer-First Navigation            │  Exact file.py:L1-L2 targets (ctx query -p)
│  3. Docstring Frontmatter Governance    │  Zero-drift CI/CD verification (ctx validate / ctx sync)
│  4. Anti-Hallucination Verifier         │  verify_claim checks facts before writing code
└─────────────────────────────────────────┘
        ↓
   CLAUDE.md / .cursorrules / AGENTS.md
        ↓
Claude Code / Cursor / Devin / Antigravity / Any Agent
```

### 2-Step Agent Navigation Workflow

```
[Agent Query]  →  ctx query symbol <name> -p  →  Returns: "engine.py:38-99 (process_claim)"
     ↓
[Targeted Read] →  Agent reads ONLY lines 38-99  →  100% verified correctness, 92% token savings
```

---

## Key CLI Commands

```bash
# 1. Pointer-first navigation (find exact file and line ranges)
ctx query symbol OrchestratorEngine.process_claim -d src/ -p

# 2. Trace call chains through your codebase with line pointers
ctx query lineage pipeline.orchestrator -d src/ -p

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

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

# 5. Auto-sync docstring YAML frontmatter across the repo in one command
ctx sync src/

# 6. Check docstring drift in CI/CD (exits 1 if drift found)
ctx validate src/
```

---

## Real-World Benchmark

Evaluated against an enterprise orchestration service:

| Paradigm | Complete & Correct Answers | Tokens Consumed | Cost Savings vs Baseline | Hallucination Risk |
| :--- | :---: | :---: | :---: | :---: |
| **1. Direct Whole-File Reads (Baseline)** | 5 / 5 | 34,073 tokens | Baseline (0%) | Low |
| **2. Query Output Alone (No Source Reads)** | 0 / 5 (2 partial, 3 abstained) | 2,614 tokens | N/A (Failed correctness) | High if agent guesses |
| **3. ContextLineage Pointer Slices** | **5 / 5 (100%)** | **2,711 tokens** | **92.0% Reduction** | **0% (Verified from source)** |

→ [Full benchmark details](BENCHMARK_REPORT.md) · [Comparison Report](COMPARISON_REPORT.md)

---

## Frequently Asked Questions

Have questions about how ContextLineage compares to Graphify, Tree-sitter tools, or how CI/CD governance works?

→ Read the [FAQ (Frequently Asked Questions)](docs/FAQ.md)

---

## 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=3000)
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=3000)
packed = packer.pack_for_task("trace_dataflow", "pipeline.orchestrator")
prompt = f"Codebase context:\n{packed.to_markdown()}\n\nTask: {user_task}"
```

---

## 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>
