contextcraft-py 0.3.0__tar.gz

contextcraft_py-0.3.0/.env.example

@@ -0,0 +1,46 @@
+# ContextCraft — Environment Variables
+# Copy this file to .env and fill in the values.
+
+# --- Database ---
+# Railway/Heroku: DATABASE_URL is also accepted (no CONTEXTCRAFT_ prefix).
+CONTEXTCRAFT_DATABASE_URL=postgresql://contextcraft:contextcraft@localhost:5432/contextcraft
+
+# --- Embeddings & LLM (Gemini — default) ---
+CONTEXTCRAFT_GEMINI_API_KEY=your_gemini_api_key_here
+CONTEXTCRAFT_EMBEDDING_PROVIDER=gemini
+CONTEXTCRAFT_EMBEDDING_MODEL=text-embedding-004
+CONTEXTCRAFT_LLM_PROVIDER=gemini
+CONTEXTCRAFT_GEMINI_CHAT_MODEL=gemini-1.5-flash
+
+# --- OpenAI (optional alternative) ---
+# CONTEXTCRAFT_EMBEDDING_PROVIDER=openai
+# CONTEXTCRAFT_LLM_PROVIDER=openai
+# CONTEXTCRAFT_OPENAI_API_KEY=sk-your-key-here
+# CONTEXTCRAFT_OPENAI_CHAT_MODEL=gpt-4o
+
+# --- Anthropic (optional alternative LLM) ---
+# CONTEXTCRAFT_LLM_PROVIDER=anthropic
+# CONTEXTCRAFT_ANTHROPIC_API_KEY=sk-ant-your-key-here
+# CONTEXTCRAFT_ANTHROPIC_MODEL=claude-sonnet-4-20250514
+
+# --- Ollama (optional local LLM) ---
+# CONTEXTCRAFT_LLM_PROVIDER=ollama
+# CONTEXTCRAFT_OLLAMA_BASE_URL=http://localhost:11434
+# CONTEXTCRAFT_OLLAMA_MODEL=qwen2.5-coder:7b
+# CONTEXTCRAFT_OLLAMA_ALLOW_REMOTE=false
+
+# --- Cohere reranking (optional) ---
+# CONTEXTCRAFT_COHERE_API_KEY=your_cohere_key_here
+# CONTEXTCRAFT_RERANK_ENABLED=true
+
+# --- Search ---
+CONTEXTCRAFT_SEARCH_TOP_K=10
+CONTEXTCRAFT_MAX_CONTEXT_TOKENS=20000
+
+# --- API / CORS ---
+CONTEXTCRAFT_API_HOST=0.0.0.0
+CONTEXTCRAFT_API_PORT=8000
+CONTEXTCRAFT_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
+
+# --- Logging ---
+CONTEXTCRAFT_LOG_LEVEL=INFO

contextcraft_py-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Ruff lint
+        run: ruff check src/ tests/
+
+      - name: Ruff format check
+        run: ruff format --check src/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: mypy
+        run: mypy src/contextcraft/ --ignore-missing-imports
+
+  test:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_USER: contextcraft
+          POSTGRES_PASSWORD: contextcraft
+          POSTGRES_DB: contextcraft
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U contextcraft -d contextcraft"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        env:
+          CONTEXTCRAFT_DATABASE_URL: postgresql://contextcraft:contextcraft@localhost:5432/contextcraft
+          CONTEXTCRAFT_OPENAI_API_KEY: ""
+        run: pytest -v --tb=short

contextcraft_py-0.3.0/.gitignore

@@ -0,0 +1,90 @@
+# ContextCraft — Python + FastAPI + Next.js + Docker + PyPI + Railway
+
+# --- PYTHON ---
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.so
+
+# --- VIRTUAL ENVIRONMENTS ---
+.venv/
+venv/
+env/
+.uv/
+
+# --- BUILD & DISTRIBUTION ---
+dist/
+build/
+*.egg-info/
+.eggs/
+*.whl
+*.tar.gz
+MANIFEST
+
+# --- ENVIRONMENT & SECRETS ---
+.env
+.env.*
+!.env.example
+
+# --- TESTING & COVERAGE ---
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.coveragerc
+
+# --- TYPE CHECKING & LINTING ---
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+dmypy.json
+
+# --- NEXT.JS / NODE ---
+web/.next/
+web/node_modules/
+web/out/
+web/.turbo/
+web/coverage/
+*.tsbuildinfo
+
+# --- DOCKER ---
+.docker/
+docker-volumes/
+
+# --- DATABASES & LOCAL STATE ---
+*.db
+*.sqlite
+*.sqlite3
+pgdata/
+
+# --- LOGS ---
+*.log
+logs/
+
+# --- EVAL HARNESS OUTPUTS ---
+eval/results/
+eval/outputs/
+eval/*.json
+!eval/test_cases.json
+
+# --- BENCHMARK ARTIFACTS ---
+benchmark_raw/
+*.benchmark.json
+
+# --- IDE & OS ---
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# --- CLAUDE CODE ---
+CLAUDE.md
+.claude/
+
+# --- RAILWAY ---
+.railway/

contextcraft_py-0.3.0/BENCHMARK.md

@@ -0,0 +1,136 @@
+# ContextCraft — Benchmark Results
+
+Evaluated against ContextCraft's own codebase (v0.3.0).
+Eval set: 10 hand-curated questions with verified ground-truth source files.
+Date: May 19, 2026
+Embedder: Gemini Embedding 2 | Reranker: Cohere rerank-english-v3.0 | LLM Judge: Gemini 3.1 Flash Lite
+
+---
+
+## Methodology
+
+Each configuration was evaluated over **3 complete iterations** (30 total queries per
+config) to produce stable latency metrics. Before each run, the system undergoes a
+warm-up phase — one throwaway embedding and one pgvector hybrid search — to eliminate
+cold-start penalties from connection pool initialization and network overhead.
+
+**Ground truth verification:** Expected source files were determined by manual
+inspection of the codebase before any queries were run against the system. No
+system output was used to construct the test set. One test case was corrected
+mid-evaluation after discovering the original expected source (`001_init.sql`)
+pointed to a SQL migration file outside the AST parser's indexing scope — an
+honest limitation documented in the observations below.
+
+**Faithfulness scoring:** Each generated answer is evaluated by a second LLM call
+acting as a judge, asked to return `PASS` or `FAIL` based on whether the answer
+correctly covers the ground truth. This is an approximation — LLM-as-judge
+introduces its own variance, particularly with smaller models.
+
+---
+
+## Retrieval Quality
+
+| Configuration | Source Hit Rate | Faithful Answers |
+|---|---|---|
+| RRF only | **80.0%** | 73.3% |
+| RRF + Reranker | **75.0%** | 60.0% |
+| RRF + Reranker + Deps | **75.0%** | 53.3% |
+
+*Source Hit Rate: percentage of queries where at least one expected source file
+appeared in the retrieved context, position-agnostic, averaged across 3 runs.*
+
+*Faithful Answers: percentage of generated answers judged to correctly cover the
+ground truth by a second LLM call, averaged across 3 runs.*
+
+---
+
+## Latency (retrieval only, averaged over 3 runs)
+
+| Configuration | P50 | P95 |
+|---|---|---|
+| RRF only | 3,876ms | 4,340ms |
+| RRF + Reranker | 5,121ms | 6,969ms |
+| RRF + Reranker + Deps | 4,993ms | 5,621ms |
+
+*Latency measured from query embedding start to final ranked chunk list returned.
+Excludes LLM answer generation time, which is model-dependent and typically adds
+2–15 seconds.*
+
+---
+
+## Observations
+
+**RRF only is the strongest configuration on this codebase.** It achieves the
+highest source hit rate (80%) and the best faithfulness score (73.3%) at the
+lowest latency (3.88s P50). For a ~270 chunk corpus queried with factual
+architectural questions, the hybrid BM25 + vector RRF baseline is already
+well-calibrated.
+
+**The Cohere reranker adds ~1.25s P50 latency** (Cohere API round-trip) and
+did not improve source hit rate on this eval set. Hit rate dropped marginally
+from 80% to 75%. This is consistent with how cross-encoders behave on small,
+well-chunked corpora — the initial retrieval candidates are already good, and
+reranking changes their order without surfacing new files. The reranker is
+expected to show larger gains on codebases with 10K+ chunks where the initial
+candidate pool is noisier.
+
+**Faithfulness decreases with each added stage.** Adding the reranker dropped
+faithfulness from 73.3% to 60.0%, and dependency expansion brought it further
+to 53.3%. This is partly a LLM judge sensitivity issue — `gemini-3.1-flash-lite`
+is a small model that is sensitive to context ordering changes introduced by
+reranking. It is not a reliable signal that answer quality degraded for end users.
+
+**Dependency expansion is sparse on this codebase.** The graph expander fired
+on only 1 question across all 30 queries per config (question 8: SSE disconnect
+handling), expanding 1 dependency chunk from 10 source chunks each time. The
+dependency graph becomes more valuable on larger, more interconnected codebases
+where a retrieved function imports heavily from other modules.
+
+**Persistent retrieval miss — question 10.** "How are file imports attached to
+code chunks?" consistently returns 0% hit rate across all configurations. The
+expected source (`src/contextcraft/parser/ast_parser.py`) is indexed, but the
+query embedding does not match it in the top-10. This is a genuine retrieval
+gap for questions about implicit behaviour rather than named functions or classes,
+and represents a known limitation of bi-encoder retrieval.
+
+**Question 2 is a structural miss.** "What is the token limit for a single code
+chunk?" misses across all configurations because `config.py` (the expected source)
+does not surface in the top results despite containing the answer. This points to
+a vocabulary mismatch between the query and the indexed content — a candidate for
+query expansion or metadata filtering in a future iteration.
+
+---
+
+## Eval Set
+
+10 questions covering: hybrid search implementation, token limits, git blame
+caching, incremental indexing, reranker interface, language support, connection
+pooling, SSE disconnect handling, embedding storage, and import attachment logic.
+
+Full questions, expected sources, and ground truth answers: `eval/test_cases.json`
+
+---
+
+## Reproducing
+
+```bash
+# 1. Configure environment
+cp .env.example .env
+# Set CONTEXTCRAFT_GEMINI_API_KEY and CONTEXTCRAFT_COHERE_API_KEY
+
+# 2. Start database
+docker compose -f docker/docker-compose.yml up -d postgres
+
+# 3. Index the codebase
+contextcraft index .
+
+# 4. Run evaluation (all three configurations)
+python eval/run_eval.py --runs 3
+python eval/run_eval.py --rerank --runs 3
+python eval/run_eval.py --rerank --deps --runs 3
+```
+
+> **Rate limit note:** The eval harness makes 2 LLM calls per question.
+> On Gemini free tier, use `gemini-3.1-flash-lite` (500 RPD / 15 RPM) with
+> `asyncio.sleep(10)` between questions in `eval/run_eval.py` to stay within limits.
+> Each 3-run configuration takes approximately 10–12 minutes end to end.

contextcraft_py-0.3.0/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- **Gemini provider** — Default embeddings (`text-embedding-004`) and chat (`gemini-1.5-flash`) via `google-genai`; zero-cost local dev with a free AI Studio key.
+- **Production startup checks** (`startup.py`) — API lifespan verifies PostgreSQL, pgvector extension, provider API keys, and Ollama reachability when configured.
+- **Security module** (`security.py`) — Repo path validation (blocks sensitive dirs and symlink escape), query sanitization (500-char cap, control-char strip), Ollama URL SSRF guard (localhost-only unless `CONTEXTCRAFT_OLLAMA_ALLOW_REMOTE=true`).
+- **API rate limiting** — `slowapi` on `POST /ask` (10 requests/minute per IP).
+- **Configurable CORS** — `CONTEXTCRAFT_ALLOWED_ORIGINS` (comma-separated); defaults to local Next.js dev origins (not `*`).
+- **Async git subprocesses** — `git/async_git.py`; blame and log no longer block the event loop during indexing.
+- **HTTP timeouts** — Shared `http_timeouts.py` for Ollama and outbound clients (connect/read caps).
+- **PyPI packaging** — `py.typed` marker, `slowapi` runtime dependency, hatchling wheel build.
+- **Railway deploy config** — `railway.toml` with `/health` check, `restartPolicyType = on_failure`, `$PORT` binding.
+- **Docker hardening** — Multi-stage image runs as non-root `appuser`; `PORT` env respected in CMD.
+
+### Changed
+- **Default providers** — `embedding_provider` and `llm_provider` default to `gemini` (OpenAI and Anthropic remain swappable).
+- **`DATABASE_URL` alias** — Railway/Heroku-style `DATABASE_URL` accepted alongside `CONTEXTCRAFT_DATABASE_URL`.
+- **Cohere reranker errors** — Raises `RerankerUnavailableError` with RRF fallback instead of opaque failures; API emits a warning SSE event when reranking is skipped.
+- **Tree-sitter parsing** — CPU-bound `parse_file` runs in a thread pool via `parse_file_async` during async indexing.
+- **`.gitignore`** — Comprehensive stack coverage (Python, Next.js, Docker, eval outputs, IDE, Railway); `CLAUDE.md` kept local-only (not in public repo).
+
+### Fixed
+- Datetime defaults use timezone-aware `datetime.now(UTC)` (no deprecated `utcnow()`).
+- OpenAI SSE streams close cleanly on client disconnect (`CancelledError`).
+- Ollama embedder/LLM use validated base URLs and explicit timeouts.
+
+## [0.3.0] — 2026-05-17
+
+### Added
+- **Dependency graph** (`chunk_edges` table) — Static analyzer that resolves direct Python imports and class inheritance, mapping them to source and target chunk IDs with confidence scores.
+- **Context expansion** — Expands LLM context with 1-hop dependencies; cycle guard via `visited` set in `graph.expander`. Adds `--with-deps` CLI flag and `expand_deps` API parameter.
+- **Ollama LLM provider** (`qwen2.5-coder:7b`) — `OllamaLLM` via `/api/chat` with `/api/tags` connection verification and streaming support.
+- **Multi-repo search** — `hybrid_search` performs RRF normalization per repo before merging, so large repos do not drown out small ones.
+- **Multi-repo Web UI** — Repo multi-select and “Expand Graph Context” toggle in `web/src/app/page.tsx`.
+- **Multi-repo CLI/API** — `--repos` / `--all-repos` CLI flags; `repo_ids` / `all_repos` on `/ask`.
+- **Benchmark harness** — `BENCHMARK.md` and eval tooling for source hit rate and latency.
+- **Testing** — `tests/fixtures/import_ground_truth.txt` and `test_graph.py` for dependency edge generation.
+
+## [0.2.0] — 2026-05-17
+
+### Added
+- **Cohere reranker** (`rerank-english-v3.0`) — cross-encoder reranking via `reranker/` module with abstract `BaseReranker` interface. Increases retrieval pool to 60 candidates, reranks down to requested `top_k`.
+- **`--no-rerank` CLI flag** on `contextcraft ask` to bypass reranking when speed is preferred over precision.
+- **Reranker in FastAPI** — `/ask` endpoint automatically reranks when `CONTEXTCRAFT_COHERE_API_KEY` is set.
+- **RAG evaluation harness** (`eval/`) — `run_eval.py` measures source hit rate, LLM-as-a-judge faithfulness, and p50 latency across 10 benchmark queries. Includes `test_cases.json` and `README.md`.
+- **Next.js Web UI** (`web/`) — App Router, TypeScript, vanilla CSS dark-mode design:
+  - Chat interface with SSE streaming (token-by-token rendering)
+  - Repository selector dropdown
+  - Source citations with Shiki syntax highlighting, line ranges, relevance scores, and git blame metadata
+  - API proxy routes (`/api/ask`, `/api/repos`) to avoid CORS
+  - Multi-stage Dockerfile for production builds
+  - `web` service in `docker-compose.yml`
+- **Background task tracking** in FastAPI — strong references to `asyncio.Task` objects prevent GC of indexing tasks.
+
+### Changed
+- Hybrid search now fetches 60 candidates (up from 20) when reranker is enabled.
+- `pyproject.toml` — added `cohere>=5.0.0` dependency, mypy overrides, ruff ignore rules for `E501`, `W293`, `UP042`, `B905`.
+
+### Fixed
+- All `ruff check` lint errors across 36 source files.
+- All `ruff format` formatting inconsistencies across 15 files.
+- All `mypy --strict` type-check errors (21 → 0).
+- Fixed `test_imports_extracted` test after ruff removed unused import from fixture.
+- Replaced ambiguous EN DASH with hyphen in `context_builder.py`.
+
+## [0.1.0] — 2026-05-17
+
+### Added
+- **Tree-sitter AST parser** for Python, JavaScript/TypeScript, and Go — extracts functions, classes, and modules as semantic chunks (not fixed-size splits).
+- **PostgreSQL + pgvector** storage with async connection pool (asyncpg), retry logic, and full CRUD for repositories and code chunks.
+- **Hybrid search** via Reciprocal Rank Fusion (RRF) combining pgvector cosine similarity and PostgreSQL tsvector full-text search in a single SQL query.
+- **Git blame + commit history** per chunk — runs `git blame --porcelain` once per file (not per chunk) for 50x speedup.
+- **CLI** (`contextcraft index`, `contextcraft ask`, `contextcraft status`) built with Typer and Rich progress bars.
+- **FastAPI API server** with `/health`, `/repos`, `/index`, and `/ask` (SSE streaming) endpoints.
+- **Embeddings pipeline** with OpenAI `text-embedding-3-small` and Ollama support via abstract `BaseEmbedder` interface.
+- **LLM providers**: OpenAI and Anthropic Claude, swappable via config, with streaming support.
+- **Docker Compose** for local pgvector, multi-stage Dockerfile for production.
+- **GitHub Actions CI**: ruff format → ruff check → mypy `--strict` → pytest.
+- **Incremental indexing**: `--incremental` flag re-indexes only files changed since last commit.
+- **`.gitignore` / `.contextignore` support**: skips binary files, `node_modules`, etc.