pedalpoint 0.1.0__tar.gz

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

@@ -0,0 +1,98 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "feat/**", "fix/**", "chore/**", "test/**", "docs/**"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  unit-tests:
+    name: Unit Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run unit tests with coverage
+        run: |
+          pytest tests/unit/ -v \
+            --cov=pedalpoint \
+            --cov-report=term-missing \
+            --cov-fail-under=90
+
+  integration-tests:
+    name: Integration Tests (Ollama)
+    runs-on: ubuntu-latest
+    needs: unit-tests
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install Ollama
+        run: curl -fsSL https://ollama.ai/install.sh | sh
+
+      - name: Start Ollama and pull model
+        run: |
+          ollama serve &
+          timeout 30 bash -c 'until ollama list 2>/dev/null; do sleep 1; done'
+          ollama pull gemma4:e4b
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run integration tests
+        env:
+          PEDALPOINT_INTEGRATION: "true"
+          PEDALPOINT_MODEL: "gemma4:e4b"
+        run: pytest tests/integration/ -v
+
+  install-tests:
+    name: Install Script Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install bats
+        run: sudo apt-get install -y bats
+
+      - name: Run install script tests
+        run: bats tests/install/ -v
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Run ruff check
+        run: ruff check src/ tests/
+
+      - name: Run ruff format check
+        run: ruff format --check src/ tests/

pedalpoint-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,75 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python3 -m build
+
+      - name: Upload dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/pedalpoint
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: publish-to-testpypi
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pedalpoint
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pedalpoint-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.coverage
+htmlcov/
+*.log
+.env
+.ruff_cache/
+.DS_Store

pedalpoint-0.1.0/CLAUDE.md

@@ -0,0 +1,83 @@
+# pedalpoint — Developer Guide
+
+## Project Overview
+
+MCP server + companion superpowers skill. Two deliverables:
+1. `pedalpoint-server` — Python binary (FastMCP, httpx)
+2. `skills/route-tasks.md` — Markdown skill for Claude Code
+
+## Key Design Decisions
+
+- **Thin server, smart skill:** Server is a pure HTTP proxy. All routing logic lives in the skill. Server never touches `~/.pedalpoint/state.json`.
+- **No streaming:** `local_llm` returns full string. Simpler, sufficient for code gen.
+- **Circuit breaker in skill:** Claude reads/writes state.json via Write tool. Python `circuit_breaker.py` module contains the pure functions that document and validate this logic.
+- **Context Courier:** Skill MUST grep codebase before sending any task to local LLM. Empty grep result = escalate to Agent.
+
+## Branch Strategy
+
+- `main` — always stable, PR only, squash merge
+- `feat/<name>` — new functionality
+- `fix/<name>` — bug fixes
+- `chore/<name>` — tooling, config, deps
+- `test/<name>` — test-only changes
+- `docs/<name>` — documentation
+
+Branch on everything, including README and CLAUDE.md changes.
+
+## TDD Workflow
+
+1. Write failing test
+2. Run to confirm failure
+3. Implement minimal code
+4. Run to confirm pass
+5. Commit
+
+Coverage requirements: circuit_breaker.py = 100%, error_classifier.py = 100%, server.py ≥ 90%
+
+## Running Tests
+
+```sh
+# Unit tests (fast, no Ollama needed)
+pytest tests/unit/ -v --cov=pedalpoint --cov-report=term-missing
+
+# Integration tests (requires Ollama running with gemma4:e4b pulled)
+PEDALPOINT_INTEGRATION=true pytest tests/integration/ -v
+
+# All unit tests with coverage check
+pytest tests/unit/ --cov=pedalpoint --cov-fail-under=90
+```
+
+## File Responsibilities
+
+| File | Responsibility |
+|---|---|
+| `src/pedalpoint/config.py` | Load env vars into frozen Config dataclass |
+| `src/pedalpoint/error_classifier.py` | Regex classify error strings → error type |
+| `src/pedalpoint/circuit_breaker.py` | Pure fns for state transitions, expiry, backoff |
+| `src/pedalpoint/server.py` | FastMCP app, lifespan, `local_llm` tool, `_call_local_llm` |
+| `skills/route-tasks.md` | Claude instructions: routing, Context Courier, circuit breaker |
+| `install.sh` | Install pkg, pull model, register MCP config, copy skill |
+
+## State File Format
+
+`~/.pedalpoint/state.json`:
+```json
+{
+  "circuit": "open",
+  "reason": "402_quota",
+  "opened_at": "2026-05-08T15:30:00+00:00",
+  "expires": "2026-05-08T16:30:00+00:00",
+  "failure_count": 1,
+  "fallback_duration_minutes": 60,
+  "tasks_rerouted": 3
+}
+```
+
+CLOSED state: `{"circuit": "closed"}` or file absent.
+
+## Common Gotchas
+
+- `get_config()` uses `lru_cache`. Tests must call `get_config.cache_clear()` before and after monkeypatching env vars.
+- `_call_local_llm` is the testable core; `local_llm` (the MCP tool) just unwraps ctx and delegates to it.
+- 402 errors trigger permanent fallback. 429 errors trigger retry-with-backoff only. Do not conflate them.
+- The companion skill has no Python backing. Skill tests are manual scenarios in `tests/skill/scenarios/`.

pedalpoint-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: pedalpoint
+Version: 0.1.0
+Summary: MCP server that routes mechanical dev tasks to a local LLM
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pedalpoint
+
+Route mechanical development tasks to a local LLM (Ollama, LM Studio, Jan) via Claude Code. Automatically falls back to local-only mode when Claude quota is exhausted.
+
+## What it does
+
+- **Hybrid routing:** Claude classifies each task. Mechanical work (scaffolding, CRUD, test stubs) goes to your local LLM. Judgment work (architecture, debugging, integration) stays with Claude.
+- **Quota fallback:** When Claude returns a quota error, pedalpoint automatically switches to local-only mode and continues working. Switches back when quota restores.
+- **Context Courier:** Before sending any task to the local LLM, pedalpoint greps your codebase for existing patterns and injects them into the prompt. Local LLMs only get tasks they have templates for.
+- **Single install:** One script installs the MCP server, pulls the default model, and registers the companion skill.
+
+## Requirements
+
+- Claude Code
+- Python 3.11+
+- [Ollama](https://ollama.ai) (or any OpenAI-compatible inference server)
+
+## Install
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/EMSwank/pedalpoint/main/install.sh | sh
+```
+
+With a custom model or endpoint:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/EMSwank/pedalpoint/main/install.sh | \
+  sh -s -- --model llama3 --base-url http://localhost:11434/v1
+```
+
+Restart Claude Code after install.
+
+## Usage
+
+Instead of `superpowers:subagent-driven-development`, invoke:
+
+```
+pedalpoint:route-tasks
+```
+
+pedalpoint handles routing automatically. No manual flagging needed.
+
+## Modes
+
+| Mode | Set via | Behavior |
+|---|---|---|
+| `hybrid` | default | Claude classifies each task |
+| `local-only` | `PEDALPOINT_MODE=local-only` | All tasks → local LLM (use when quota exhausted preemptively) |
+| `passthrough` | `PEDALPOINT_MODE=passthrough` | All tasks → Claude Agent (disables pedalpoint) |
+
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `PEDALPOINT_BASE_URL` | `http://localhost:11434/v1` | OpenAI-compatible endpoint |
+| `PEDALPOINT_MODEL` | `gemma4:e4b` | Default local model |
+| `PEDALPOINT_MODE` | `hybrid` | Routing mode |
+| `PEDALPOINT_TIMEOUT` | `120` | Read timeout in seconds |
+| `PEDALPOINT_INITIAL_FALLBACK_MINUTES` | `60` | Initial circuit-open duration (doubles on each probe failure) |
+
+## Uninstall
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/EMSwank/pedalpoint/main/install.sh | sh -s -- --uninstall
+```
+
+## Development
+
+```sh
+git clone https://github.com/EMSwank/pedalpoint
+cd pedalpoint
+pip install -e ".[dev]"   # requires pip >= 21.3; run `pip install --upgrade pip` if needed
+pytest tests/unit/ -v
+```
+
+Integration tests (requires Ollama running):
+
+```sh
+PEDALPOINT_INTEGRATION=true pytest tests/integration/ -v
+```
+
+Install script tests (requires [bats-core](https://github.com/bats-core/bats-core)):
+
+```sh
+brew install bats-core   # macOS; use apt-get install bats on Linux
+bats tests/install/
+```
+
+## License
+
+MIT

pedalpoint-0.1.0/README.md

@@ -0,0 +1,91 @@
+# pedalpoint
+
+Route mechanical development tasks to a local LLM (Ollama, LM Studio, Jan) via Claude Code. Automatically falls back to local-only mode when Claude quota is exhausted.
+
+## What it does
+
+- **Hybrid routing:** Claude classifies each task. Mechanical work (scaffolding, CRUD, test stubs) goes to your local LLM. Judgment work (architecture, debugging, integration) stays with Claude.
+- **Quota fallback:** When Claude returns a quota error, pedalpoint automatically switches to local-only mode and continues working. Switches back when quota restores.
+- **Context Courier:** Before sending any task to the local LLM, pedalpoint greps your codebase for existing patterns and injects them into the prompt. Local LLMs only get tasks they have templates for.
+- **Single install:** One script installs the MCP server, pulls the default model, and registers the companion skill.
+
+## Requirements
+
+- Claude Code
+- Python 3.11+
+- [Ollama](https://ollama.ai) (or any OpenAI-compatible inference server)
+
+## Install
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/EMSwank/pedalpoint/main/install.sh | sh
+```
+
+With a custom model or endpoint:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/EMSwank/pedalpoint/main/install.sh | \
+  sh -s -- --model llama3 --base-url http://localhost:11434/v1
+```
+
+Restart Claude Code after install.
+
+## Usage
+
+Instead of `superpowers:subagent-driven-development`, invoke:
+
+```
+pedalpoint:route-tasks
+```
+
+pedalpoint handles routing automatically. No manual flagging needed.
+
+## Modes
+
+| Mode | Set via | Behavior |
+|---|---|---|
+| `hybrid` | default | Claude classifies each task |
+| `local-only` | `PEDALPOINT_MODE=local-only` | All tasks → local LLM (use when quota exhausted preemptively) |
+| `passthrough` | `PEDALPOINT_MODE=passthrough` | All tasks → Claude Agent (disables pedalpoint) |
+
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `PEDALPOINT_BASE_URL` | `http://localhost:11434/v1` | OpenAI-compatible endpoint |
+| `PEDALPOINT_MODEL` | `gemma4:e4b` | Default local model |
+| `PEDALPOINT_MODE` | `hybrid` | Routing mode |
+| `PEDALPOINT_TIMEOUT` | `120` | Read timeout in seconds |
+| `PEDALPOINT_INITIAL_FALLBACK_MINUTES` | `60` | Initial circuit-open duration (doubles on each probe failure) |
+
+## Uninstall
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/EMSwank/pedalpoint/main/install.sh | sh -s -- --uninstall
+```
+
+## Development
+
+```sh
+git clone https://github.com/EMSwank/pedalpoint
+cd pedalpoint
+pip install -e ".[dev]"   # requires pip >= 21.3; run `pip install --upgrade pip` if needed
+pytest tests/unit/ -v
+```
+
+Integration tests (requires Ollama running):
+
+```sh
+PEDALPOINT_INTEGRATION=true pytest tests/integration/ -v
+```
+
+Install script tests (requires [bats-core](https://github.com/bats-core/bats-core)):
+
+```sh
+brew install bats-core   # macOS; use apt-get install bats on Linux
+bats tests/install/
+```
+
+## License
+
+MIT