From 9f2cb57fc78b910d3328e378e13cbdfb7e9c90d9 Mon Sep 17 00:00:00 2001
From: JP <jp@JPs-Pursuit-MacBook-Air.local>
Date: Tue, 19 May 2026 13:31:44 -0400
Subject: [PATCH] refactor(pebble): convert orchestrator.py into a package
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Pure refactor with zero behavior change. Renames pebble/orchestrator.py
to pebble/orchestrator/_pipeline.py and adds an __init__.py that re-exports
the seven symbols imported by callers outside the package today
(ProspectBudgetTracker, research_single_prospect, score_source_richness,
activate_foragers, quorum_verify_claims, synthesize_profile, verify_urls).
Single-dot relative imports inside _pipeline.py become double-dot since
the file now sits one level deeper.

This is slice 0 of carving PR #191 (feat/pebble-l2-swarm) into focused
slices off current dev. See ~/.claude/plans/pr191-carve-strategy.md.
The orchestrator package is the foundation: future slices add sibling
modules (schemas.py, planner.py, renderer.py, ...) under this same package.

Verification:
- pebble suite: 290 passed (unchanged)
- financial_forecasting suite: 827 passed, 22 skipped (unchanged)
- All seven re-exported symbols import cleanly: `from pebble.orchestrator
  import ProspectBudgetTracker, ...` succeeds with no warnings.

Callers verified unchanged on dev:
- pebble/main.py:591 — from .orchestrator import research_single_prospect
- pebble/clusters/__init__.py:15 — from ..orchestrator import ProspectBudgetTracker
- pebble/handlers/tier2.py:41 — from ..orchestrator import (score_source_richness, activate_foragers, ProspectBudgetTracker)
- pebble/handlers/tier3.py:33 — from ..orchestrator import (research_single_prospect, quorum_verify_claims, synthesize_profile, verify_urls, ProspectBudgetTracker)
- pebble/tests/test_clusters.py — 4 imports of ProspectBudgetTracker

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 pebble/orchestrator/__init__.py               | 30 +++++++++++++++++++
 .../_pipeline.py}                             | 12 ++++----
 2 files changed, 36 insertions(+), 6 deletions(-)
 create mode 100644 pebble/orchestrator/__init__.py
 rename pebble/{orchestrator.py => orchestrator/_pipeline.py} (99%)

diff --git a/pebble/orchestrator/__init__.py b/pebble/orchestrator/__init__.py
new file mode 100644
index 00000000..86aa161b
--- /dev/null
+++ b/pebble/orchestrator/__init__.py
@@ -0,0 +1,30 @@
+"""Pebble research orchestrator.
+
+This package replaces the former single-file `pebble/orchestrator.py`. All
+existing behavior lives unchanged in `_pipeline.py`; this `__init__.py`
+re-exports the symbols that callers outside the package import today, so
+existing import sites keep working without modification.
+
+Future work (the L2 swarm) will add sibling modules (`schemas.py`,
+`planner.py`, `renderer.py`, ...) inside this package.
+"""
+
+from ._pipeline import (
+    ProspectBudgetTracker,
+    activate_foragers,
+    quorum_verify_claims,
+    research_single_prospect,
+    score_source_richness,
+    synthesize_profile,
+    verify_urls,
+)
+
+__all__ = [
+    "ProspectBudgetTracker",
+    "activate_foragers",
+    "quorum_verify_claims",
+    "research_single_prospect",
+    "score_source_richness",
+    "synthesize_profile",
+    "verify_urls",
+]
diff --git a/pebble/orchestrator.py b/pebble/orchestrator/_pipeline.py
similarity index 99%
rename from pebble/orchestrator.py
rename to pebble/orchestrator/_pipeline.py
index 3a1ca398..f1508bed 100644
--- a/pebble/orchestrator.py
+++ b/pebble/orchestrator/_pipeline.py
@@ -24,10 +24,10 @@
 from dataclasses import dataclass, field
 from typing import Callable
 
-from .model_client import ModelClient
-from .harness import WorkerHarness, HarnessConfig, AgentOutcome, TaskSpec, harness_config_for_agent
-from .storage.db import log_harness_outcome, get_source_reliability, save_profile, save_source_scores, save_session
-from .data_sources import (
+from ..model_client import ModelClient
+from ..harness import WorkerHarness, HarnessConfig, AgentOutcome, TaskSpec, harness_config_for_agent
+from ..storage.db import log_harness_outcome, get_source_reliability, save_profile, save_source_scores, save_session
+from ..data_sources import (
     fetch_organization,
     search_organizations,
     fetch_company,
@@ -37,8 +37,8 @@
     fetch_full_profile,
     search_officers,
 )
-from .data_sources.sec import search_cik
-from .claim_templates import (
+from ..data_sources.sec import search_cik
+from ..claim_templates import (
     claims_from_fec,
     claims_from_usaspending,
     claims_from_opencorporates,