spinchain 0.1.0__tar.gz

spinchain-0.1.0/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.3
+Name: spinchain
+Version: 0.1.0
+Summary: Inference-time reasoning optimization using QUBO/Ising formulations
+Author: Ameya Khot
+Author-email: Ameya Khot <ameyakhot18@gmail.com>
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: dwave-neal>=0.6.0
+Requires-Dist: dimod>=0.12.0
+Requires-Dist: pyqubo>=1.5.0
+Requires-Dist: sentence-transformers>=3.0.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: scipy>=1.12.0
+Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.4.0 ; extra == 'dev'
+Requires-Dist: qiskit>=1.0.0 ; extra == 'quantum'
+Requires-Dist: qiskit-aer>=0.15.0 ; extra == 'quantum'
+Requires-Dist: qiskit-optimization>=0.6.0 ; extra == 'quantum'
+Requires-Dist: anthropic>=0.42.0 ; extra == 'standalone'
+Requires-Python: >=3.11
+Provides-Extra: dev
+Provides-Extra: quantum
+Provides-Extra: standalone
+Description-Content-Type: text/markdown
+
+# SpinChain
+
+Inference-time reasoning optimization for LLMs using QUBO/Ising formulations. Built as an MCP server for Claude Code.
+
+SpinChain takes multiple diverse reasoning chains, extracts fragments, formulates their selection as a QUBO problem (following [QCR-LLM](https://arxiv.org/abs/2510.24509)), solves it with simulated annealing, and returns the most stable and coherent fragment subset.
+
+## Installation
+
+### Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+### Install skills (recommended)
+
+Install SpinChain skills into Claude Code via the plugin marketplace:
+
+```
+/plugin marketplace add ameyakhot/spinchain
+/plugin install spinchain-skills@spinchain
+```
+
+This gives you 6 skills: `spinchain-optimize`, `analyze-spinchain`, `test-spinchain`, `spinchain-status`, `spinchain-bench`, `spinchain-trace`.
+
+### Clone and install the server
+
+```bash
+git clone https://github.com/ameyakhot/spinchain.git
+cd spinchain
+uv sync
+```
+
+To install with dev dependencies (pytest, ruff):
+
+```bash
+uv sync --extra dev
+```
+
+### Register as an MCP server in Claude Code
+
+Add SpinChain to your Claude Code config (`~/.claude.json`):
+
+```json
+{
+  "mcpServers": {
+    "spinchain": {
+      "type": "stdio",
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/path/to/spinchain",
+        "python",
+        "-m",
+        "spinchain"
+      ],
+      "env": {
+        "SPINCHAIN_TRACE_DIR": "/path/to/spinchain/traces"
+      }
+    }
+  }
+}
+```
+
+Replace `/path/to/spinchain` with the actual path to your cloned repo.
+
+Restart Claude Code. The `optimize_reasoning` tool will be available as `mcp__spinchain__optimize_reasoning`.
+
+## How it works
+
+```
+User asks a complex reasoning question
+        │
+        ▼
+Claude generates N diverse reasoning chains
+        │
+        ▼
+Claude calls optimize_reasoning(completions=[...])
+        │
+        ▼
+┌─────────────────────────────────────────────┐
+│  SpinChain Pipeline                         │
+│                                             │
+│  1. Fragment Extraction                     │
+│     Split into sentences, embed with        │
+│     sentence-transformers, deduplicate      │
+│     by cosine similarity                    │
+│                                             │
+│  2. QUBO Formulation (QCR-LLM)             │
+│     Linear: -μ·popularity + α·risk          │
+│     Quadratic: -β·(correlation - λ²·sim)    │
+│                                             │
+│  3. Simulated Annealing (dwave-neal)        │
+│     100 reads × 1000 sweeps                 │
+│                                             │
+│  4. Stability Ranking                       │
+│     Select fragments appearing in ≥50%      │
+│     of low-energy solutions                 │
+└─────────────────────────────────────────────┘
+        │
+        ▼
+Claude receives optimized fragments
+and synthesizes final answer
+```
+
+## Usage
+
+### As an MCP server (primary use)
+
+Once registered, Claude calls SpinChain automatically when using the `optimize_reasoning` tool. No manual invocation needed.
+
+### Standalone example
+
+Run the bundled example with synthetic reasoning chains (no API key needed):
+
+```bash
+uv run python examples/basic_usage.py
+```
+
+### Trace analysis
+
+Every MCP call is logged to `SPINCHAIN_TRACE_DIR/spinchain_traces.jsonl`. Analyze with:
+
+```bash
+# Human-readable report
+uv run python -m spinchain.analyze
+
+# JSON output
+uv run python -m spinchain.analyze --json
+
+# Last 10 calls only
+uv run python -m spinchain.analyze --last 10
+```
+
+### Run tests
+
+```bash
+uv run --extra dev python -m pytest tests/ -v
+```
+
+## Skills
+
+Install via `/plugin marketplace add ameyakhot/spinchain` in Claude Code, or use as slash commands when working inside the project directory.
+
+| Skill | Description |
+|-------|-------------|
+| `spinchain-optimize` | Core skill — teaches Claude how to generate diverse chains and call `optimize_reasoning` effectively |
+| `analyze-spinchain` | Run trace analysis — usage stats, latency breakdown, anomalies |
+| `test-spinchain` | Run the full test suite (71 tests) |
+| `spinchain-status` | Health check — config, imports, trace summary |
+| `spinchain-bench` | Run the example benchmark and inspect pipeline output |
+| `spinchain-trace` | Inspect raw trace records — recent calls, specific trace IDs |
+
+## Project structure
+
+```
+spinchain/
+├── src/spinchain/
+│   ├── server.py                  # MCP server — optimize_reasoning tool
+│   ├── tracing.py                 # JSONL trace logger
+│   ├── analyze.py                 # Trace analysis CLI
+│   ├── formulation/
+│   │   ├── fragment_extractor.py  # Sentence splitting, embedding, dedup
+│   │   ├── coefficient_builder.py # QCR-LLM linear + quadratic weights
+│   │   └── qubo_builder.py        # BQM construction + cardinality constraint
+│   └── solvers/
+│       ├── base.py                # Abstract solver interface
+│       └── simulated_annealing.py # dwave-neal SA solver
+├── tests/                         # 71 tests
+├── examples/
+│   └── basic_usage.py             # Synthetic benchmark
+├── .claude/commands/              # Claude Code slash commands
+└── traces/                        # Trace logs (created at runtime)
+```
+
+## Configuration
+
+### Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SPINCHAIN_TRACE_DIR` | `~/.spinchain/traces/` | Directory for JSONL trace logs |
+
+### optimize_reasoning parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `completions` | required | List of reasoning chain strings (min 2) |
+| `num_reads` | 100 | SA samples per solve |
+| `num_sweeps` | 1000 | MC sweeps per sample |
+| `similarity_threshold` | 0.85 | Cosine similarity for fragment dedup |
+| `selection_threshold` | 0.25 | Fraction of low-energy solutions for ranking |
+| `inclusion_threshold` | 0.50 | Min frequency to include a fragment |
+| `cardinality_k` | None | Target number of fragments to select |
+
+### QUBO hyperparameters (in code)
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `mu` | 1.0 | Fragment popularity weight |
+| `alpha` | 0.5 | Risk/variance penalty |
+| `beta` | 1.0 | Pairwise coherence weight |
+| `lambda_sim` | 0.3 | Semantic similarity penalty factor |
+| `penalty_strength` | 5.0 | Cardinality constraint weight |
+
+## Solver roadmap
+
+1. **Simulated Annealing** (current) — dwave-neal, pure Python
+2. **COBI Ising chip** — millisecond solves, hardware accelerated
+3. **Quanfluence CIM** — optical coherent Ising machine
+4. **IBM Quantum QAOA** — gate-based quantum validation
+
+All solvers share the same `BaseSolver` interface and QUBO formulation.
+
+## License
+
+MIT

spinchain-0.1.0/README.md

@@ -0,0 +1,217 @@
+# SpinChain
+
+Inference-time reasoning optimization for LLMs using QUBO/Ising formulations. Built as an MCP server for Claude Code.
+
+SpinChain takes multiple diverse reasoning chains, extracts fragments, formulates their selection as a QUBO problem (following [QCR-LLM](https://arxiv.org/abs/2510.24509)), solves it with simulated annealing, and returns the most stable and coherent fragment subset.
+
+## Installation
+
+### Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+### Install skills (recommended)
+
+Install SpinChain skills into Claude Code via the plugin marketplace:
+
+```
+/plugin marketplace add ameyakhot/spinchain
+/plugin install spinchain-skills@spinchain
+```
+
+This gives you 6 skills: `spinchain-optimize`, `analyze-spinchain`, `test-spinchain`, `spinchain-status`, `spinchain-bench`, `spinchain-trace`.
+
+### Clone and install the server
+
+```bash
+git clone https://github.com/ameyakhot/spinchain.git
+cd spinchain
+uv sync
+```
+
+To install with dev dependencies (pytest, ruff):
+
+```bash
+uv sync --extra dev
+```
+
+### Register as an MCP server in Claude Code
+
+Add SpinChain to your Claude Code config (`~/.claude.json`):
+
+```json
+{
+  "mcpServers": {
+    "spinchain": {
+      "type": "stdio",
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/path/to/spinchain",
+        "python",
+        "-m",
+        "spinchain"
+      ],
+      "env": {
+        "SPINCHAIN_TRACE_DIR": "/path/to/spinchain/traces"
+      }
+    }
+  }
+}
+```
+
+Replace `/path/to/spinchain` with the actual path to your cloned repo.
+
+Restart Claude Code. The `optimize_reasoning` tool will be available as `mcp__spinchain__optimize_reasoning`.
+
+## How it works
+
+```
+User asks a complex reasoning question
+        │
+        ▼
+Claude generates N diverse reasoning chains
+        │
+        ▼
+Claude calls optimize_reasoning(completions=[...])
+        │
+        ▼
+┌─────────────────────────────────────────────┐
+│  SpinChain Pipeline                         │
+│                                             │
+│  1. Fragment Extraction                     │
+│     Split into sentences, embed with        │
+│     sentence-transformers, deduplicate      │
+│     by cosine similarity                    │
+│                                             │
+│  2. QUBO Formulation (QCR-LLM)             │
+│     Linear: -μ·popularity + α·risk          │
+│     Quadratic: -β·(correlation - λ²·sim)    │
+│                                             │
+│  3. Simulated Annealing (dwave-neal)        │
+│     100 reads × 1000 sweeps                 │
+│                                             │
+│  4. Stability Ranking                       │
+│     Select fragments appearing in ≥50%      │
+│     of low-energy solutions                 │
+└─────────────────────────────────────────────┘
+        │
+        ▼
+Claude receives optimized fragments
+and synthesizes final answer
+```
+
+## Usage
+
+### As an MCP server (primary use)
+
+Once registered, Claude calls SpinChain automatically when using the `optimize_reasoning` tool. No manual invocation needed.
+
+### Standalone example
+
+Run the bundled example with synthetic reasoning chains (no API key needed):
+
+```bash
+uv run python examples/basic_usage.py
+```
+
+### Trace analysis
+
+Every MCP call is logged to `SPINCHAIN_TRACE_DIR/spinchain_traces.jsonl`. Analyze with:
+
+```bash
+# Human-readable report
+uv run python -m spinchain.analyze
+
+# JSON output
+uv run python -m spinchain.analyze --json
+
+# Last 10 calls only
+uv run python -m spinchain.analyze --last 10
+```
+
+### Run tests
+
+```bash
+uv run --extra dev python -m pytest tests/ -v
+```
+
+## Skills
+
+Install via `/plugin marketplace add ameyakhot/spinchain` in Claude Code, or use as slash commands when working inside the project directory.
+
+| Skill | Description |
+|-------|-------------|
+| `spinchain-optimize` | Core skill — teaches Claude how to generate diverse chains and call `optimize_reasoning` effectively |
+| `analyze-spinchain` | Run trace analysis — usage stats, latency breakdown, anomalies |
+| `test-spinchain` | Run the full test suite (71 tests) |
+| `spinchain-status` | Health check — config, imports, trace summary |
+| `spinchain-bench` | Run the example benchmark and inspect pipeline output |
+| `spinchain-trace` | Inspect raw trace records — recent calls, specific trace IDs |
+
+## Project structure
+
+```
+spinchain/
+├── src/spinchain/
+│   ├── server.py                  # MCP server — optimize_reasoning tool
+│   ├── tracing.py                 # JSONL trace logger
+│   ├── analyze.py                 # Trace analysis CLI
+│   ├── formulation/
+│   │   ├── fragment_extractor.py  # Sentence splitting, embedding, dedup
+│   │   ├── coefficient_builder.py # QCR-LLM linear + quadratic weights
+│   │   └── qubo_builder.py        # BQM construction + cardinality constraint
+│   └── solvers/
+│       ├── base.py                # Abstract solver interface
+│       └── simulated_annealing.py # dwave-neal SA solver
+├── tests/                         # 71 tests
+├── examples/
+│   └── basic_usage.py             # Synthetic benchmark
+├── .claude/commands/              # Claude Code slash commands
+└── traces/                        # Trace logs (created at runtime)
+```
+
+## Configuration
+
+### Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SPINCHAIN_TRACE_DIR` | `~/.spinchain/traces/` | Directory for JSONL trace logs |
+
+### optimize_reasoning parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `completions` | required | List of reasoning chain strings (min 2) |
+| `num_reads` | 100 | SA samples per solve |
+| `num_sweeps` | 1000 | MC sweeps per sample |
+| `similarity_threshold` | 0.85 | Cosine similarity for fragment dedup |
+| `selection_threshold` | 0.25 | Fraction of low-energy solutions for ranking |
+| `inclusion_threshold` | 0.50 | Min frequency to include a fragment |
+| `cardinality_k` | None | Target number of fragments to select |
+
+### QUBO hyperparameters (in code)
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `mu` | 1.0 | Fragment popularity weight |
+| `alpha` | 0.5 | Risk/variance penalty |
+| `beta` | 1.0 | Pairwise coherence weight |
+| `lambda_sim` | 0.3 | Semantic similarity penalty factor |
+| `penalty_strength` | 5.0 | Cardinality constraint weight |
+
+## Solver roadmap
+
+1. **Simulated Annealing** (current) — dwave-neal, pure Python
+2. **COBI Ising chip** — millisecond solves, hardware accelerated
+3. **Quanfluence CIM** — optical coherent Ising machine
+4. **IBM Quantum QAOA** — gate-based quantum validation
+
+All solvers share the same `BaseSolver` interface and QUBO formulation.
+
+## License
+
+MIT

spinchain-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "spinchain"
+version = "0.1.0"
+description = "Inference-time reasoning optimization using QUBO/Ising formulations"
+readme = "README.md"
+authors = [
+    { name = "Ameya Khot", email = "ameyakhot18@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "mcp>=1.0.0",
+    "dwave-neal>=0.6.0",
+    "dimod>=0.12.0",
+    "pyqubo>=1.5.0",
+    "sentence-transformers>=3.0.0",
+    "numpy>=1.26.0",
+    "scipy>=1.12.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.4.0",
+]
+standalone = [
+    "anthropic>=0.42.0",
+]
+quantum = [
+    "qiskit>=1.0.0",
+    "qiskit-aer>=0.15.0",
+    "qiskit-optimization>=0.6.0",
+]
+
+[project.scripts]
+spinchain-server = "spinchain.server:main"
+
+[build-system]
+requires = ["uv_build>=0.9.5,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100

spinchain-0.1.0/src/spinchain/__init__.py

@@ -0,0 +1,3 @@
+"""SpinChain: Inference-time reasoning optimization using QUBO/Ising formulations."""
+
+__version__ = "0.1.0"

spinchain-0.1.0/src/spinchain/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for python -m spinchain."""
+
+from spinchain.server import main
+
+main()