"""Voyages (one engagement's chain of use cases) and the workflow registry, as loaded from this repository. A path is relative to this repository, or to the cp1-agents clone when it starts with `cp1-agents:` (the committed F01 to F03 cases stay there and are read in place, plan ยง3). A stage input is a literal, or a reference to an earlier stage's result: `{from: , value: }`, where the name is `execution_id`, `approval_ref` or `package_artifact_ids` (`["_step_"]` of its package step). References are resolved when the stage starts; the files themselves are never edited. """ from __future__ import annotations from dataclasses import dataclass, field from pathlib import Path from typing import Any, Dict, List, Optional import yaml from . import cp1_agents REPO = Path(__file__).resolve().parents[1] CONTEXT_ADAPTERS = {"upload", "document", "none"} STAGE_VALUES = {"execution_id", "approval_ref", "package_artifact_ids"} class VoyageError(ValueError): pass def resolve_path(text: str) -> Path: if text.startswith("cp1-agents:"): return cp1_agents.clone_dir() / text.split(":", 1)[1] path = Path(text) return path if path.is_absolute() else REPO / path @dataclass class Workflow: key: str feature: str names: List[str] context: str document_input: Optional[str] = None workflow_id: Optional[str] = None def load_workflow(key: str) -> Workflow: path = REPO / "workflows" / f"{key}.yaml" if not path.is_file(): raise VoyageError(f"workflow {key!r} is not registered: no {path.relative_to(REPO)}") doc = yaml.safe_load(path.read_text()) or {} wf = Workflow(key=doc.get("key", key), feature=doc["feature"], names=list(doc["names"]), context=doc["context"], document_input=doc.get("document_input"), workflow_id=doc.get("workflow_id")) if wf.context not in CONTEXT_ADAPTERS: raise VoyageError(f"{path.name}: context must be one of {sorted(CONTEXT_ADAPTERS)}") if wf.context == "document" and not wf.document_input: raise VoyageError(f"{path.name}: a document context names its run input in document_input") return wf @dataclass class Stage: key: str workflow: str workflow_id: Optional[str] = None context: Optional[str] = None case: Optional[str] = None inputs: Dict[str, Any] = field(default_factory=dict) documents: Dict[str, str] = field(default_factory=dict) use_execution: Optional[str] = None approval_ref: Optional[str] = None @dataclass class Voyage: name: str engagement_id: str project: str stages: List[Stage] capability: Optional[str] = None source: Optional[Path] = None def load_voyage(path: Path) -> Voyage: doc = yaml.safe_load(Path(path).read_text()) or {} for required in ("voyage", "engagement_id", "project", "stages"): if not doc.get(required): raise VoyageError(f"{path}: `{required}` is required") stages, seen = [], set() for raw in doc["stages"]: stage = Stage(key=raw["key"], workflow=raw["workflow"], workflow_id=raw.get("workflow_id"), context=raw.get("context"), case=raw.get("case"), inputs=dict(raw.get("inputs") or {}), documents=dict(raw.get("documents") or {}), use_execution=raw.get("use_execution"), approval_ref=raw.get("approval_ref")) if stage.key in seen: raise VoyageError(f"{path}: stage key {stage.key!r} appears twice") if stage.use_execution and not stage.approval_ref: raise VoyageError(f"{path}: stage {stage.key} uses execution {stage.use_execution}: give its approval_ref " "(who continued it at its review point, and when)") for name, value in stage.inputs.items(): if isinstance(value, dict): if value.get("from") not in seen or value.get("value") not in STAGE_VALUES: raise VoyageError(f"{path}: stage {stage.key} input {name}: `from` must name an earlier stage and " f"`value` one of {sorted(STAGE_VALUES)}") seen.add(stage.key) stages.append(stage) return Voyage(name=doc["voyage"], engagement_id=doc["engagement_id"], project=doc["project"], stages=stages, capability=doc.get("capability"), source=Path(path)) def load_config(path: Path | None = None) -> dict: """Runner settings, from a committed file so a change to them is reviewed. The environment can't widen them.""" path = path or REPO / "config" / "runner.yaml" doc = yaml.safe_load(path.read_text()) or {} doc["gate_projects"] = {str(p) for p in (doc.get("gate_projects") or [])} return doc