Pathfinder  

---

Pathfinder is a HPO broker for 1–2 objective deep learning runs, not an LLM that picks hyperparameters. The broker suggests via Optuna TPE; your IDE agent then inspects results only when you ask

How it works

2 layers:

• Broker (FastAPI + Optuna TPE): A lightweight coordination server optimized for iterative training with up to two objectives (e.g., maximizing accuracy and minimizing loss). Suggests parameters in <20ms locally (excluding network latency for standard study sizes), handles early stopping, and monitors study health (stagnation, OOM patterns).
• Worker: Runs your training script in a loop. Calls suggest, report_epoch, complete. Reports VRAM telemetry and handles OOMs without crashing the study.

An MCP server gives your IDE agent read-only visibility into trial history, health tiers, and fANOVA importances. The agent can validate manifests and register new studies, only when you ask. The worker never waits on an LLM.

Quick Start

Step 1: Start the Broker

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt   # or: pip install -r requirements-dev.lock for pinned CI deps
python broker.py --daemon
# Dashboard: http://127.0.0.1:8000

Using the dashboard is optional; CLI and your IDE agent can do everything.

Try it without your own training script

python hpo_cli.py init templates/demo_study.yaml
export HPO_BROKER_URL=http://localhost:8000
export HPO_STUDY_NAME=demo_study
python simulators/training_worker.py --study_name demo_study --max_trials 3
# Open http://127.0.0.1:8000 to watch trials

Step 2: Connect Your Workers

Local worker (same machine)

HPO_BROKER_URL=http://localhost:8000 HPO_STUDY_NAME=my_study python train.py

Remote worker (Colab / cloud GPU)

To expose your local broker to remote workers, use a tunnel:

# Generate a token
export HPO_SECRET_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"

# Start broker with tunnel (ngrok auto-generates a URL)
python broker.py --daemon --tunnel

# Or with Cloudflare (bring your own domain):
python broker.py --daemon --tunnel-provider cloudflare --tunnel-url https://your-domain.com

Set the printed URL and token on your remote machine:

export HPO_BROKER_URL="https://..."
export HPO_SECRET_TOKEN="<your-token>"
python train.py

See docs/INTEGRATION.md for more tunneling and auth options.

Step 3: Connect Your Agent

Point your IDE at the MCP server for agent-driven onboarding and inspection. See IDE Setup.

Environment variables are documented in docs/INTEGRATION.md.

Agent Integration

Pathfinder exposes MCP tools that let your IDE agent (Cursor, Claude Code, Antigravity) participate in two workflows:

Onboarding

1. Agent reads your training script, identifies tunable hyperparameters and metrics
2. Agent drafts a train.hpo.yaml manifest
3. Agent calls validate_manifest to check for errors
4. Agent calls init_from_manifest to register the study in Optuna and SQLite
5. Agent writes a minimal worker script from templates/worker_minimal.py

Inspection

1. Agent reads the hpo://studies/{name}/packet resource to retrieve trial telemetry, health tier, fANOVA importances, and trial data
2. Agent summarizes: current best score, health status, OOM rate, stagnation warnings
3. Recommended search space adjustments happen by you through the dashboard Settings UI or hpo_cli.py

Key MCP tools: validate_manifest, init_from_manifest. Data is retrieved via resources (hpo://studies/{name}/packet, hpo://studies/{name}/cards).

Trigger phrases: say "integrate HPO" or "wire hyperparameter tuning" to onboard. Say "show study health" or "check HPO progress" to inspect.

Ask it anything about your experiment; it has full context on trial history, health, and importances.

See AGENTS.md for the full agent procedure.

---

Onboarding Your Own Project

1. Write a manifest (train.hpo.yaml): Manually or have an agent do it for you

study_name: my_study
metrics:
  primary_score: accuracy
  objectives:
    - name: accuracy
      direction: maximize
      label: "Accuracy"
    - name: loss
      direction: minimize
      label: "Loss"
params:
  - name: learning_rate
    type: float_log
    min: 1e-5
    max: 1e-2
  - name: batch_size
    type: categorical
    options: [4, 8, 16, 32]
worker:
  entrypoint: python train.py

The primary_score field tells the dashboard which objective to highlight.

2. Register the study

python hpo_cli.py validate train.hpo.yaml
python hpo_cli.py init train.hpo.yaml

3. Update your training script

from src.hpo_client import TrialSession

session = TrialSession()  # reads HPO_BROKER_URL / HPO_STUDY_NAME
trial = session.suggest()
params = trial["params"]

for epoch in range(epochs):
    accuracy, loss = train_one_epoch(params, epoch)

    if session.report_epoch(epoch, score=accuracy, loss=loss):
        # Trial was pruned by the broker
        session.complete(epoch, score=accuracy, loss=loss, state="PRUNED")
        break

session.complete(epoch, score=accuracy, loss=loss, state="COMPLETE")

The worker contract is three calls: suggest(), report_epoch(), complete(). Map your higher-is-better metric to score and your lower-is-better metric to loss. Full details: docs/INTEGRATION.md.

4. Run on your GPU

export HPO_BROKER_URL=http://localhost:8000
export HPO_STUDY_NAME=my_study
python train.py

---

IDE Setup

Cursor

Settings → Features → MCP → + Add New MCP Server

Name: pathfinder, Type: command, Command: source .venv/bin/activate && python3 hpo_mcp_server.py

Claude Code / Antigravity

{
  "mcpServers": {
    "pathfinder": {
      "command": "python3",
      "args": ["hpo_mcp_server.py"],
      "env": {
        "HPO_DATABASE_URL": "sqlite:///./.data/hpo_studies.db"
      }
    }
  }
}

Pathfinder is compliant with the Model Context Protocol standard, it works with any MCP-compatible IDE.

---

Common Commands

# Start broker + dashboard
python broker.py --daemon

# Validate and initialize a study from manifest
python hpo_cli.py validate train.hpo.yaml
python hpo_cli.py init train.hpo.yaml

# Check study health
python hpo_cli.py status

# Export study config back to YAML
python hpo_cli.py manifest my_study

# Export/import study data
python hpo_cli.py export my_study --output my_study.json
python hpo_cli.py import my_study.json

# Generate a model card
python hpo_cli.py modelcard my_study

# Delete a study
python hpo_cli.py delete my_study

# Run tests
pytest tests/ -q

---

Notes for running locally

• Study state lives in SQLite under .data/ (override with HPO_DATABASE_URL).
• Backup anytime: python hpo_cli.py backup --output backup.db
• Auth: loopback needs no token. With --tunnel, set HPO_SECRET_TOKEN and pass the same value to workers (X-HPO-Token). This is a shared secret for a single operator.

---

Dev Notes

• MCP is implemented instead of giving the agent direct CLI execution access because structured APIs (schemas for tools and URIs for data) are much more reliable for AI tools than parsing raw command-line output.
• Implemented concurrency patterns for distributed workers, real-time detection of crashed processes
• Optimized SQLite backend performance using Write-Ahead Logging; allowing concurrent broker writes, dashboard rendering, and MCP queries without read-write blocks
• Designed specifically for 1-2 objective optimization (e.g., maximizing score while minimizing loss) which is typical for deep learning pipelines. Rather than building an overly complicated multi-objective schema, my effort was focused on making the system I have work in practice (lease management, concurrent SQLite WAL transactions, VRAM telemetry, and automatic worker OOM recovery).

---

Reference: crack-seg

Pathfinder was initially built to tune crack-seg, a U-Net pixel-level segmentation model trained on UAV bridge imagery.

---

Docs

• AGENTS.md — Guide for AI agents (Cursor, Claude Code, Antigravity, etc)
• docs/INTEGRATION.md — Worker integration details

---

License

MIT License - see the LICENSE file for details.