feat(pebble): add orchestrator/schemas.py — Pydantic data models (slice 1)

[jpb33333]

Summary

Adds the data-model foundation for the new orchestrator pipeline. Eleven public types covering plans, tool calls, evaluations, and final responses, with strict validation and immutable instances.

Stacked on PR #204 (slice 0 — the package conversion). This PR's base is feat/pebble-orchestrator-package. When #204 merges to dev, GitHub will automatically retarget this PR to dev.

What's added

pebble/orchestrator/schemas.py (221 LOC):

Type	Kind	Purpose
StepType	str Enum	Plan step kinds (search, read, compute, write)
EvalVerdict	str Enum	Evaluator verdict (pass, retry, abort)
PlanStep	BaseModel	One step in a plan — tool, inputs, dependencies
Plan	BaseModel	Top-level plan from the planner — query, steps, success criteria
ToolCall	BaseModel	Executor request to a tool
ToolResult	BaseModel	Tool response with success flag + data or error
Evaluation	BaseModel	Verifier output: factuality score, harm bucket, verdict
Citation	BaseModel	Entity link for the renderer
ChartSpec	BaseModel	Recharts-compatible chart spec
SuggestedAction	BaseModel	Write-action confirmation card
FinalResponse	BaseModel	What the renderer hands back to the user

All models are frozen=True (immutable). Validators enforce:

• Non-empty query / tool name after whitespace strip.
• No forward references in PlanStep.depends_on (step N can only depend on steps < N).
• Evaluation.factuality in [0.0, 1.0].
• Evaluation.harm ∈ {none, mild, severe}.
• ChartSpec.kind matches the supported Recharts whitelist.

Why

Every later orchestrator slice (planner, executor, renderer, chat_orchestrator, …) imports from schemas. Landing the data foundation first means each subsequent slice can be reviewed against a stable type surface.

How tested

• pytest pebble/tests/test_orchestrator_schemas.py -v — 27 passed:
  • PlanStep: minimal valid, strip whitespace, reject empty, frozen.
  • Plan: minimal valid, strip query, reject empty query, reject forward refs in depends_on, accept valid chains, frozen.
  • ToolResult: failure default, success carries data, frozen.
  • Evaluation: factuality bounds, harm pattern, harm enum values, verdict enum.
  • Citation, ChartSpec, SuggestedAction: shape pinning.
  • FinalResponse: immutability.
  • StepType: enum values.
• pytest pebble/tests/ -q — 317 passed (290 baseline + 27 new).
• pytest financial_forecasting/tests/ -q — 827 passed, 22 skipped, unchanged.

Imports

Stdlib + pydantic only:

from __future__ import annotations
from datetime import datetime, timezone
from enum import Enum
from typing import Any, Optional
from uuid import UUID, uuid4
from pydantic import BaseModel, ConfigDict, Field, field_validator

pydantic>=2.5.2 is already in requirements.txt. No new dependencies.

Risk

Very low. The module is purely additive — nothing on dev (or on slice 0) imports from pebble.orchestrator.schemas, so this PR cannot change any existing code path. The only consumers will be future slices.

Rollback

Revert this single commit. The schemas.py and test_orchestrator_schemas.py files disappear; nothing else moves.

Next slice

Slice 2: pebble/llm/ (Anthropic client + cost helpers + tests + cassettes). Independent of schemas — can be reviewed in parallel with this one.

🤖 Generated with Claude Code

[claude]

⚠️ Code review skipped — your organization's overage spend limit has been reached.

Code review is billed via overage credits. To resume reviews, an organization admin can raise the monthly limit at claude.ai/admin-settings/claude-code.

Once credits are available, push a new commit or reopen this pull request to trigger a review.