`socioverse.validation` — strict hand-offs¶

Every stage boundary loads its input through validate_handoff and writes its output through write_artifact — malformed artifacts fail at the gate.

socioverse.validation ¶

The single chokepoint that makes 'skills pass only typed artifacts' literally true.

Every workflow skill loads its input via validate_handoff(path, Schema) and writes its output via write_artifact(path, model). A half-formed dict cannot cross a stage boundary: if the artifact does not satisfy the contract, the pipeline stops here with a typed error.

HandoffError ¶

Bases: Exception

Raised when an inter-skill artifact is missing, unparseable, or off-contract.

validate_handoff ¶

validate_handoff(path: str | Path, schema: Type[T]) -> T

Load + validate a workspace artifact against its schema. Raises HandoffError.

Source code in socioverse/validation.py

def validate_handoff(path: str | Path, schema: Type[T]) -> T:
    """Load + validate a workspace artifact against its schema. Raises HandoffError."""
    p = Path(path)
    if not p.exists():
        raise HandoffError(f"Handoff artifact missing: {p}")
    try:
        data = json.loads(p.read_text(encoding="utf-8"))
    except json.JSONDecodeError as e:
        raise HandoffError(f"Handoff artifact is not valid JSON: {p}\n  {e}") from e
    try:
        return schema.model_validate(data)
    except ValidationError as e:
        raise HandoffError(
            f"Handoff artifact {p} violates the {schema.__name__} contract:\n{e}"
        ) from e

write_artifact ¶

write_artifact(path: str | Path, model: BaseModel) -> Path

Serialize a validated model to a workspace artifact (creates parent dirs).

Source code in socioverse/validation.py

def write_artifact(path: str | Path, model: BaseModel) -> Path:
    """Serialize a validated model to a workspace artifact (creates parent dirs)."""
    p = Path(path)
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(model.model_dump_json(indent=2), encoding="utf-8")
    return p

socioverse.validation — strict hand-offs¶