anneal-context 0.1.0__tar.gz

anneal_context-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Create venv and install
+        run: |
+          uv venv
+          uv pip install "spinchain @ git+https://github.com/ameyakhot/spinchain.git"
+          uv pip install -e ".[dev]"
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Test
+        run: uv run python -m pytest tests/ -v --tb=short
+
+  test-spinchain-main:
+    name: Test against SpinChain main
+    runs-on: ubuntu-latest
+    continue-on-error: true
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Create venv and install
+        run: |
+          uv venv
+          uv pip install "spinchain @ git+https://github.com/ameyakhot/spinchain.git@main"
+          uv pip install -e ".[dev]"
+
+      - name: Test
+        run: uv run python -m pytest tests/ -v --tb=short

anneal_context-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Create venv and install
+        run: |
+          uv venv
+          uv pip install spinchain
+          uv pip install -e ".[dev]"
+
+      - name: Run tests before publish
+        run: uv run python -m pytest tests/ -v --tb=short
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

anneal_context-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+# Local config (project-specific, not for repo)
+.anneal/
+CLAUDE.md
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+*.egg-info/
+.ruff_cache/
+
+# Test artifacts
+.pytest_cache/

anneal_context-0.1.0/DEVOPS.md

@@ -0,0 +1,42 @@
+# Anneal DevOps
+
+Full DevOps documentation lives in the SpinChain repo:
+`spinchain/docs/superpowers/specs/2026-04-13-devops-workflow.md`
+
+It covers the complete workflow for both SpinChain and Anneal:
+- Project architecture and relationship
+- Local development setup
+- CI/CD pipelines
+- Release and publish process
+- Cross-repo dependency management
+- PyPI trusted publisher setup
+
+## Quick Reference
+
+| Item | Value |
+|------|-------|
+| PyPI name | `anneal-context` |
+| Import name | `anneal` |
+| Entry point | `anneal-server` |
+| Depends on | `spinchain>=0.1.0` |
+| CI | `.github/workflows/ci.yml` — test + lint + SpinChain canary |
+| Publish | `.github/workflows/publish.yml` — triggers on GitHub Release |
+| SpinChain public API | `spinchain/PUBLIC_API.md` |
+
+## Local Dev
+
+```bash
+cd ~/quantum/anneal
+source .venv/bin/activate
+uv pip install -e ~/quantum/spinchain   # editable spinchain
+uv pip install -e ".[dev]"
+python -m pytest tests/ -v
+ruff check src/ tests/
+```
+
+## Release
+
+1. Ensure SpinChain is published to PyPI first (if new version needed)
+2. Update version in `pyproject.toml`
+3. `git commit`, `git tag vX.Y.Z`, `git push origin main --tags`
+4. Create GitHub Release from tag → publish.yml runs automatically

anneal_context-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: anneal-context
+Version: 0.1.0
+Summary: Optimal context selection for AI coding assistants using QUBO/Ising formulation
+Author-email: Ameya Khot <ameyakhot18@gmail.com>
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: dimod>=0.12.0
+Requires-Dist: dwave-neal>=0.6.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: scipy>=1.12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Requires-Dist: spinchain; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Anneal
+
+Optimal context selection for AI coding assistants. Cooling random context down to exactly what your AI needs.
+
+Anneal reads your codebase's structural graph (from Graphify or code-review-graph),
+formulates "which chunks are optimal?" as a QUBO problem, solves with simulated
+annealing, and returns the minimum context set for your task.
+
+## How It Works
+
+1. Reads codebase graph (Graphify `graph.json` or code-review-graph SQLite)
+2. Generates candidate chunks (keyword matching + graph topology)
+3. Formulates QUBO: minimize token cost, maximize relevance, reward dependency coverage
+4. Solves via simulated annealing (SpinChain engine)
+5. Returns stability-ranked, dependency-ordered chunks within your token budget
+
+## Requirements
+
+- Python 3.11+
+- At least one graph tool: [Graphify](https://github.com/safishamsi/graphify) or [code-review-graph](https://github.com/nicholasgasior/code-review-graph)
+
+## Installation
+
+```bash
+pip install anneal-context
+```
+
+Or with uv:
+```bash
+uv tool install anneal-context
+```
+
+## Setup
+
+**1. Install a graph tool** (required):
+
+```bash
+# code-review-graph
+npx code-review-graph install
+
+# Graphify (Claude Code)
+/plugin marketplace add safishamsi/graphify && /graphify
+```
+
+**2. Create `.anneal/config.toml`** in your project root:
+
+```toml
+[budget]
+default_tokens = 5000
+strategy = "balanced"   # "minimal" | "balanced" | "thorough"
+
+[solver]
+backend = "simulated-annealing"
+num_reads = 100
+num_sweeps = 1000
+```
+
+Add `.anneal/` to your `.gitignore`.
+
+## MCP Server Setup
+
+### Claude Code
+
+Add to `.claude/settings.json`:
+```json
+{
+  "mcpServers": {
+    "anneal": {
+      "command": "anneal-server"
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+Add to `~/.gemini/settings.json`:
+```json
+{
+  "mcpServers": {
+    "anneal": {
+      "command": "anneal-server"
+    }
+  }
+}
+```
+
+### OpenAI Codex CLI
+
+Add to `~/.codex/config.toml`:
+```toml
+[[mcp_servers]]
+name = "anneal"
+command = "anneal-server"
+```
+
+### Cursor / VS Code + Copilot / Aider
+
+Any MCP-compatible client: run `anneal-server` via stdio transport.
+
+## Tools
+
+### `get_optimal_context`
+
+```
+Parameters:
+  task_description: str     -- what you want to do
+  token_budget: int | None  -- max tokens (default: 5000)
+  include_files: list[str]  -- always include these paths
+  exclude_files: list[str]  -- never include these paths
+  strategy: str             -- "balanced" | "minimal" | "thorough"
+
+Returns:
+  selected_chunks: list[{path, content, relevance_score, tokens}]
+  total_tokens: int
+  budget_utilization: float
+  stability_score: float
+  dependency_graph: dict
+```
+
+### `get_status`
+
+Returns graph source availability, node counts, solver config.
+
+## Development
+
+```bash
+git clone https://github.com/ameyakhot/anneal
+cd anneal
+uv venv && source .venv/bin/activate
+uv pip install -e /path/to/spinchain
+uv pip install -e ".[dev]"
+python -m pytest tests/ -v
+```
+
+## License
+
+MIT

anneal_context-0.1.0/README.md

@@ -0,0 +1,138 @@
+# Anneal
+
+Optimal context selection for AI coding assistants. Cooling random context down to exactly what your AI needs.
+
+Anneal reads your codebase's structural graph (from Graphify or code-review-graph),
+formulates "which chunks are optimal?" as a QUBO problem, solves with simulated
+annealing, and returns the minimum context set for your task.
+
+## How It Works
+
+1. Reads codebase graph (Graphify `graph.json` or code-review-graph SQLite)
+2. Generates candidate chunks (keyword matching + graph topology)
+3. Formulates QUBO: minimize token cost, maximize relevance, reward dependency coverage
+4. Solves via simulated annealing (SpinChain engine)
+5. Returns stability-ranked, dependency-ordered chunks within your token budget
+
+## Requirements
+
+- Python 3.11+
+- At least one graph tool: [Graphify](https://github.com/safishamsi/graphify) or [code-review-graph](https://github.com/nicholasgasior/code-review-graph)
+
+## Installation
+
+```bash
+pip install anneal-context
+```
+
+Or with uv:
+```bash
+uv tool install anneal-context
+```
+
+## Setup
+
+**1. Install a graph tool** (required):
+
+```bash
+# code-review-graph
+npx code-review-graph install
+
+# Graphify (Claude Code)
+/plugin marketplace add safishamsi/graphify && /graphify
+```
+
+**2. Create `.anneal/config.toml`** in your project root:
+
+```toml
+[budget]
+default_tokens = 5000
+strategy = "balanced"   # "minimal" | "balanced" | "thorough"
+
+[solver]
+backend = "simulated-annealing"
+num_reads = 100
+num_sweeps = 1000
+```
+
+Add `.anneal/` to your `.gitignore`.
+
+## MCP Server Setup
+
+### Claude Code
+
+Add to `.claude/settings.json`:
+```json
+{
+  "mcpServers": {
+    "anneal": {
+      "command": "anneal-server"
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+Add to `~/.gemini/settings.json`:
+```json
+{
+  "mcpServers": {
+    "anneal": {
+      "command": "anneal-server"
+    }
+  }
+}
+```
+
+### OpenAI Codex CLI
+
+Add to `~/.codex/config.toml`:
+```toml
+[[mcp_servers]]
+name = "anneal"
+command = "anneal-server"
+```
+
+### Cursor / VS Code + Copilot / Aider
+
+Any MCP-compatible client: run `anneal-server` via stdio transport.
+
+## Tools
+
+### `get_optimal_context`
+
+```
+Parameters:
+  task_description: str     -- what you want to do
+  token_budget: int | None  -- max tokens (default: 5000)
+  include_files: list[str]  -- always include these paths
+  exclude_files: list[str]  -- never include these paths
+  strategy: str             -- "balanced" | "minimal" | "thorough"
+
+Returns:
+  selected_chunks: list[{path, content, relevance_score, tokens}]
+  total_tokens: int
+  budget_utilization: float
+  stability_score: float
+  dependency_graph: dict
+```
+
+### `get_status`
+
+Returns graph source availability, node counts, solver config.
+
+## Development
+
+```bash
+git clone https://github.com/ameyakhot/anneal
+cd anneal
+uv venv && source .venv/bin/activate
+uv pip install -e /path/to/spinchain
+uv pip install -e ".[dev]"
+python -m pytest tests/ -v
+```
+
+## License
+
+MIT

anneal_context-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "anneal-context"
+version = "0.1.0"
+description = "Optimal context selection for AI coding assistants using QUBO/Ising formulation"
+readme = "README.md"
+authors = [
+    { name = "Ameya Khot", email = "ameyakhot18@gmail.com" }
+]
+license = { text = "MIT" }
+requires-python = ">=3.11"
+dependencies = [
+    "mcp>=1.0.0",
+    "dimod>=0.12.0",
+    "dwave-neal>=0.6.0",
+    "numpy>=1.26.0",
+    "scipy>=1.12.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.4.0",
+    "spinchain",
+]
+
+[project.scripts]
+anneal-server = "anneal.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/anneal"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

anneal_context-0.1.0/skills/claude-code/anneal.md

@@ -0,0 +1,81 @@
+# Anneal — Optimal Context Selection
+
+Use this skill to get the optimal code context before starting any task. Anneal
+uses QUBO optimization over the codebase dependency graph to select the minimum
+token set that maximizes task relevance.
+
+## When to Use
+
+Call `mcp__anneal__get_optimal_context` at the start of any coding task before
+reading files. This replaces manual file discovery.
+
+## Usage
+
+### Get optimal context
+```
+mcp__anneal__get_optimal_context(
+  task_description="<describe what you want to do>",
+  token_budget=5000,
+  strategy="balanced",
+  include_files=[],
+  exclude_files=[],
+)
+```
+
+### Check status
+```
+mcp__anneal__get_status()
+```
+
+## First-Time Setup
+
+If `get_optimal_context` returns an error about no graph sources, install one:
+
+**code-review-graph** (recommended):
+```
+npx code-review-graph install
+```
+
+**Graphify:**
+```
+/plugin marketplace add safishamsi/graphify
+/graphify
+```
+
+Then create `.anneal/config.toml` in your project root:
+```toml
+[budget]
+default_tokens = 5000
+strategy = "balanced"
+
+[solver]
+backend = "simulated-annealing"
+num_reads = 100
+num_sweeps = 1000
+```
+
+## Installation (Claude Code)
+
+Add to your MCP config:
+```json
+{
+  "mcpServers": {
+    "anneal": {
+      "command": "anneal-server",
+      "args": []
+    }
+  }
+}
+```
+
+Or with uvx (no install):
+```json
+{
+  "mcpServers": {
+    "anneal": {
+      "command": "uvx",
+      "args": ["anneal-context"]
+    }
+  }
+}
+```

anneal_context-0.1.0/skills/gemini-cli/anneal.md

@@ -0,0 +1,24 @@
+# Anneal — Gemini CLI Setup
+
+## Installation
+
+```bash
+pip install anneal-context
+```
+
+Add to `~/.gemini/settings.json`:
+```json
+{
+  "mcpServers": {
+    "anneal": {
+      "command": "anneal-server"
+    }
+  }
+}
+```
+
+## Usage
+
+```
+@anneal get_optimal_context task_description="add unit tests for auth module"
+```

anneal_context-0.1.0/src/anneal/assembly/budget_manager.py

@@ -0,0 +1,25 @@
+# src/anneal/assembly/budget_manager.py
+"""Token counting and hard budget enforcement."""
+
+from __future__ import annotations
+from anneal.formulation.candidate_generator import Candidate
+
+_CHARS_PER_TOKEN = 4
+
+
+class BudgetManager:
+    def count_tokens(self, text: str) -> int:
+        return max(0, len(text) // _CHARS_PER_TOKEN)
+
+    def trim_to_budget(self, candidates: list[Candidate], budget: int) -> list[Candidate]:
+        total = sum(c.tokens for c in candidates)
+        if total <= budget:
+            return candidates
+        sorted_cands = sorted(candidates, key=lambda c: -c.relevance_score)
+        result = []
+        used = 0
+        for c in sorted_cands:
+            if used + c.tokens <= budget:
+                result.append(c)
+                used += c.tokens
+        return result