`socioverse.providers` — generic population providers¶

Bring-your-own-population: a file-backed provider (CSV/Parquet with an agent_id column) and an MCP-backed provider for external persona pools.

socioverse.providers ¶

Generic, study-agnostic PopulationProviders (scenario 3: user data / tool / MCP).

These let any study draw its population P from sources other than a bespoke builder

FilePopulationProvider : a user-uploaded CSV/Parquet of personas
McpPopulationProvider : a SocioVerse-1.0-style population-pool MCP tool

Both yield Personas with persistent ids (the longitudinal key).

FilePopulationProvider ¶

FilePopulationProvider(bundle: PopulationBundle)

Bases: PopulationProvider

Read personas from a user-uploaded file. provider_args: {"path": ..., "format"?}. The file must have an agent_id column; group_key/weight optional; the rest become persona attributes.

Source code in socioverse/providers.py

def __init__(self, bundle: PopulationBundle):
    self.bundle = bundle

McpPopulationProvider ¶

McpPopulationProvider(
    bundle: PopulationBundle,
    fetch_fn: Callable[[dict], list[dict]] | None = None,
)

Bases: PopulationProvider

Draw personas from a population-pool MCP (SocioVerse 1.0). Reference implementation: inject fetch_fn(provider_args) -> list[dict] that performs the MCP tool call (the skill wires it from ResourceManifest.mcp_servers). Each record needs an agent_id.

Source code in socioverse/providers.py

def __init__(self, bundle: PopulationBundle, fetch_fn: Callable[[dict], list[dict]] | None = None):
    self.bundle = bundle
    self.fetch_fn = fetch_fn

socioverse.providers — generic population providers¶