socioverse.schemas — typed contracts

Every hand-off in the pipeline (Persona → Observation → Action → metrics) and every artifact on disk is one of these Pydantic models.

Study

socioverse.schemas.study

StudySpec — the top-level contract produced from a user query by sv-init.

StudySpec

Bases: BaseModel

One study = one research question over a fixed population and a dynamic environment.

study_type=longitudinal is the SocioVerse-beta differentiator: the same persistent population is tracked across n_steps (panel data), not re-sampled per round.

Environment

socioverse.schemas.environment

Environment E schemas: the two-axis layer system + dynamics channels.

• EnvironmentLayer carries (modality, scope, dynamics) tags — the routing rules that EnvironmentProvider.observe_batch uses to assemble each agent's Observation.
• ScheduledEvent = exogenous NUMERIC environment change at a step (subway/crime/income).
• Broadcast / InformationProgram = exogenous INFORMATION content, audience-scoped (audience="all" -> macro_information; audience=selector -> local_information).

EnvironmentLayer

Bases: BaseModel

One tagged slice of the environment. The (modality, scope) pair places it in one of the 4 quadrants: macro/local x physical/information.

ScheduledEvent

Bases: BaseModel

A numeric, exogenous mutation of a physical layer fired at at_step. (Reframes the old one-shot customize/PolicySpec.geo_modifications as time-scheduled.)

Broadcast

Bases: BaseModel

A piece of information injected into the environment at a step, delivered to a scoped audience. audience='all' -> macro_information (everyone); audience=dict selector -> local_information (only matching agents).

InformationProgram

Bases: BaseModel

The full timeline of information broadcasts for a study (scenario 1).

EnvironmentBundle

Bases: BaseModel

The validated artifact written by sv-build-environment.

Population

socioverse.schemas.population

Population P schemas: personas with persistent ids + interaction + propagation.

The persistent agent_id is the longitudinal primary key — the same persona is tracked across all steps. PopulationBundle.personas may be empty when the bundle only declares a provider (e.g. census/mcp) that materializes personas at runtime.

PropagationMode

Bases: str, Enum

How influence flows among agents.

PopulationBundle

Bases: BaseModel

The validated artifact written by sv-build-population.

Simulation

socioverse.schemas.simulation

SimulationConfig — binds population + environment + decision model + schedule.

Written by sv-run (preflight) after the env/population bundles exist. The *_ref strings are resolved against the registry to concrete classes.

WarmStartSpec

Bases: BaseModel

Inherit already-run steps from a parent version instead of re-running from step 0.

The engine REPLAYS the parent's stored actions for steps 1..resume_from (no LLM — this reproduces the parent trajectory exactly AND rehydrates env state to E_K), then runs resume_from+1..n_steps with real decisions, so only the genuinely new steps spend budget. Requires a study whose env.apply(actions) is a pure function of the passed actions (from-scratch / Path-B) and interaction_rounds == 1; legacy-wrap studies (chicago) are not supported (their move-intent lives on hidden legacy agents set during decide_batch).

Runtime (Observation / Action)

socioverse.schemas.runtime

Runtime contracts exchanged inside the simulation loop: Observation and Action.

Observation is where the two-axis environment materializes into a concrete per-agent view (the 4 quadrants). Action is the agent's behavior B handed back to the engine.

Observation

Bases: BaseModel

The assembled 4-quadrant view handed to the DecisionModel for one agent at one step.

quadrants_nonempty

quadrants_nonempty() -> dict[str, bool]

Helper for tests/audits: which of the 4 quadrants carry content.

Source code in socioverse/schemas/runtime.py

def quadrants_nonempty(self) -> dict[str, bool]:
    """Helper for tests/audits: which of the 4 quadrants carry content."""
    return {
        "macro_physical": bool(self.macro_physical),
        "local_physical": bool(self.local_physical),
        "macro_information": bool(self.macro_information),
        "local_information": bool(self.local_information),
    }

Action

Bases: BaseModel

The behavior B_t emitted by a DecisionModel for one agent.

Trajectory

socioverse.schemas.trajectory

Trajectory + metrics output contracts (the longitudinal panel data).

TrajectoryRecord

Bases: BaseModel

One panel row. (agent_id, step) is the longitudinal primary key.

MetricsHistory

Bases: BaseModel

Per-step aggregate metrics; one flat dict per step (must contain 'step').

covers

covers(required: list[str]) -> list[str]

Return required metric names NOT present in schema_columns (contract check).

Source code in socioverse/schemas/trajectory.py

def covers(self, required: list[str]) -> list[str]:
    """Return required metric names NOT present in schema_columns (contract check)."""
    present = set(self.schema_columns)
    return [m for m in required if m not in present]

Resources

socioverse.schemas.resources

ResourceManifest — user-declared external data, tools, and MCP servers (scenario 3).

Declared at sv-init time (or alongside the query). Skills and providers read it to attach a population pool MCP, a user-uploaded dataset, or custom tools.