pedalpoint 0.1.0__py3-none-any.whl

pedalpoint/circuit_breaker.py

@@ -0,0 +1,74 @@
+import json
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+CircuitState = dict[str, Any]
+
+CLOSED_STATE: CircuitState = {"circuit": "closed"}
+
+DEFAULT_STATE_PATH = Path.home() / ".pedalpoint" / "state.json"
+
+
+def read_state(path: Path = DEFAULT_STATE_PATH) -> CircuitState:
+    if not path.exists():
+        return CLOSED_STATE.copy()
+    try:
+        return json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return CLOSED_STATE.copy()
+
+
+def write_state(state: CircuitState, path: Path = DEFAULT_STATE_PATH) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(json.dumps(state, indent=2))
+    tmp.rename(path)
+
+
+def compute_duration(failure_count: int, initial_minutes: int = 60) -> int:
+    return min(initial_minutes * (2 ** (failure_count - 1)), 1440)
+
+
+def is_expired(state: CircuitState) -> bool:
+    expires = state.get("expires")
+    if not expires:
+        return True
+    return datetime.now(timezone.utc) >= datetime.fromisoformat(expires)
+
+
+def transition_to_open(
+    reason: str,
+    failure_count: int = 1,
+    initial_minutes: int = 60,
+    tasks_rerouted: int = 0,
+) -> CircuitState:
+    now = datetime.now(timezone.utc)
+    duration = compute_duration(failure_count, initial_minutes)
+    return {
+        "circuit": "open",
+        "reason": reason,
+        "opened_at": now.isoformat(),
+        "expires": (now + timedelta(minutes=duration)).isoformat(),
+        "failure_count": failure_count,
+        "fallback_duration_minutes": duration,
+        "tasks_rerouted": tasks_rerouted,
+    }
+
+
+def transition_to_closed() -> CircuitState:
+    return CLOSED_STATE.copy()
+
+
+def double_duration(state: CircuitState, initial_minutes: int = 60) -> CircuitState:
+    failure_count = state.get("failure_count", 1) + 1
+    return transition_to_open(
+        reason=state.get("reason", "unknown"),
+        failure_count=failure_count,
+        initial_minutes=initial_minutes,
+        tasks_rerouted=state.get("tasks_rerouted", 0),
+    )
+
+
+def increment_rerouted(state: CircuitState) -> CircuitState:
+    return {**state, "tasks_rerouted": state.get("tasks_rerouted", 0) + 1}

pedalpoint/config.py

@@ -0,0 +1,27 @@
+import os
+from dataclasses import dataclass
+from functools import lru_cache
+
+
+@dataclass(frozen=True)
+class Config:
+    base_url: str
+    model: str
+    mode: str
+    timeout: float
+    initial_fallback_minutes: int
+    context_limit: int
+
+
+@lru_cache(maxsize=1)
+def get_config() -> Config:
+    return Config(
+        base_url=os.getenv("PEDALPOINT_BASE_URL", "http://localhost:11434/v1"),
+        model=os.getenv("PEDALPOINT_MODEL", "gemma4:e4b"),
+        mode=os.getenv("PEDALPOINT_MODE", "hybrid"),
+        timeout=float(os.getenv("PEDALPOINT_TIMEOUT", "120")),
+        initial_fallback_minutes=int(
+            os.getenv("PEDALPOINT_INITIAL_FALLBACK_MINUTES", "60")
+        ),
+        context_limit=int(os.getenv("PEDALPOINT_CONTEXT_LIMIT", "16000")),
+    )

pedalpoint/error_classifier.py

@@ -0,0 +1,16 @@
+import re
+
+_PATTERNS: list[tuple[re.Pattern[str], str]] = [
+    (re.compile(r"402|quota|billing|insufficient", re.IGNORECASE), "hard_quota"),
+    (re.compile(r"429|rate.?limit", re.IGNORECASE), "rate_limit"),
+    (re.compile(r"529|overload|capacity", re.IGNORECASE), "overload"),
+    (re.compile(r"timeout|connection", re.IGNORECASE), "network"),
+]
+
+
+def classify_error(text: str) -> str:
+    """Return the error category for a given error message string."""
+    for pattern, error_type in _PATTERNS:
+        if pattern.search(text):
+            return error_type
+    return "unknown"

pedalpoint/server.py

@@ -0,0 +1,72 @@
+from contextlib import asynccontextmanager
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+from .config import Config, get_config
+
+
+@asynccontextmanager
+async def lifespan(app):  # type: ignore[type-arg]
+    cfg = get_config()
+    async with httpx.AsyncClient(
+        base_url=cfg.base_url,
+        timeout=httpx.Timeout(connect=5.0, read=cfg.timeout, write=10.0, pool=5.0),
+    ) as client:
+        yield {"http": client, "cfg": cfg}
+
+
+mcp = FastMCP("pedalpoint", lifespan=lifespan)
+
+
+async def _call_local_llm(
+    client: httpx.AsyncClient,
+    prompt: str,
+    system: str | None,
+    model: str,
+    cfg: Config,
+) -> str:
+    messages: list[dict[str, str]] = []
+    if system:
+        messages.append({"role": "system", "content": system})
+    messages.append({"role": "user", "content": prompt})
+
+    try:
+        resp = await client.post(
+            "/chat/completions",
+            json={"model": model, "messages": messages},
+        )
+        resp.raise_for_status()
+        return resp.json()["choices"][0]["message"]["content"]
+    except httpx.ConnectError:
+        raise ValueError(
+            f"Ollama not reachable at {cfg.base_url} — is it running?"
+        ) from None
+    except httpx.TimeoutException:
+        raise ValueError(
+            f"Model timed out after {cfg.timeout}s — increase PEDALPOINT_TIMEOUT"
+        ) from None
+    except httpx.HTTPStatusError as exc:
+        if exc.response.status_code == 404:
+            raise ValueError(
+                f"Model `{model}` not found — run: ollama pull {model}"
+            ) from exc
+        raise ValueError(
+            f"HTTP {exc.response.status_code}: {exc.response.text}"
+        ) from exc
+
+
+@mcp.tool()
+async def local_llm(
+    ctx,  # type: ignore[type-arg]
+    prompt: str,
+    system: str | None = None,
+    model: str | None = None,
+) -> str:
+    client: httpx.AsyncClient = ctx.request_context.lifespan_context["http"]
+    cfg: Config = ctx.request_context.lifespan_context["cfg"]
+    return await _call_local_llm(client, prompt, system, model or cfg.model, cfg)
+
+
+def main() -> None:
+    mcp.run()

pedalpoint-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+pedalpoint/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pedalpoint/circuit_breaker.py,sha256=YtvEy2jgi20cSTUbNUY3lsnYoo35mPMztzWItkhc7LI,2226
+pedalpoint/config.py,sha256=9SCj-Q7m_uAClRebr7mysnb57tYgcG6QXgf2CdSMsVA,762
+pedalpoint/error_classifier.py,sha256=nHyk-t2wr7ZpsAn3fw8G1qXZK1RkF--XItQfQc5cO0E,585
+pedalpoint/server.py,sha256=wGp-m4mK-hhv2dHwZSrbzn0Dz4VW-fcALu42wia2Gc8,2104
+pedalpoint-0.1.0.dist-info/METADATA,sha256=wpzX-2A0PaPouIsaUxSGLXzFKeTHyDM_Fx_YpdjrMZg,3432
+pedalpoint-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pedalpoint-0.1.0.dist-info/entry_points.txt,sha256=LLPpcY6fbbPrOSBzy5LXnDbrsK_mhFEKfU2Fjrf8ND4,61
+pedalpoint-0.1.0.dist-info/RECORD,,

pedalpoint-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pedalpoint-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pedalpoint-server = pedalpoint.server:main