{"id":48873120,"url":"https://github.com/framersai/paracosm","last_synced_at":"2026-05-13T03:12:40.585Z","repository":{"id":350916293,"uuid":"1208748661","full_name":"framersai/paracosm","owner":"framersai","description":"Agent swarm simulation with emergent tool forging, HEXACO personality evolution, and deterministic kernels. Built on AgentOS.","archived":false,"fork":false,"pushed_at":"2026-04-30T23:57:25.000Z","size":287796,"stargazers_count":24,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-01T00:15:01.695Z","etag":null,"topics":["agentos","ai-agents","ai-simulation","emergent-behavior","hexaco","mars","multi-agent","personality","simulation","swarm"],"latest_commit_sha":null,"homepage":"https://paracosm.agentos.sh","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/framersai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-12T17:38:18.000Z","updated_at":"2026-04-30T23:55:39.000Z","dependencies_parsed_at":"2026-04-18T02:02:08.541Z","dependency_job_id":null,"html_url":"https://github.com/framersai/paracosm","commit_stats":null,"previous_names":["framersai/mars-genesis-simulation","framersai/paracosm"],"tags_count":201,"template":false,"template_full_name":null,"purl":"pkg:github/framersai/paracosm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/framersai%2Fparacosm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/framersai%2Fparacosm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/framersai%2Fparacosm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/framersai%2Fparacosm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/framersai","download_url":"https://codeload.github.com/framersai/paracosm/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/framersai%2Fparacosm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32577126,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentos","ai-agents","ai-simulation","emergent-behavior","hexaco","mars","multi-agent","personality","simulation","swarm"],"created_at":"2026-04-15T23:02:04.740Z","updated_at":"2026-05-13T03:12:40.578Z","avatar_url":"https://github.com/framersai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://paracosm.agentos.sh\"\u003e\u003cimg src=\"assets/favicons/icon.svg\" alt=\"Paracosm\" height=\"64\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003ePARACOSM\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eAgent swarm simulation for structured world modeling with LLMs. Prompt to runnable multi-agent world to forked futures.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/paracosm\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/paracosm?style=flat-square\u0026color=e8b44a\u0026labelColor=14110e\" alt=\"npm\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/framersai/paracosm/blob/master/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache--2.0-e06530?style=flat-square\u0026labelColor=14110e\" alt=\"License\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://paracosm.agentos.sh/docs\"\u003e\u003cimg src=\"https://img.shields.io/badge/docs-API%20Reference-4ca8a8?style=flat-square\u0026labelColor=14110e\" alt=\"Docs\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://agentos.sh/en\"\u003e\u003cimg src=\"https://img.shields.io/badge/built%20on-AgentOS-e06530?style=flat-square\u0026labelColor=14110e\" alt=\"AgentOS\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://paracosm.agentos.sh\"\u003e\u003cstrong\u003eparacosm.agentos.sh\u003c/strong\u003e\u003c/a\u003e ·\n  \u003ca href=\"https://paracosm.agentos.sh/sim\"\u003eLive Demo\u003c/a\u003e ·\n  \u003ca href=\"https://paracosm.agentos.sh/docs\"\u003eAPI Docs\u003c/a\u003e ·\n  \u003ca href=\"https://www.npmjs.com/package/paracosm\"\u003enpm\u003c/a\u003e ·\n  \u003ca href=\"https://wilds.ai/discord\"\u003eDiscord\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/blog/readme/paracosm-hero.gif\" alt=\"Paracosm end-to-end: paragraph in, two leaders running, fork-and-replay out\" width=\"720\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eType a what-if. Compile a typed world. Run two LLM commanders against it. Fork any past turn. Watch the trajectories diverge.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://paracosm.agentos.sh/demo/e2e-atlas-8-hero.mp4\"\u003e▶ Full 90-second demo\u003c/a\u003e\n  \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"https://paracosm.agentos.sh/demo/digital-twin-maria-2-hero.mp4\"\u003e▶ Digital twin\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nParacosm is an agent swarm simulation framework for structured world modeling with LLMs. It compiles a JSON scenario draft (or a prompt, or an extracted document) into a runnable multi-agent world, plays it through a deterministic kernel, and lets agents with HEXACO personality profiles decide turn by turn how the world unfolds. Snapshots persist on disk. Runs replay byte-for-byte. Any past turn can be forked with a different actor, a different seed, or a custom event, and the divergent branch streams alongside the trunk so the contrast is visible in the artifact, not promised in copy.\n\nThe product is the contrast. Same compiled world, same kernel, same seed — but the LLM Event Director reads each leader's HEXACO profile and accumulated state, so the events themselves diverge from turn 1. Swap one variable and the trajectory measurably moves; replay the same leader on the same seed and the run reproduces.\n\n---\n\n## Forking Paths\n\n\u003e \"In all fictions, each time a man meets diverse alternatives, he chooses one and eliminates the others. In the work of Ts'ui Pên, he chooses, simultaneously, all of them.\"\n\u003e\n\u003e Jorge Luis Borges, *The Garden of Forking Paths*, 1941\n\nA world model that can be forked needs three things: a deterministic substrate that can be rewound, an LLM reasoner that can be replayed against the same state, and a contract for what state actually means. Paracosm carries all three. Snapshots are JSON, the kernel round-trips through `JSON.stringify`, and every fork resumes from the captured state without recomputing the prefix.\n\n```typescript\nimport { WorldModel } from 'paracosm';\nimport worldJson from './my-world.json' with { type: 'json' };\n\nconst wm = await WorldModel.fromJson(worldJson);\n\n// Trunk run, snapshots captured at every turn\nconst trunk = await wm.simulate(visionaryActor, {\n  maxTurns: 6, seed: 42, captureSnapshots: true,\n});\n\n// Fork at turn 3 with a different actor; turns 1 to 3 are reused, not rerun\nconst branch = await (await wm.forkFromArtifact(trunk, 3)).simulate(\n  pragmatistActor,\n  { maxTurns: 6, seed: 42 },\n);\n\nconsole.log(trunk.metadata.runId);        // parent run id\nconsole.log(branch.metadata.forkedFrom);  // { parentRunId, atTurn: 3 }\nconsole.log(trunk.fingerprint, branch.fingerprint);\n```\n\n`captureSnapshots` defaults to `false` so that ordinary runs stay lean. The dashboard flips it on for every UI run; the Reports tab shows a fork button on each completed turn, posts to `/setup` with the parent artifact, and routes the new run into a Branches tab where forks accumulate as cards with per-metric deltas as they stream.\n\n### Replay any run for audit\n\n```typescript\nconst replay = await wm.replay(storedArtifact);\nconsole.log(replay.matches);     // true when the kernel reproduces the artifact byte for byte\nconsole.log(replay.divergence);  // first-mismatch JSON pointer when matches=false\n```\n\nThe kernel's between-turn progression hook reruns deterministically from each recorded snapshot. LLM stages are not invoked, so replay is fast and free. Use it for golden-artifact regression tests in CI, or to find the first kernel-state divergence between two paracosm versions.\n\n---\n\n## Personality is the variable\n\n\u003e \"We don't want to conquer the cosmos, we only want to extend the boundaries of Earth to the frontiers of the cosmos. We don't want other worlds; we want mirrors.\"\n\u003e\n\u003e Stanislaw Lem, *Solaris*, 1961\n\nTwo simulation runs against an identical compiled scenario, starting from the same kernel state, produce divergent trajectories when the only thing that changes is the actor's personality. The kernel is reproducible. The divergence comes from the LLM stages reading a HEXACO profile and deciding accordingly.\n\nActors do not need to be people. The same authoring contract handles colony commanders, ship captains, AI release directors, governing councils, faction leaders, autonomous coordinators, or any entity whose decisions shape the world after a chain of inputs. Paracosm does not care what an actor represents. It cares how the actor decides.\n\n```typescript\nimport { compileScenario, WorldModel } from 'paracosm';\nimport worldJson from './my-world.json' with { type: 'json' };\n\nconst scenario = await compileScenario(worldJson, {\n  provider: 'anthropic',\n  model: 'claude-sonnet-4-6',\n});\nconst wm = WorldModel.fromScenario(scenario);\n\nconst reyes = {\n  name: 'Captain Reyes', archetype: 'The Pragmatist', unit: 'Station Alpha',\n  hexaco: { openness: 0.4, conscientiousness: 0.9, extraversion: 0.3,\n            agreeableness: 0.6, emotionality: 0.5, honestyHumility: 0.8 },\n  instructions: 'You lead by protocol. Safety margins first.',\n};\n\nconst okafor = {\n  name: 'Captain Okafor', archetype: 'The Innovator', unit: 'Station Beta',\n  hexaco: { openness: 0.9, conscientiousness: 0.4, extraversion: 0.8,\n            agreeableness: 0.5, emotionality: 0.3, honestyHumility: 0.6 },\n  instructions: 'You lead by experimentation. Push boundaries.',\n};\n\nconst [a, b] = await Promise.all(\n  [reyes, okafor].map((actor) =\u003e\n    wm.simulate({ actor, maxTurns: 6, seed: 42 }),\n  ),\n);\nconsole.log(a.fingerprint, b.fingerprint); // diverges visibly within two turns\n```\n\n### Inspecting the agent swarm\n\nEach run carries a swarm of ~100 personality-typed agents (cells with departments, roles, mood, family edges, and persistent memory) on `RunArtifact.finalSwarm`. The dedicated `paracosm/swarm` subpath ships pure-projection helpers for the common shapes:\n\n```typescript\nimport { getSwarm, swarmByDepartment, moodHistogram, departmentHeadcount } from 'paracosm/swarm';\n\nconst swarm = getSwarm(a);\nif (swarm) {\n  console.log(`T${swarm.turn} · ${swarm.population} alive · ${Math.round((swarm.morale ?? 0) * 100)}% morale`);\n  console.log(moodHistogram(swarm));        // { focused: 12, anxious: 5, ... }\n  console.log(departmentHeadcount(swarm));  // { engineering: 18, agriculture: 22, ... }\n  console.log(swarmByDepartment(a));        // org chart with full roster per dept\n}\n```\n\nSame data is on `WorldModel.swarm(artifact)` if you already have the WorldModel façade imported, and at `GET /api/v1/runs/:runId/swarm` for HTTP consumers. The dashboard's living-swarm grid streams the same shape per-turn via SSE.\n\nSix turns is enough to surface the contrast. The fingerprint is a stable hash over the trajectory, decisions, and final metrics, so two runs are easy to diff.\n\n---\n\n## Quickstart: prompt or document to running simulation\n\n`WorldModel.fromPrompt` compiles a scenario from seed source material (paste, URL, or extracted PDF text), and `wm.quickstart` then generates N contextual HEXACO actors and runs them in parallel. Both paths validate against `DraftScenarioSchema` and route into `compileScenario`. The canonical `ScenarioPackage` contract is never bypassed.\n\n```typescript\nimport { WorldModel } from 'paracosm';\n\nconst wm = await WorldModel.fromPrompt({\n  seedText: 'Q3 board brief: the company must decide between...',\n  domainHint: 'corporate strategic decision',\n});\n\nconst { actors, artifacts } = await wm.quickstart({ actorCount: 3 });\nartifacts.forEach((a, i) =\u003e console.log(actors[i].name, a.fingerprint));\n```\n\nIn the dashboard, Quickstart is the default landing tab. A user pastes a brief, drops a PDF, or supplies a URL, and three streaming actors arrive within a minute of first click. A curated library of HEXACO archetypes ships at `paracosm.ACTOR_PRESETS` for programmatic `wm.batch` sweeps.\n\n---\n\n## Install\n\n```bash\nnpm install paracosm   # also: pnpm add paracosm · bun add paracosm\n```\n\nParacosm ships as pure ESM. The root export covers most use cases (`run`, `runMany`, `WorldModel`, `compileScenario`, `marsScenario`, `lunarScenario`, `ACTOR_PRESETS`, all public types). Subpath escape hatches are kept for power users: `paracosm/compiler`, `paracosm/schema`, `paracosm/swarm`, `paracosm/digital-twin`, `paracosm/core`. Node 20+, Bun 1.x, and any TypeScript runner with ESM and import-attributes support resolve them out of the box.\n\n---\n\n## Defining a world\n\nThe authoring contract is JSON because JSON validates, diffs, caches, and snapshots. A draft can be hand-written, generated from a prompt, or grounded with `seedText` / `seedUrl`.\n\n```json\n{\n  \"id\": \"submarine-habitat\",\n  \"labels\": {\n    \"name\": \"Deep Ocean Habitat\",\n    \"populationNoun\": \"crew\",\n    \"settlementNoun\": \"habitat\",\n    \"timeUnitNoun\": \"day\",\n    \"currency\": \"credits\"\n  },\n  \"setup\": {\n    \"defaultTurns\": 8,\n    \"defaultPopulation\": 50,\n    \"defaultStartTime\": 2040,\n    \"defaultSeed\": 42\n  },\n  \"departments\": [\n    {\n      \"id\": \"life-support\",\n      \"label\": \"Life Support\",\n      \"role\": \"Chief Life Support Officer\",\n      \"instructions\": \"Analyze O2 levels, CO2 scrubbing capacity, water recycling.\"\n    },\n    {\n      \"id\": \"engineering\",\n      \"label\": \"Engineering\",\n      \"role\": \"Chief Engineer\",\n      \"instructions\": \"Analyze hull integrity, pressure systems, power generation.\"\n    }\n  ],\n  \"metrics\": [\n    { \"id\": \"population\", \"format\": \"number\" },\n    { \"id\": \"morale\", \"format\": \"percent\" }\n  ]\n}\n```\n\nEvery scenario declares its own vocabulary via `labels.populationNoun` (plural), `labels.settlementNoun` (singular), and `labels.timeUnitNoun`. The dashboard, kernel, and progression hooks pick those up everywhere user-facing copy renders. Without overrides, paracosm falls back to `colonists` / `colony` / `tick`.\n\nTime is unit-agnostic. `setup.defaultTimePerTurn` and `setup.defaultStartTime` are plain numbers; whether they represent years, quarters, hours, or ticks is decided by `timeUnitNoun`. The dashboard turn header reads `Quarter 5`, `Day 22`, or `Year 2043` straight from the label.\n\n---\n\n## Compile and run\n\n```typescript\nimport { compileScenario, WorldModel } from 'paracosm';\nimport worldJson from './my-world.json' with { type: 'json' };\n\n// First compile is roughly $0.10 and caches to disk; reruns are free\nconst scenario = await compileScenario(worldJson, {\n  provider: 'anthropic',\n  model: 'claude-sonnet-4-6',\n});\nconst wm = WorldModel.fromScenario(scenario);\n\nconst result = await wm.simulate({\n  actor,\n  maxTurns: 6,\n  seed: 42,\n  // costPreset: 'economy',  // ~5-10× cheaper iteration on OpenAI\n  onEvent(e) { console.log(actor.name, e.type, e.data.summary); },\n});\n\nconsole.log(result.metadata.scenario.name, '→', result.fingerprint);\nconsole.log('cost      $', result.cost?.totalUSD.toFixed(2));\nconsole.log('final       ', result.finalState?.metrics);\nconsole.log('forged tools ', result.forgedTools?.length ?? 0);\nconsole.log('citations    ', result.citations?.length ?? 0);\n```\n\nEach call to `wm.simulate` takes one actor. Run one, two, or twenty. The dashboard runs two side-by-side for comparison; the API has no limit.\n\n### Or use the dashboard\n\n```bash\ngit clone https://github.com/framersai/paracosm\ncd paracosm \u0026\u0026 npm install\ncp .env.example .env  # add OPENAI_API_KEY or ANTHROPIC_API_KEY\nnpm run dashboard     # opens http://localhost:3456\n```\n\nThe dashboard ships a scenario editor for writing, importing, compiling, and running custom worlds from the browser, plus the live Branches view for forks.\n\n### Or run the standalone CLI\n\n```bash\nnpm install -g paracosm\n\nparacosm run                                        # actors.json + default scenario\nparacosm run --name \"Reyes\" --openness 0.85 --turns 6\nparacosm dashboard 6                                # auto-launch with 6 turns\nparacosm compile scenarios/lunar.json --seed-url \u003curl\u003e --max-searches 5\nparacosm init my-app --domain \"Submarine crew of 8\" --actors 3\n```\n\nThe CLI looks for `actors.json` via `--actors`, then `./actors.json`, then `./config/actors.json`, then a bundled example. A back-compat `paracosm-dashboard` alias is shipped for existing scripts and Docker invocations.\n\n---\n\n## The universal result contract\n\nEvery simulation returns a `RunArtifact`: one Zod-validated shape exported from `paracosm/schema`. The same shape covers civilization sims (turn-loop), digital-twin runs (batch-trajectory), and one-shot forecasts (batch-point).\n\n```typescript\nimport { RunArtifactSchema, type RunArtifact } from 'paracosm/schema';\n\nconst wm = WorldModel.fromScenario(scenario);\nconst artifact: RunArtifact = await wm.simulate({ actor, maxTurns: 6 });\nconst parsed = RunArtifactSchema.parse(artifact);   // optional dev-mode validation\n\nswitch (artifact.metadata.mode) {\n  case 'turn-loop':         // civ sims: per-turn trajectory + decisions\n  case 'batch-trajectory':  // digital twin: labeled timepoints over a horizon\n  case 'batch-point':       // one-shot forecast: overview + risk flags\n}\n```\n\nFor non-TypeScript consumers, `npm run export:json-schema` emits `schema/run-artifact.schema.json` and `schema/stream-event.schema.json`. Python projects generate Pydantic types via `datamodel-codegen`; any ecosystem with a JSON-Schema generator adopts cleanly.\n\n---\n\n## Digital twins: subjects and interventions\n\nFor simulations that revolve around a single subject under an intervention, paracosm exposes a `DigitalTwin` subpath plus `SubjectConfig` and `InterventionConfig` as first-class input primitives.\n\n```typescript\nimport { DigitalTwin } from 'paracosm/digital-twin';\nimport { SubjectConfigSchema, InterventionConfigSchema } from 'paracosm/schema';\n\nconst twin = await DigitalTwin.fromJson(scenarioJson);\n\nconst subject = SubjectConfigSchema.parse({\n  id: 'user-42',\n  name: 'Alice',\n  profile: { age: 34, diet: 'mediterranean' },\n  signals: [{ label: 'HRV', value: 48.2, unit: 'ms', recordedAt: '2026-04-21T08:00:00Z' }],\n  markers: [{ id: 'rs4680', category: 'genome', value: 'AA' }],\n});\n\nconst intervention = InterventionConfigSchema.parse({\n  id: 'intv-1',\n  name: 'Creatine + Sleep Hygiene',\n  description: '5g daily + 11pm bedtime.',\n  duration: { value: 12, unit: 'weeks' },\n  adherenceProfile: { expected: 0.7 },\n});\n\nconst artifact = await twin.intervene({ subject, intervention, actor });\n```\n\n`DigitalTwin` is an alias of `WorldModel`. The subpath names the use case in the import path. `RunArtifact.subject` and `RunArtifact.intervention` carry through to any consumer.\n\n---\n\n## Trait models beyond HEXACO\n\nActors are not always human. Paracosm ships a `TraitModel` registry with two built-ins, and registering more is one call.\n\n| Model       | Axes                                                                                              | For                                                                |\n|-------------|---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------|\n| `hexaco`    | openness, conscientiousness, extraversion, agreeableness, emotionality, honesty-humility           | CEOs, captains, governors, councils, military commanders           |\n| `ai-agent`  | exploration, verification-rigor, deference, risk-tolerance, transparency, instruction-following    | Frontier-lab release directors, autonomous coordinators, eval subs |\n\n```typescript\nimport { WorldModel } from 'paracosm';\n\nconst releaseDirector = {\n  name: 'Atlas-Bot Release Director',\n  archetype: 'Aggressive AI Release Optimizer',\n  unit: 'Frontier Lab',\n  // hexaco is optional when traitProfile is set; a representative\n  // snapshot is also accepted.\n  traitProfile: {\n    modelId: 'ai-agent',\n    traits: {\n      exploration: 0.85,\n      'verification-rigor': 0.2,\n      deference: 0.2,\n      'risk-tolerance': 0.85,\n      transparency: 0.4,\n      'instruction-following': 0.4,\n    },\n  },\n  instructions: 'You weight time-to-market. Verification is overhead.',\n};\n\nconst wmAi = WorldModel.fromScenario(scenario);\nawait wmAi.simulate({ actor: releaseDirector, maxTurns: 6, seed: 42 });\n```\n\nThe orchestrator's `normalizeActorConfig` accepts either shape. End-to-end captures and full surface live in [`docs/COOKBOOK.md`](docs/COOKBOOK.md).\n\n---\n\n## Cost envelope\n\nRunning a simulation calls real LLM APIs against the user's key. Paracosm assigns a different model tier per role so flagship cost only lands where it earns its keep (forge-code correctness).\n\n| Preset                | Departments                          | Commander · Director · Judge                       | Reactions                                          | OpenAI / run | Anthropic / run |\n|-----------------------|--------------------------------------|-----------------------------------------------------|----------------------------------------------------|--------------|-----------------|\n| `quality` (default)   | gpt-5.4 · claude-sonnet-4-6          | gpt-5.4-mini · claude-haiku-4-5-20251001            | gpt-5.4-nano · claude-haiku-4-5-20251001           | ~$1 to $3    | ~$3 to $7       |\n| `economy`             | gpt-4o · claude-sonnet-4-6           | gpt-5.4-nano · claude-haiku-4-5-20251001            | gpt-5.4-nano · claude-haiku-4-5-20251001           | ~$0.20 to $0.60 | ~$3 to $5    |\n\nNumbers assume 6 turns, 5 departments, 100 agents, up to 3 events per turn. Forge approval rate drops 10 to 20 points on `economy` because the mid-tier department model occasionally violates structured-output schemas the judge rejects. Use `economy` for iteration and CI; use `quality` for publishable runs. Explicit `models` entries always win over the preset, so per-role overrides combine cleanly with global defaults.\n\n`WorldModel.simulate` returns a `cost` field with token counts, LLM call counts, and USD spend. Every stable system prefix routes through a `cacheBreakpoint: true` block, so on Anthropic the shared prefix serves from prompt cache at one-tenth input cost from turn 2 onward; OpenAI auto-caches any prompt over 1024 tokens. The `cost.caches` field reports tokens read, tokens created, and USD saved per run.\n\n---\n\n## How a turn runs\n\nDirector event → Kernel advance (deterministic, seeded) → Department analysis in parallel (with optional runtime tool forging in a hardened `node:vm` sandbox; an LLM judge approves each forge) → Commander decision (HEXACO-weighted) → Outcome classification → Kernel effects → Agent reactions → Memory consolidation → Personality drift.\n\nEvery structured LLM call (director, departments, commander, reactions, verdict) is Zod-validated with retry-with-feedback. Schemas under [`src/runtime/validators/`](src/runtime/validators/). Full per-stage breakdown in [docs/architecture.md](docs/architecture.md).\n\n---\n\n## Seed enrichment\n\n`paracosm compile \u003cscenario.json\u003e --seed-text \"...\"` or `--seed-url \u003curl\u003e` extracts topics, searches across Firecrawl + Tavily + Serper + Brave in parallel, reranks with Cohere `rerank-v3.5`, ingests the result into an AgentOS `AgentMemory.sqlite()` store, and threads citations into department prompts. Bundle cached per-seed. Surface citations land in the dashboard's Reports tab.\n\n---\n\n## Built-in scenarios + APIs\n\n`marsScenario` (100 colonists, 6 turns over 48 years; 5 departments) and `lunarScenario` (50-person south-pole crew; regolith + 1/6g) ship from the `paracosm` root as references for custom scenarios.\n\nProgrammatic surfaces: `paracosm` root (`run`, `runMany`, `WorldModel`, `compileScenario`, `createParacosmClient`), plus `paracosm/{compiler,schema,swarm,digital-twin,core}` for deeper paths. Provider / preset / model defaults can be pinned per client or via `PARACOSM_*` env vars. Full reference + every method signature: [`docs/COOKBOOK.md`](docs/COOKBOOK.md).\n\nFor non-SSE consumers there's `POST /simulate` (gated on `PARACOSM_ENABLE_SIMULATE_ENDPOINT=true`) and nine read-and-replay routes under `/api/v1/*`. Wire-level details: [`docs/HTTP_API.md`](docs/HTTP_API.md).\n\nStorage: SQLite by default, Postgres / sql.js / IndexedDB via `STORAGE_ADAPTER=` env. Run history (Library) and session blobs (Load menu) share the same schema. Admin write routes (`/admin/sessions/save`, `/admin/data/wipe`) require both `ADMIN_WRITE=true` and an `ADMIN_TOKEN` bearer; off by default.\n\n---\n\n## Architecture\n\n```\nsrc/\n  engine/         the npm package\n    core/         deterministic kernel: RNG, state, progression, personality drift\n    compiler/     scenario draft + source grounding to ScenarioPackage compiler\n    mars/         Mars Genesis scenario\n    lunar/        Lunar Outpost scenario\n\n  runtime/        orchestration (not exported)\n    orchestrator           turn pipeline: director, kernel, departments, commander\n    director               emergent event generation from simulation state\n    departments            parallel department analysis agents\n    agent-reactions        batched agent reactions, 10 agents per LLM call\n    agent-memory           persistent memory, consolidation, stance drift\n    chat-agents            post-simulation conversational agents\n    schemas/               Zod schemas for every structured LLM call\n    llm-invocations/       generateValidatedObject + sendAndValidate wrappers\n    hexaco-cues/           trajectory and reaction cue translation helpers\n\n  cli/            server + dashboard (not exported)\n    serve.ts      HTTP + SSE server\n    dashboard/    React + Vite live visualization, cellular automata viz\n```\n\nThe engine owns the chassis. The scenario owns the domain. The kernel handles state, time, randomness, and invariants. The scenario handles event categories, department instructions, progression hooks, and research citations. The orchestrator connects them.\n\n---\n\n## Built on AgentOS\n\n\u003e \"You are not the kind of dead that can be brought back.\"\n\u003e\n\u003e *SOMA*, Frictional Games, 2015\n\nParacosm uses [AgentOS](https://agentos.sh/en) for agent orchestration, LLM dispatch, tool forging, and memory. The composition is what makes the runs feel inhabited rather than scripted: department heads remember, specialists invent tools mid-decision, and the LLM judge holds the line on safety before any forge enters the pipeline.\n\n| AgentOS API                  | Used for                                                              |\n|------------------------------|-----------------------------------------------------------------------|\n| `agent()`                    | Commander, department, and Event Director agents                      |\n| `generateText()`             | LLM calls for event generation and tool evaluation                    |\n| `EmergentCapabilityEngine`   | Runtime tool forging in a hardened node:vm sandbox                    |\n| `EmergentJudge`              | LLM-as-judge safety review of forged tools                            |\n| `WebSearchService`           | Multi-provider seed enrichment with Firecrawl, Tavily, Serper, Brave  |\n| `AgentMemory`                | Per-run citation memory with semantic recall                          |\n\n---\n\n## Open source vs hosted\n\n|                  | Open source (Apache-2.0)                                           | Hosted (planned)                                                      |\n|------------------|--------------------------------------------------------------------|------------------------------------------------------------------------|\n| Actors           | Unlimited via API. Dashboard shows two side-by-side.               | N actors in parallel, fleet management UI.                             |\n| Simulations      | Sequential or self-managed parallelism.                            | Distributed parallelization across worker nodes.                       |\n| Scenarios        | JSON + compiler, unlimited.                                         | Visual scenario editor, team sharing, version control.                |\n| Agent chat       | Available after the first turn completes.                           | Persistent agents with durable memory across sessions.                |\n| Cost             | Free forever. The user supplies LLM API keys.                       | Tiered pricing for teams, organizations, and government agencies.     |\n| Support          | Community via Discord and GitHub.                                   | SLA, dedicated support, private deployment.                            |\n\nThe open-source engine is the permanent foundation. The hosted product targets organizations that need to run dozens or hundreds of simulations in parallel: defense agencies stress-testing doctrine, corporations modeling leadership scenarios, game studios generating divergent NPC civilizations at scale. Contact [team@frame.dev](mailto:team@frame.dev) for early access.\n\n---\n\n## Links\n\n|                |                                                              |\n|----------------|--------------------------------------------------------------|\n| Live demo      | [paracosm.agentos.sh/sim](https://paracosm.agentos.sh/sim)   |\n| Landing page   | [paracosm.agentos.sh](https://paracosm.agentos.sh)           |\n| API docs       | [paracosm.agentos.sh/docs](https://paracosm.agentos.sh/docs) |\n| npm            | [npmjs.com/package/paracosm](https://www.npmjs.com/package/paracosm) |\n| AgentOS        | [agentos.sh](https://agentos.sh/en)                              |\n| Discord        | [wilds.ai/discord](https://wilds.ai/discord)                  |\n\n## License\n\nApache-2.0\n\n---\n\n\u003cp align=\"center\"\u003e\n  Built by \u003ca href=\"https://manic.agency\"\u003eManic Agency LLC\u003c/a\u003e · \u003ca href=\"https://frame.dev\"\u003eFrame.dev\u003c/a\u003e\u003cbr /\u003e\n  \u003ca href=\"mailto:team@frame.dev\"\u003eteam@frame.dev\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fframersai%2Fparacosm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fframersai%2Fparacosm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fframersai%2Fparacosm/lists"}