PARACOSM AGENTOS | API Reference v0.9.1035
Home Simulation API Docs GitHub npm
Home Simulation API Docs GitHub npm AgentOS Discord
paracosm - v0.9.1035
    Preparing search index...

    Interface SimulateOptions

    Options-bag for wm.simulate. Replaces the v0.8 positional form simulate(leader, options, keyPersonnel). Extends the full internal RunOptions (provider keys, economics, initial population, etc.) and adds actor + keyPersonnel so visitor-facing call sites need only one argument.

    interface SimulateOptions {
        _forkedFrom?: { atTurn: number; parentRunId: string };
        _resumeFrom?: KernelSnapshot;
        activeDepartments?: string[];
        actor: ActorConfig;
        anthropicKey?: string;
        apiKey?: string;
        braveKey?: string;
        captureSnapshots?: boolean;
        cohereKey?: string;
        costPreset?: CostPreset;
        customEvents?: { description: string; title: string; turn: number }[];
        economics?: ResolvedEconomicsProfile;
        execution?: Partial<SimulationExecutionConfig>;
        firecrawlKey?: string;
        initialPopulation?: number;
        intervention?: {
            adherenceProfile?: { expected: number; risks?: string[] };
            category?: string;
            description: string;
            duration?: { unit: string; value: number };
            id: string;
            mechanism?: string;
            name: string;
            scenarioExtensions?: Record<string, unknown>;
            targetBehaviors?: string[];
        };
        keyPersonnel?: KeyPersonnel[];
        liveSearch?: boolean;
        maxTurns?: number;
        models?: Partial<SimulationModelConfig>;
        onEvent?: (event: SimEvent) => void;
        provider?: LlmProvider;
        scenario?: ScenarioPackage;
        seed?: number;
        serperKey?: string;
        signal?: AbortSignal;
        startingEnvironment?: Record<string, string | number | boolean>;
        startingPolitics?: StartingPolitics;
        startingResources?: StartingResources;
        startingStatuses?: Record<string, string | boolean>;
        startTime?: number;
        subject?: {
            conditions?: string[];
            id: string;
            markers?: {
                category?: string;
                id: string;
                interpretation?: string;
                value?: string;
            }[];
            name: string;
            personality?: Record<string, number>;
            profile?: Record<string, unknown>;
            scenarioExtensions?: Record<string, unknown>;
            signals?: {
                label: string;
                recordedAt?: string;
                unit?: string;
                value: string | number;
            }[];
        };
        tavilyKey?: string;
        timePerTurn?: number;
    }

    Hierarchy (View Summary)

    Index
    _forkedFrom? _resumeFrom? activeDepartments? actor anthropicKey? apiKey? braveKey? captureSnapshots? cohereKey? costPreset? customEvents? economics? execution? firecrawlKey? initialPopulation? intervention? keyPersonnel? liveSearch? maxTurns? models? onEvent? provider? scenario? seed? serperKey? signal? startingEnvironment? startingPolitics? startingResources? startingStatuses? startTime? subject? tavilyKey? timePerTurn?

    Optional_forkedFrom

    _forkedFrom?: { atTurn: number; parentRunId: string }

    Internal-only: WorldModel.fork() sets this to thread the { parentRunId, atTurn } link onto the child run's metadata.forkedFrom. Not part of the public API; callers should use WorldModel.fork() rather than setting this directly.

    Optional_resumeFrom

    _resumeFrom?: KernelSnapshot

    Internal-only: WorldModel.fork() sets this to a KernelSnapshot that the orchestrator restores before running the first turn. Not part of the public API.

    activeDepartments?: string[]
    actor: ActorConfig

    The actor whose decisions drive the simulation.

    anthropicKey?: string

    Anthropic API key.

    apiKey?: string

    OpenAI API key. Historical dashboard field name.

    braveKey?: string
    captureSnapshots?: boolean

    When true, the orchestrator captures a KernelSnapshot at the end of every turn and stashes the resulting array under artifact.scenarioExtensions.kernelSnapshotsPerTurn. Enables WorldModel.forkFromArtifact() on the returned artifact. Default false so normal runs stay lean; snapshots add ~100 KB per turn for 100-agent Mars-shape runs.

    cohereKey?: string
    costPreset?: CostPreset

    Cost-vs-quality switch for model routing. Defaults to 'quality' which keeps department agents on the flagship tier (gpt-5.4 / claude-sonnet-4-6) for reliable tool forging — ~$1-3 per 6-turn run on OpenAI. Set to 'economy' to drop every role to mid/cheap (gpt-4o departments, gpt-5.4-nano everything else; haiku on Anthropic) — ~$0.20-0.60 per 6-turn run on OpenAI, ~5-10× cheaper.

    Economy mode drops forge approval rate by roughly 10-20pp because the mid-tier model occasionally violates structured-output schemas the judge rejects. Use it for quick iteration / debugging / CI; use 'quality' (default) for publishable or production runs.

    Explicit models entries always win over the preset, so you can mix and match: { costPreset: 'economy', models: { departments: 'gpt-5.4' } } gives you cheap everything except departments.

    customEvents?: { description: string; title: string; turn: number }[]
    economics?: ResolvedEconomicsProfile
    execution?: Partial<SimulationExecutionConfig>
    firecrawlKey?: string
    initialPopulation?: number
    intervention?: {
        adherenceProfile?: { expected: number; risks?: string[] };
        category?: string;
        description: string;
        duration?: { unit: string; value: number };
        id: string;
        mechanism?: string;
        name: string;
        scenarioExtensions?: Record<string, unknown>;
        targetBehaviors?: string[];
    }

    Intervention being tested on the subject. Passed through verbatim to RunArtifact.intervention. Turn-loop ignores; batch modes consume.

    keyPersonnel?: KeyPersonnel[]

    Optional supporting cast for context retrieval. Default [].

    liveSearch?: boolean
    maxTurns?: number
    models?: Partial<SimulationModelConfig>
    onEvent?: (event: SimEvent) => void
    provider?: LlmProvider
    scenario?: ScenarioPackage
    seed?: number
    serperKey?: string
    signal?: AbortSignal

    Cancellation signal. When .aborted flips to true, the turn loop short-circuits at the next turn boundary, emits a sim_aborted event, and returns the partial result accumulated so far.

    Server wires this to an AbortController that fires after a grace period of zero connected SSE clients, so a user who closes the tab or navigates away stops billing for new LLM calls while preserving the partial results they already accumulated in the event buffer.

    startingEnvironment?: Record<string, string | number | boolean>
    startingPolitics?: StartingPolitics
    startingResources?: StartingResources
    startingStatuses?: Record<string, string | boolean>
    startTime?: number
    subject?: {
        conditions?: string[];
        id: string;
        markers?: {
            category?: string;
            id: string;
            interpretation?: string;
            value?: string;
        }[];
        name: string;
        personality?: Record<string, number>;
        profile?: Record<string, unknown>;
        scenarioExtensions?: Record<string, unknown>;
        signals?: {
            label: string;
            recordedAt?: string;
            unit?: string;
            value: string | number;
        }[];
    }

    Subject being simulated (digital-twin person, game character, etc.). Passed through verbatim to RunArtifact.subject. Turn-loop mode does not consume this semantically; future batch-trajectory executor will.

    tavilyKey?: string
    timePerTurn?: number

    Settings
    Member Visibility

    On This Page
    Properties
    agentos.sh GitHub npm Frame.dev Frame Privacy
    PARACOSM · Apache-2.0 · Frame.dev