paracosm 0.4.384 → 0.4.385

package/README.md

@@ -305,11 +305,71 @@ Everything the dashboard does is also available as library calls. The exports fa
 | Import | Surface |
 |--------|---------|
 | `paracosm/compiler` | `compileScenario`, `ingestSeed`, `ingestFromUrl`, type `CompileOptions` |
-| `paracosm/runtime`  | `runSimulation`, `runBatch`, `EventDirector`, `generateAgentReactions`, `buildEventSummary`, memory helpers, type `CostPreset` |
-| `paracosm`          | `ProviderKeyMissingError`, `SeededRng`, `SimulationKernel`, all `Scenario*` types |
+| `paracosm/runtime`  | `runSimulation`, `runBatch`, `EventDirector`, `generateAgentReactions`, `buildEventSummary`, `createParacosmClient`, memory helpers, type `CostPreset` |
+| `paracosm`          | `createParacosmClient`, `ProviderKeyMissingError`, `SeededRng`, `SimulationKernel`, all `Scenario*` types |
 | `paracosm/core`     | Kernel state types (`Agent`, `WorldState`, `HexacoProfile`, …) |
 | `paracosm/mars`, `paracosm/lunar` | Pre-built `ScenarioPackage` constants to use or fork |
 
+### Client — global defaults + env-var config
+
+`createParacosmClient` pins `provider`, `costPreset`, per-role `models`, and compile-time options once, then hands back `runSimulation` / `runBatch` / `compileScenario` methods that inherit those defaults. Per-call overrides still win, merged at the per-role level so `models: { departments: 'gpt-5.4' }` at the client and `models: { judge: 'gpt-5.4' }` at the call combine to pin both roles instead of one replacing the other.
+
+```typescript
+import { createParacosmClient } from 'paracosm';
+
+const client = createParacosmClient({
+  provider: 'openai',
+  costPreset: 'economy',               // cheap default for iteration
+  models: { departments: 'gpt-5.4' },  // but pin departments to flagship
+  compilerProvider: 'anthropic',       // compile on a different provider if you want
+  compilerModel: 'claude-sonnet-4-6',
+});
+
+const scenario = await client.compileScenario(worldJson);
+const out = await client.runSimulation(leader, [], { maxTurns: 6, seed: 42 });
+
+// Promote one specific run to quality without touching the client:
+const gold = await client.runSimulation(leader, [], {
+  maxTurns: 8, seed: 42, costPreset: 'quality',
+});
+
+// Batch 20 ablations with shared config:
+const manifest = await client.runBatch({
+  scenarios: [scenarioA, scenarioB], leaders, turns: 6, seed: 42, maxConcurrency: 4,
+});
+```
+
+Env vars feed the same defaults and are read once at `createParacosmClient` construction. Explicit args win over env; env wins over the built-in library defaults.
+
+| Env var | Maps to | Valid values |
+|---------|---------|--------------|
+| `PARACOSM_PROVIDER` | `provider` | `openai` / `anthropic` |
+| `PARACOSM_COST_PRESET` | `costPreset` | `quality` / `economy` |
+| `PARACOSM_MODEL_COMMANDER` | `models.commander` | any provider-valid model id |
+| `PARACOSM_MODEL_DEPARTMENTS` | `models.departments` | any provider-valid model id |
+| `PARACOSM_MODEL_JUDGE` | `models.judge` | any provider-valid model id |
+| `PARACOSM_MODEL_DIRECTOR` | `models.director` | any provider-valid model id |
+| `PARACOSM_MODEL_AGENT_REACTIONS` | `models.agentReactions` | any provider-valid model id |
+| `PARACOSM_COMPILER_PROVIDER` | `compilerProvider` | `openai` / `anthropic` |
+| `PARACOSM_COMPILER_MODEL` | `compilerModel` | any provider-valid model id |
+
+Invalid values (typos, unknown providers) are silently ignored so bad env state can't crash boot — the client falls back to the next layer. Empty or whitespace-only env values are treated as unset.
+
+```bash
+# Zero-code config for hosting / CI:
+PARACOSM_PROVIDER=anthropic \
+PARACOSM_COST_PRESET=economy \
+PARACOSM_MODEL_DEPARTMENTS=claude-sonnet-4-6 \
+  node my-runner.js
+```
+
+```typescript
+// my-runner.js reads them all implicitly:
+const client = createParacosmClient();   // no args, pulls from env
+```
+
+Direct `runSimulation(...)` / `runBatch(...)` / `compileScenario(...)` calls without a client are still fully supported — the client is purely additive for multi-run workflows.
+
 ### Batch runner — N scenarios × M leaders
 
 ```typescript

package/dist/engine/index.d.ts

@@ -24,4 +24,7 @@ export { marsScenario } from './mars/index.js';
 export { lunarScenario } from './lunar/index.js';
 export { ProviderKeyMissingError, resolveProviderWithFallback } from './provider-resolver.js';
 export type { ResolvedProviderChoice, ResolveProviderOptions } from './provider-resolver.js';
+export { createParacosmClient } from '../runtime/client.js';
+export type { ParacosmClient, ParacosmClientOptions } from '../runtime/client.js';
+export type { CostPreset } from '../cli/sim-config.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/engine/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,UAAU,EACV,eAAe,EACf,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,sBAAsB,EACtB,iBAAiB,EACjB,aAAa,GACd,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAG1H,YAAY,EACV,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,gBAAgB,EACtG,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,kBAAkB,EAChE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,GACnE,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3F,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,qBAAqB,EAAE,QAAQ,EAAE,cAAc,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGjJ,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG7D,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAMjD,OAAO,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAC9F,YAAY,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,UAAU,EACV,eAAe,EACf,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,sBAAsB,EACtB,iBAAiB,EACjB,aAAa,GACd,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAG1H,YAAY,EACV,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,gBAAgB,EACtG,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,kBAAkB,EAChE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,GACnE,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3F,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,qBAAqB,EAAE,QAAQ,EAAE,cAAc,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGjJ,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG7D,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAMjD,OAAO,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAC9F,YAAY,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAM7F,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAClF,YAAY,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/engine/index.js

@@ -21,4 +21,9 @@ export { lunarScenario } from './lunar/index.js';
 // lets tools/tests drive the resolver without importing from internal
 // paths.
 export { ProviderKeyMissingError, resolveProviderWithFallback } from './provider-resolver.js';
+// Top-level client re-export so `import { createParacosmClient } from
+// 'paracosm'` works. Keeps the discoverability bar low for new users:
+// one import for the most common entry point, deeper imports available
+// via `paracosm/runtime` and `paracosm/compiler` when needed.
+export { createParacosmClient } from '../runtime/client.js';
 //# sourceMappingURL=index.js.map

package/dist/engine/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA4BH,aAAa;AACb,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,cAAc;AACd,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAoB1H,oBAAoB;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,8DAA8D;AAC9D,oEAAoE;AACpE,sEAAsE;AACtE,SAAS;AACT,OAAO,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA4BH,aAAa;AACb,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,cAAc;AACd,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAoB1H,oBAAoB;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,8DAA8D;AAC9D,oEAAoE;AACpE,sEAAsE;AACtE,SAAS;AACT,OAAO,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAG9F,sEAAsE;AACtE,sEAAsE;AACtE,uEAAuE;AACvE,8DAA8D;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/runtime/client.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Paracosm client — one-call factory that pins `provider`, `costPreset`,
+ * per-role `models`, and compile-time options once, then hands back
+ * methods that inherit those defaults on every call.
+ *
+ * Problem it solves: a typical programmatic workflow runs 10-50
+ * simulations (batch sweeps, CI regression checks, per-scenario
+ * ablations). Passing the same `{ provider, costPreset, models }` on
+ * every `runSimulation(leader, [], { ... })` call is noisy and
+ * error-prone; a typo in one config entry silently breaks that run's
+ * model routing without breaking the others. The client centralizes
+ * the defaults so per-call overrides become the exception, not the
+ * baseline.
+ *
+ * Layering (lowest precedence to highest):
+ *   1. Built-in defaults from `DEFAULT_MODELS` / `DEMO_MODELS`
+ *   2. `PARACOSM_*` env vars (read once at client construction)
+ *   3. Explicit `createParacosmClient({ ... })` args
+ *   4. Per-call overrides on `client.runSimulation(leader, [], { ... })`
+ *
+ * Each higher layer merges over the lower one; `models` merges at the
+ * per-role level so you can pin `departments: 'gpt-5.4'` at the client
+ * and still override `judge` per call.
+ *
+ * @module paracosm/runtime/client
+ */
+import { runSimulation, type RunOptions, type LeaderConfig } from './orchestrator.js';
+import { type BatchConfig, type BatchManifest } from './batch.js';
+import type { CompileOptions } from '../engine/compiler/types.js';
+import type { KeyPersonnel } from '../engine/core/agent-generator.js';
+import type { LlmProvider, ScenarioPackage, SimulationModelConfig } from '../engine/types.js';
+import type { CostPreset } from '../cli/sim-config.js';
+/** Options passed to `createParacosmClient`. Every field is optional and composes with env-var reads. */
+export interface ParacosmClientOptions {
+    /**
+     * Default provider for `runSimulation` / `runBatch`. Env fallback:
+     * `PARACOSM_PROVIDER=openai` or `=anthropic`. Per-call `opts.provider`
+     * still wins.
+     */
+    provider?: LlmProvider;
+    /**
+     * Default cost preset. Env fallback: `PARACOSM_COST_PRESET=quality`
+     * or `=economy`.
+     */
+    costPreset?: CostPreset;
+    /**
+     * Per-role model pins. Env fallbacks:
+     *   PARACOSM_MODEL_COMMANDER, PARACOSM_MODEL_DEPARTMENTS,
+     *   PARACOSM_MODEL_JUDGE, PARACOSM_MODEL_DIRECTOR,
+     *   PARACOSM_MODEL_AGENT_REACTIONS
+     * Merged at the per-role level, not whole-object: setting
+     * `models: { departments: 'gpt-5.4' }` pins departments but leaves
+     * commander / director / judge / agentReactions flowing from the
+     * preset as before.
+     */
+    models?: Partial<SimulationModelConfig>;
+    /**
+     * Provider to use for compile-time LLM calls in `client.compileScenario`.
+     * Defaults to `provider` when unset so most users only configure one
+     * provider. Env fallback: `PARACOSM_COMPILER_PROVIDER`.
+     */
+    compilerProvider?: LlmProvider;
+    /**
+     * Model to use for compile-time LLM calls. Env fallback:
+     * `PARACOSM_COMPILER_MODEL`. If omitted the compiler picks a
+     * provider-default (gpt-5.4-mini on OpenAI, claude-sonnet-4-6 on
+     * Anthropic).
+     */
+    compilerModel?: string;
+}
+/**
+ * Handle returned by `createParacosmClient`. The three methods mirror
+ * the corresponding standalone exports — same arg shapes, same return
+ * types — but with the client's defaults layered in.
+ */
+export interface ParacosmClient {
+    /**
+     * Run one simulation. Leader + key personnel passed per-call; all
+     * other options inherit from the client with per-call overrides.
+     */
+    runSimulation: (leader: LeaderConfig, keyPersonnel: KeyPersonnel[], opts?: RunOptions) => ReturnType<typeof runSimulation>;
+    /**
+     * Run a batch sweep. Scenarios / leaders / turns / seed are the
+     * caller's responsibility; provider + costPreset + models inherit.
+     */
+    runBatch: (config: BatchConfig) => Promise<BatchManifest>;
+    /**
+     * Compile a scenario with the client's compiler defaults.
+     */
+    compileScenario: (scenarioJson: Record<string, unknown>, opts?: CompileOptions) => Promise<ScenarioPackage>;
+}
+/**
+ * Create a Paracosm client with pinned defaults. Env vars are read once
+ * at construction; subsequent `process.env` mutations won't retrigger.
+ *
+ * @example
+ * ```typescript
+ * import { createParacosmClient } from 'paracosm/runtime';
+ *
+ * const client = createParacosmClient({
+ *   provider: 'openai',
+ *   costPreset: 'economy',
+ *   models: { departments: 'gpt-5.4' },  // pin only departments to flagship
+ * });
+ *
+ * const scenario = await client.compileScenario(worldJson);
+ * const out = await client.runSimulation(leader, [], { maxTurns: 6, seed: 42 });
+ *
+ * // Per-call override wins over client defaults:
+ * const quality = await client.runSimulation(leader, [], {
+ *   maxTurns: 8, seed: 42,
+ *   costPreset: 'quality',  // promote this one run to flagship
+ * });
+ * ```
+ *
+ * @example Env-driven (zero-code config for hosting / CI):
+ * ```bash
+ * PARACOSM_PROVIDER=anthropic \
+ * PARACOSM_COST_PRESET=economy \
+ * PARACOSM_MODEL_DEPARTMENTS=claude-sonnet-4-6 \
+ *   node my-runner.js
+ * ```
+ * ```typescript
+ * const client = createParacosmClient();  // no args — reads from env
+ * ```
+ */
+export declare function createParacosmClient(options?: ParacosmClientOptions): ParacosmClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/runtime/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/runtime/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,aAAa,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtF,OAAO,EAAY,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC9F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,yGAAyG;AACzG,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACxC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,WAAW,CAAC;IAC/B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,aAAa,EAAE,CACb,MAAM,EAAE,YAAY,EACpB,YAAY,EAAE,YAAY,EAAE,EAC5B,IAAI,CAAC,EAAE,UAAU,KACd,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;IACtC;;;OAGG;IACH,QAAQ,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1D;;OAEG;IACH,eAAe,EAAE,CACf,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,IAAI,CAAC,EAAE,cAAc,KAClB,OAAO,CAAC,eAAe,CAAC,CAAC;CAC/B;AAiDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,CA2CxF"}

package/dist/runtime/client.js

@@ -0,0 +1,155 @@
+/**
+ * Paracosm client — one-call factory that pins `provider`, `costPreset`,
+ * per-role `models`, and compile-time options once, then hands back
+ * methods that inherit those defaults on every call.
+ *
+ * Problem it solves: a typical programmatic workflow runs 10-50
+ * simulations (batch sweeps, CI regression checks, per-scenario
+ * ablations). Passing the same `{ provider, costPreset, models }` on
+ * every `runSimulation(leader, [], { ... })` call is noisy and
+ * error-prone; a typo in one config entry silently breaks that run's
+ * model routing without breaking the others. The client centralizes
+ * the defaults so per-call overrides become the exception, not the
+ * baseline.
+ *
+ * Layering (lowest precedence to highest):
+ *   1. Built-in defaults from `DEFAULT_MODELS` / `DEMO_MODELS`
+ *   2. `PARACOSM_*` env vars (read once at client construction)
+ *   3. Explicit `createParacosmClient({ ... })` args
+ *   4. Per-call overrides on `client.runSimulation(leader, [], { ... })`
+ *
+ * Each higher layer merges over the lower one; `models` merges at the
+ * per-role level so you can pin `departments: 'gpt-5.4'` at the client
+ * and still override `judge` per call.
+ *
+ * @module paracosm/runtime/client
+ */
+import { runSimulation } from './orchestrator.js';
+import { runBatch } from './batch.js';
+import { compileScenario } from '../engine/compiler/index.js';
+const VALID_PROVIDERS = ['openai', 'anthropic'];
+const VALID_PRESETS = ['quality', 'economy'];
+function envString(key) {
+    const env = typeof process !== 'undefined' && process.env ? process.env : undefined;
+    if (!env)
+        return undefined;
+    const v = env[key];
+    if (typeof v !== 'string')
+        return undefined;
+    const trimmed = v.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function readEnvClientOptions() {
+    const rawProvider = envString('PARACOSM_PROVIDER');
+    const rawCompilerProvider = envString('PARACOSM_COMPILER_PROVIDER');
+    const rawPreset = envString('PARACOSM_COST_PRESET');
+    const provider = rawProvider && VALID_PROVIDERS.includes(rawProvider)
+        ? rawProvider
+        : undefined;
+    const compilerProvider = rawCompilerProvider && VALID_PROVIDERS.includes(rawCompilerProvider)
+        ? rawCompilerProvider
+        : undefined;
+    const costPreset = rawPreset && VALID_PRESETS.includes(rawPreset)
+        ? rawPreset
+        : undefined;
+    const models = {};
+    const commander = envString('PARACOSM_MODEL_COMMANDER');
+    const departments = envString('PARACOSM_MODEL_DEPARTMENTS');
+    const judge = envString('PARACOSM_MODEL_JUDGE');
+    const director = envString('PARACOSM_MODEL_DIRECTOR');
+    const agentReactions = envString('PARACOSM_MODEL_AGENT_REACTIONS');
+    if (commander)
+        models.commander = commander;
+    if (departments)
+        models.departments = departments;
+    if (judge)
+        models.judge = judge;
+    if (director)
+        models.director = director;
+    if (agentReactions)
+        models.agentReactions = agentReactions;
+    return {
+        provider,
+        compilerProvider,
+        costPreset,
+        models: Object.keys(models).length > 0 ? models : undefined,
+        compilerModel: envString('PARACOSM_COMPILER_MODEL'),
+    };
+}
+/**
+ * Create a Paracosm client with pinned defaults. Env vars are read once
+ * at construction; subsequent `process.env` mutations won't retrigger.
+ *
+ * @example
+ * ```typescript
+ * import { createParacosmClient } from 'paracosm/runtime';
+ *
+ * const client = createParacosmClient({
+ *   provider: 'openai',
+ *   costPreset: 'economy',
+ *   models: { departments: 'gpt-5.4' },  // pin only departments to flagship
+ * });
+ *
+ * const scenario = await client.compileScenario(worldJson);
+ * const out = await client.runSimulation(leader, [], { maxTurns: 6, seed: 42 });
+ *
+ * // Per-call override wins over client defaults:
+ * const quality = await client.runSimulation(leader, [], {
+ *   maxTurns: 8, seed: 42,
+ *   costPreset: 'quality',  // promote this one run to flagship
+ * });
+ * ```
+ *
+ * @example Env-driven (zero-code config for hosting / CI):
+ * ```bash
+ * PARACOSM_PROVIDER=anthropic \
+ * PARACOSM_COST_PRESET=economy \
+ * PARACOSM_MODEL_DEPARTMENTS=claude-sonnet-4-6 \
+ *   node my-runner.js
+ * ```
+ * ```typescript
+ * const client = createParacosmClient();  // no args — reads from env
+ * ```
+ */
+export function createParacosmClient(options = {}) {
+    const fromEnv = readEnvClientOptions();
+    // Explicit args win over env; env wins over the built-in library
+    // defaults further down the call chain (DEFAULT_MODELS / DEMO_MODELS).
+    const provider = options.provider ?? fromEnv.provider;
+    const costPreset = options.costPreset ?? fromEnv.costPreset;
+    const mergedModels = {
+        ...fromEnv.models,
+        ...options.models,
+    };
+    const compilerProvider = options.compilerProvider
+        ?? fromEnv.compilerProvider
+        ?? provider;
+    const compilerModel = options.compilerModel ?? fromEnv.compilerModel;
+    const hasClientModels = Object.keys(mergedModels).length > 0;
+    return {
+        runSimulation: (leader, keyPersonnel, opts = {}) => runSimulation(leader, keyPersonnel, {
+            ...opts,
+            provider: opts.provider ?? provider,
+            costPreset: opts.costPreset ?? costPreset,
+            // Per-role merge so caller's override only stomps the role(s)
+            // they specified, not the whole client pin.
+            models: hasClientModels || opts.models
+                ? { ...mergedModels, ...opts.models }
+                : undefined,
+        }),
+        runBatch: (config) => runBatch({
+            ...config,
+            provider: config.provider ?? provider,
+            costPreset: config.costPreset ?? costPreset,
+            models: hasClientModels || config.models
+                ? { ...mergedModels, ...config.models }
+                : undefined,
+        }),
+        compileScenario: (scenarioJson, opts = {}) => compileScenario(scenarioJson, {
+            ...opts,
+            provider: opts.provider ?? compilerProvider,
+            model: opts.model ?? compilerModel,
+        }),
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/runtime/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/runtime/client.ts"],"names":[],"mappings":"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"}

package/dist/runtime/index.d.ts

@@ -6,6 +6,8 @@
 export { runSimulation, buildEventSummary } from './orchestrator.js';
 export type { RunOptions, SimEvent, SimEventType, SimEventPayloadMap, SimEventCostPayload, LeaderConfig, } from './orchestrator.js';
 export type { CostPreset } from '../cli/sim-config.js';
+export { createParacosmClient } from './client.js';
+export type { ParacosmClient, ParacosmClientOptions } from './client.js';
 export { EventDirector } from './director.js';
 export type { DirectorEvent, DirectorCrisis, DirectorContext, EventCategory, CrisisCategory } from './director.js';
 export type { DepartmentReport, CommanderDecision, TurnArtifact, CrisisResearchPacket } from './contracts.js';

package/dist/runtime/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACrE,YAAY,EACV,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,GACb,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACnH,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC9G,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC1E,OAAO,EACL,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,iBAAiB,EACjB,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,gCAAgC,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACrE,YAAY,EACV,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,GACb,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACnH,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC9G,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC1E,OAAO,EACL,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,iBAAiB,EACjB,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,gCAAgC,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/runtime/index.js

@@ -4,6 +4,7 @@
  * Run simulations with AI agents, crisis directors, and department analysis.
  */
 export { runSimulation, buildEventSummary } from './orchestrator.js';
+export { createParacosmClient } from './client.js';
 export { EventDirector } from './director.js';
 export { buildDepartmentContext, getDepartmentsForTurn } from './departments.js';
 export { generateAgentReactions } from './agent-reactions.js';

package/dist/runtime/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAUrE,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9C,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,OAAO,EACL,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAMhC,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,gCAAgC,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAUrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9C,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,OAAO,EACL,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAMhC,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,gCAAgC,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paracosm",
-  "version": "0.4.384",
+  "version": "0.4.385",
   "description": "AI agent swarm simulation engine with emergent crises, runtime tool forging, HEXACO personality drift, and deterministic kernels. Built on AgentOS.",
   "type": "module",
   "main": "dist/engine/index.js",