contextpilot-ai 0.1.0__tar.gz

contextpilot_ai-0.1.0/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(curl -s https://pypi.org/pypi/contextpilot/json)",
+      "Bash(python -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\(d['info']['name'], d['info']['version'], d['info']['author']\\)\")"
+    ]
+  }
+}

contextpilot_ai-0.1.0/.cursor/agents/changelog-archivist.md

@@ -0,0 +1,24 @@
+---
+name: changelog-archivist
+description: Maintains accurate records of code changes. Use when finishing a feature, before commits/PRs, or when the user asks for a changelog, release notes, or summary of what changed.
+model: inherit
+readonly: false
+---
+
+You track **what** changed in code and **why**, without rewriting unrelated code.
+
+When invoked:
+
+1. Inspect `git diff`, recent edits, or the described scope; list touched files and areas (modules, public APIs).
+2. Classify changes: feat / fix / refactor / perf / chore / docs — match the project’s existing changelog style if `CHANGELOG.md` exists.
+3. Produce a concise entry: date, bullet points with user-visible impact first, then internal/technical notes.
+4. Write the entry to a new file in `Logs/` — not a root `CHANGELOG.md`. Naming convention:
+   - Phase work → `Logs/phase-N-<slug>.md`
+   - Feature additions → `Logs/feat-<slug>.md`
+   - Bug fixes / refactors → `Logs/fix-<slug>.md`
+   Each file must include: date, changed items, FR references, and conventional commit lines.
+5. Optionally draft a conventional commit subject line (e.g. `feat(scope): …`) aligned with the actual diff.
+
+Do not invent changes not present in the diff or conversation. Ask only if scope is ambiguous.
+
+When describing library or dashboard behavior, you may reference **FR-xxx** IDs from `Doc/contextpilot_functional_doc.docx` if they clearly match the change.

contextpilot_ai-0.1.0/.cursor/agents/structure-guardian.md

@@ -0,0 +1,18 @@
+---
+name: structure-guardian
+description: Improves and preserves clean architecture—modules, boundaries, naming, and readability. Use when refactoring for clarity, removing duplication, or when code feels messy or tightly coupled.
+model: inherit
+readonly: false
+---
+
+You keep the codebase **structured and readable**, not sprawling or clever-at-the-cost-of-clarity.
+
+When invoked:
+
+1. Map the relevant area: entry points, layers (e.g. SDK wrapper vs strategies vs telemetry), and dependencies. Prefer matching existing folder and naming patterns.
+2. Identify problems: oversized files, mixed concerns, unclear public APIs, circular imports, dead code, inconsistent naming.
+3. Propose **minimal, staged** refactors: extract modules or types, clarify boundaries, shorten functions—each step should preserve behavior.
+4. Avoid drive-by changes outside the requested scope; no cosmetic-only churn across unrelated files.
+5. After structural edits, note risks (breaking API, migration steps) and how to verify (tests, smoke paths).
+
+ContextPilot lens: align with the **package layout and boundaries** in `Doc/contextpilot_technical_doc.docx` (§5)—`wrapper.py`, `analyzer.py`, `compressor.py`, `strategies/`, `quality.py`, `shadow.py`, `telemetry.py`, `config.py`, `adapters/`—and keep dashboard concerns separate from the core library unless the task is explicitly full-stack.

contextpilot_ai-0.1.0/.cursor/agents/workstream-coordinator.md

@@ -0,0 +1,18 @@
+---
+name: workstream-coordinator
+description: Splits large work into parallel or sequential streams with clear ownership and handoffs. Use for multi-module tasks, epics, or when the user asks to distribute workload across agents or subtasks.
+model: inherit
+readonly: false
+---
+
+You **decompose work** so multiple contributors or subagents can execute without overlap or gaps.
+
+When invoked:
+
+1. Restate the goal and constraints (deadline, must-not-break areas, tech stack). For roadmap-sized work, align streams with **phase boundaries** in `Doc/contextpilot_functional_doc.docx` (§7) when helpful.
+2. Split into **independent workstreams** where possible (different directories, layers, or features). Mark dependencies: A before B, or parallelizable.
+3. For each stream, specify: scope, inputs needed, deliverables, verification (tests, commands), and merge order if conflicts are likely.
+4. Name suggested delegations explicitly (e.g. “Stream A: exploration”, “Stream B: implementation in `packages/foo`”) so the parent agent can launch Task/subagents in parallel where safe.
+5. Flag shared interfaces or contracts that must be agreed first to avoid integration churn.
+
+Keep the plan actionable and short; avoid duplicate instructions across streams.

contextpilot_ai-0.1.0/.cursor/rules/clean-structure.mdc

@@ -0,0 +1,12 @@
+---
+description: Keeps refactors scoped and structure clean
+globs: "**/*.{ts,tsx,js,jsx,py,rs,go}"
+alwaysApply: false
+---
+
+# Structure and cleanliness
+
+- One primary responsibility per file; extract when a file mixes unrelated concerns.
+- Match existing naming and folder layout in the touched area.
+- Refactor in **minimal steps**; do not rename or reformat unrelated symbols.
+- Prefer explicit module boundaries over cross-layer imports “for convenience.”

contextpilot_ai-0.1.0/.cursor/rules/contextpilot-project.mdc

@@ -0,0 +1,30 @@
+---
+description: ContextPilot plan alignment—docs, privacy, layering, 4 surfaces
+alwaysApply: true
+---
+
+# ContextPilot
+
+**Plan**: `Doc/contextpilot_functional_v12.docx`, `Doc/contextpilot_technical_v12.docx`, diagram `Doc/contextpilot_full_system_architecture.svg`.
+
+Open-source **Python 3.10+** middleware that deploys across four surfaces sharing one compression engine:
+
+| Surface | Entry point |
+|---------|-------------|
+| Python library | `contextpilot.wrap(client)` |
+| Local proxy | `contextpilot proxy --port 8432` + `ANTHROPIC_BASE_URL` |
+| MCP server | `contextpilot mcp` |
+| CLI migration | `contextpilot migrate ./src/` |
+
+Pipeline: intercept payload → analyze (staleness, redundancy, relevance, density) → compress (history summarizer, system prompt dedup, RAG pruning, structural stripping, agent memory) → **quality gate** (default threshold **85**; fallback to uncompressed) → forward via provider adapters → **telemetry metadata only** (no prompts/responses/PII).
+
+## Non-negotiables
+
+- Telemetry: numerical fields only (see technical doc §7 schema); TLS to dashboard; failure → silent drop/retry, library keeps working.
+- Library must stay usable **without** dashboard connectivity.
+- Each surface is a thin shell — the compression engine is surface-agnostic.
+- Customer is whoever pays the LLM API bill and controls the code — not end users of ChatGPT/Claude.ai.
+
+## Structure target
+
+Mirror the technical doc package tree: `wrapper`, `analyzer`, `compressor`, `strategies/*`, `quality`, `shadow`, `telemetry`, `config`, `adapters/*`, optional `_rust`. Dashboard lives in `dashboard/` — keep it separate from the core library.

contextpilot_ai-0.1.0/.cursor/skills/log-code-changes/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: log-code-changes
+description: Produces changelog entries, release notes bullets, and conventional commit lines from git diffs or described work. Use when the user asks to log changes, write CHANGELOG entries, or summarize what changed before commit or release.
+disable-model-invocation: true
+---
+
+# Log code changes
+
+## Steps
+
+1. Determine scope: staged only (`git diff --cached`), working tree (`git diff`), or branch (`git diff main...HEAD`).
+2. Group by concern (feature area, bugfix, refactor). Map files to user-visible outcomes when possible.
+3. Output:
+   - **Changelog block** (bullets, semver section if applicable).
+   - **Commit suggestion**: `type(scope): summary` (Conventional Commits).
+
+## Rules
+
+- Never claim changes not evidenced by diff or explicit user list.
+- Prefer linking to issue IDs if the user provides them.

contextpilot_ai-0.1.0/.cursor/skills/parallel-work-plan/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: parallel-work-plan
+description: Breaks a task into parallel tracks with dependencies and verification. Use when splitting work across subagents, streams, or developers, or when the user asks how to divide a large task.
+disable-model-invocation: true
+---
+
+# Parallel work plan
+
+## Output template
+
+```markdown
+## Goal
+[One sentence]
+
+## Streams
+| ID | Scope | Parallel? | Depends on | Done when |
+|----|-------|-----------|------------|-----------|
+
+## Contracts (define first)
+- Shared types/APIs: ...
+
+## Merge order
+1. ...
+```
+
+## Guidance
+
+- Maximize parallelism only where files and APIs do not collide.
+- Put risky or ambiguous contracts in “define first” before parallel implementation.

contextpilot_ai-0.1.0/.gitignore

@@ -0,0 +1,67 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.pyo
+*.pyd
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+.env/
+
+# Testing & coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pytype/
+
+# Ruff / linting cache
+.ruff_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb
+
+# Secrets & local config (never commit API keys)
+.env
+.env.local
+*.env
+contextpilot.yaml
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# IDEs
+.vscode/
+.idea/
+*.suo
+*.user
+
+# Rust build artefacts (optional _rust/ accelerator)
+target/
+Cargo.lock
+
+# Dashboard (separate surface, may have its own build output)
+dashboard/node_modules/
+dashboard/.next/
+dashboard/dist/

contextpilot_ai-0.1.0/AGENTS.md

@@ -0,0 +1,13 @@
+# Agents overview (Cursor subagents)
+
+**Product/engineering plan**: `Doc/contextpilot_functional_v12.docx`, `Doc/contextpilot_technical_v12.docx`, and `Doc/contextpilot_full_system_architecture.svg`.
+
+Project-defined subagents live in `.cursor/agents/`:
+
+| Agent | Role |
+|-------|------|
+| `changelog-archivist` | Document what changed (changelog, release notes, commit lines). |
+| `structure-guardian` | Refactor and organize code for clarity and stable boundaries. |
+| `workstream-coordinator` | Split big tasks into streams for parallel work or delegation. |
+
+See `CLAUDE.md` for usage notes, the 4 integration surfaces, and architecture reference.

contextpilot_ai-0.1.0/CLAUDE.md

@@ -0,0 +1,133 @@
+# ContextPilot — AI assistant context
+
+## Authoritative plan documents (`Doc/`)
+
+Treat these as the product and engineering source of truth:
+
+| Document | Contents |
+|----------|----------|
+| `Doc/contextpilot_functional_v12.docx` | Customer definition, market analysis, 4 integration surfaces, AI-native distribution strategy, FR-001–FR-011, dashboard FRs FR-101+, user stories, roadmap phases, pricing, KPIs |
+| `Doc/contextpilot_technical_v12.docx` | Architecture, 4-surface data flow, compression strategies, tech stack, package layout, API/config examples, telemetry schema, performance targets, security |
+| `Doc/contextpilot_full_system_architecture.svg` | Visual system architecture |
+
+If instructions conflict, prefer the **Word specs**, then this file, then ad‑hoc chat.
+
+---
+
+## Product snapshot
+
+**ContextPilot** is an **MIT open-source Python library** that deploys across **four surfaces**:
+
+| Surface | Entry point | Who it serves |
+|---------|-------------|---------------|
+| **A — Python library** | `pip install contextpilot` + `contextpilot.wrap(client)` | Backend developers building AI products |
+| **B — Local proxy server** | `contextpilot proxy --port 8432` + `ANTHROPIC_BASE_URL` | AI coding tool users (Claude Code, GPT Codex, Aider) |
+| **C — MCP server** | `contextpilot mcp` | Claude Desktop / Claude Code users |
+| **D — CLI migration agent** | `contextpilot migrate ./src/` | Existing codebases with 50+ LLM API calls |
+
+All surfaces share the same compression engine. The customer is always the entity that **pays the LLM API bill AND controls the code that makes the calls** — not end users of ChatGPT or Claude.ai.
+
+The library intercepts LLM API calls, analyzes token payloads, runs a **compression pipeline**, applies a **quality gate** (fallback to original if score < threshold), optionally runs **A/B shadow testing**, and emits **metadata-only telemetry**. Monetization is an **optional hosted dashboard** — repo focus is the **core library** unless work explicitly targets `dashboard/`.
+
+**AI-native distribution**: AI coding assistants (Claude, GPT) are a primary distribution channel — generated code includes `import contextpilot`. The 5 channels are: custom agents/system prompts, MCP server auto-integration, CLI migration agent, starter templates, and IDE snippets.
+
+---
+
+## Engineering principles (from technical architecture)
+
+- **Zero-trust payload handling**: never transmit prompt text, response text, or PII in telemetry — only numeric metadata (token counts, latency, scores, model ids, timestamps).
+- **Fail-safe**: compression failures or low predicted quality → send uncompressed payload; shadow mode compares embeddings when enabled.
+- **Provider-agnostic**: unified adapters; gateways (Portkey, Helicone, etc.) remain compatible — ContextPilot is middleware, not a router.
+- **Minimal integration**: pip install + wrap client for API users; set one env var for proxy users; connect MCP for Claude Code/Desktop users.
+- **Performance budgets**: analysis **< 50 ms** for up to **100K tokens**; **< 10 ms @ 10K tokens** (see technical doc §8).
+
+Functional dimensions for analysis: **staleness, redundancy, relevance, density** → classify blocks (essential / compressible / droppable).
+
+---
+
+## Intended package layout (implement toward this)
+
+Align refactors with the tree in the technical doc (summarized):
+
+```text
+contextpilot/
+├── contextpilot/
+│   ├── wrapper.py
+│   ├── analyzer.py
+│   ├── compressor.py
+│   ├── strategies/      # history, dedup, rag_pruner, structural, agent_memory
+│   ├── quality.py
+│   ├── shadow.py
+│   ├── telemetry.py
+│   ├── config.py
+│   ├── adapters/        # openai, anthropic, google
+│   └── _rust/           # optional acceleration
+├── dashboard/           # separate surface — keep library boundaries clean
+├── tests/, benchmarks/
+├── pyproject.toml
+└── contextpilot.yaml.example
+```
+
+**Stack**: Python **3.10+**, Pydantic + YAML config, httpx async telemetry, pytest + hypothesis, ruff/mypy per CI section — prefer matching these when adding tooling.
+
+---
+
+## Functional requirements summary
+
+| FR | Surface | Summary |
+|----|---------|---------|
+| FR-001 | Library | SDK wrapper — drop-in for OpenAI, Anthropic, Google Vertex AI |
+| FR-002 | Library | Context analysis engine — staleness, redundancy, relevance, density; < 50 ms @ 100K tokens |
+| FR-003 | Library | Compression pipeline — history summary, system prompt dedup, RAG pruning, structural stripping |
+| FR-004 | Library | Quality gate — predicted score 0–100, fallback if below threshold (default 85) |
+| FR-005 | Library | A/B shadow testing — default 5% sample rate, cosine similarity comparison |
+| FR-006 | Library | Telemetry — metadata only, async non-blocking |
+| FR-007 | Library | Configuration — YAML, env vars, programmatic API |
+| FR-008 | Library | Agent memory middleware — LangChain/CrewAI/AutoGen inter-agent handoff compression |
+| FR-009 | Proxy | Local proxy server — OpenAI-compatible, `contextpilot proxy --port 8432` |
+| FR-010 | MCP | MCP server — `optimize_context` tool, `get_savings` resource, `suggest_config` resource |
+| FR-011 | CLI | Migration agent — AST-based, `--dry-run` / `--apply`, wraps existing LLM calls |
+| FR-101+ | Dashboard | Token savings display, before/after comparison, cost projections, etc. |
+
+---
+
+## How to use bundled automation
+
+### Subagents (`.cursor/agents/`)
+
+- **changelog-archivist** — Summarize diffs; changelog/release notes; conventional commits (especially after API or behavior-visible changes).
+- **structure-guardian** — Refactors toward the package layout above; clear module boundaries; no scope creep.
+- **workstream-coordinator** — Split large work (e.g. analyzer vs strategies vs adapters vs proxy vs mcp vs migration) across parallel streams.
+
+### Skills (`.cursor/skills/`)
+
+- **log-code-changes** — Changelog/commit messaging from diffs.
+- **parallel-work-plan** — Dependency-aware split for parallel implementation.
+
+### Rules (`.cursor/rules/`)
+
+Project-wide and glob-scoped guardrails under `.cursor/rules/` — follow unless the task explicitly overrides.
+
+---
+
+## Change logging (`Logs/`)
+
+Every meaningful session of work gets a log file in `Logs/`:
+
+| Convention | Example |
+|------------|---------|
+| Phase work | `Logs/phase-1-foundation.md` |
+| Feature additions | `Logs/feat-proxy-server.md` |
+| Bug fixes / refactors | `Logs/fix-quality-gate.md` |
+
+Each log file must include: date, what changed (user-visible first), FR references where applicable, and the conventional commit lines. Use the **changelog-archivist** subagent or **log-code-changes** skill to produce entries.
+
+---
+
+## Defaults for code work
+
+- Preserve public wrapper semantics (**FR-001**: transparent SDK behavior).
+- When adding a new surface (proxy / MCP / CLI), keep the core compression engine surface-agnostic — surfaces are thin shells over the shared pipeline.
+- After any meaningful change, add or update a file in `Logs/` before closing the session.
+- When touching **telemetry**, re-read the technical doc schema (§7) and **never** add content payload fields.
+- Dashboard lives in `dashboard/` — keep it separate from the core library.