Skip to content

Commit a4007b2

Browse files
RandomOscillationsRandomOscillations
committed
release 0.4.0
1 parent b417451 commit a4007b2

4 files changed

Lines changed: 323 additions & 2 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Changelog
2+
3+
All notable changes to this project are documented in this file.
4+
5+
This project follows semantic versioning.
6+
7+
## [0.4.0] - 2026-02-24
8+
9+
### Summary
10+
11+
`v0.4.0` is a major operational release focused on pipeline coherence, runtime realism,
12+
and reliability under production-scale studies. The release consolidates the CLI around
13+
the scenario-first study model, hardens sampling and network quality gates, and upgrades
14+
simulation behavior for evolving timelines with stronger re-reasoning and conversation
15+
control.
16+
17+
Compared to `v0.3.0`, this release significantly changes how studies are authored and run:
18+
the old base-plus-extend workflow is fully absorbed into `scenario`, command surfaces are
19+
streamlined, and simulation/stopping semantics are now timeline-aware by default.
20+
21+
### Added
22+
23+
- Scenario-centric pipeline architecture:
24+
- scenario extension discovery/hydration integrated directly into `extropy scenario`.
25+
- versioned study artifacts for scenario and persona (`scenario.vN.yaml`, `persona.vN.yaml`).
26+
- Agent-mode operational support:
27+
- structured clarifications and deterministic exit-code-driven automation flow.
28+
- richer machine-safe command behavior across pipeline and query surfaces.
29+
- Advanced simulation realism controls:
30+
- timeline-safe stopping with future-event awareness and explicit early-convergence override.
31+
- epoch/provenance-based re-reasoning support for new information propagation.
32+
- conversation interleaving during timestep reasoning execution (instead of only terminal phase effects).
33+
- persisted and classified internal/external divergence (`THINK` vs `SAY`) with tracking support.
34+
- macro summary context and stronger action-intent accountability in reasoning prompts.
35+
- Chat and analysis improvements:
36+
- LLM-backed post-simulation chat (`chat ask`) with DB-grounded context.
37+
- query-first data extraction and inspection flow for agents, edges, states, network status, and SQL.
38+
- Model/provider capability expansion:
39+
- support for `claude-sonnet-4-6`.
40+
- improved long-response handling via streaming for Anthropic-backed calls.
41+
42+
### Changed
43+
44+
- CLI workflow and command contracts:
45+
- `extend` workflow removed from operational pipeline; scenario now owns extension generation.
46+
- default pipeline is now:
47+
`spec -> scenario -> persona -> sample -> network -> simulate -> results`.
48+
- `results` and `query` are now the canonical output/read path for analysis and export.
49+
- Study and schema semantics:
50+
- scenario and downstream runtime behavior are keyed by `scenario_id`-centric flows.
51+
- household configuration ownership moved from base spec concerns into scenario-level semantics.
52+
- `agent_focus_mode` moved into scenario ownership and enforcement path.
53+
- Sampling and household coherence:
54+
- stronger lifecycle normalization for household/member coherence.
55+
- exact target count fixes in sampling loops.
56+
- stricter handling of dependent naming and partner generation consistency.
57+
- Network generation behavior:
58+
- default network config generation is enabled for meaningful topology (`--generate-config` true).
59+
- CLI no longer forcibly overrides LLM-proposed `avg_degree` and `rewire_prob` unless user overrides.
60+
- deterministic structural role resolution and stricter topology gate hardening.
61+
- similarity worker auto-detection and resource tuning improvements.
62+
- Simulation execution/runtime tuning:
63+
- tighter re-reasoning and conversation budget guards.
64+
- improved async safety in conversation scheduling and runtime orchestration.
65+
- expanded runtime tunables and clearer fidelity-dependent behavior.
66+
- Documentation and operator runbooks:
67+
- command docs aligned to current CLI surface.
68+
- automation docs tightened for reproducible, non-interactive operation.
69+
70+
### Fixed
71+
72+
- Timeline and event correctness:
73+
- fixed timeline timestep validation edge behavior.
74+
- fixed evolution handling around timeline/outcome generation and timestep units.
75+
- Runtime and provider stability:
76+
- fixed token bucket internals usage bug with pydantic private attributes.
77+
- fixed async client reuse to prevent event-loop-close warnings.
78+
- fixed provider/runtime call paths for long-running reasoning calls.
79+
- CLI and model correctness:
80+
- fixed multiple command consistency issues and stale flag/help mismatches.
81+
- fixed validation routing for versioned scenario/persona files.
82+
- fixed scenario population reference resolution paths in estimate/validate/network/sample/simulate flows.
83+
- Persona/rendering quality:
84+
- fixed boolean/persona formatting edge cases.
85+
- fixed duplicate headers and empty population stats handling.
86+
- fixed currency/money rendering correctness in persona output.
87+
- Data quality and coherence:
88+
- fixed partner/dependent naming preservation and generation behavior.
89+
- fixed cases where reasoning-agent age and household generation constraints could drift.
90+
91+
### Deprecated
92+
93+
- Direct usage of old docs/flags that referenced `extend`, `export`, `inspect`, `report`,
94+
or global `--json` usage patterns.
95+
96+
### Removed
97+
98+
- Legacy `extend` command operational path from the user-facing workflow.
99+
- Root/global `--json` flag exposure from CLI surface.
100+
- `estimate` exposure in active CLI command list (temporarily hidden/disabled while parity work continues).
101+
- Legacy name-config/correlation contract pieces from spec/build paths where replaced by newer semantics.
102+
103+
### Breaking Changes
104+
105+
- Pipeline shape changed: if your automation scripts called `extend`, they must be migrated.
106+
- JSON mode usage changed: configure `cli.mode=agent` for machine-oriented output behavior.
107+
- Scenario ownership changed: household and agent-focus semantics are now scenario-owned.
108+
- Some old help/documented flags are no longer valid and must be updated to current command forms.
109+
- Legacy study scripts that assume direct `--study-db` command patterns should migrate to `--study` and study-folder auto-detection.
110+
111+
### Migration Guide (`0.3.x -> 0.4.0`)
112+
113+
1. Set/update agent mode in automation:
114+
- `extropy config set cli.mode agent`
115+
2. Move to scenario-first pipeline:
116+
- old: `spec -> extend -> sample -> network -> scenario -> simulate`
117+
- new: `spec -> scenario -> persona -> sample -> network -> simulate`
118+
3. Ensure scenario artifacts are versioned and colocated under:
119+
- `scenario/<name>/scenario.vN.yaml`
120+
- `scenario/<name>/persona.vN.yaml`
121+
4. Update run scripts to use `results`/`query` for post-run extraction.
122+
5. If you used estimate in CI/automation, remove hard dependencies until command parity is restored.
123+
124+
### Operational Notes
125+
126+
- This release increases realism and safety guards, but can increase prompt/context volume in high-fidelity,
127+
multi-timestep studies. Use smaller dry runs before full production scale.
128+
- For evolving scenarios, timeline-aware stopping and epoch re-reasoning materially change long-run dynamics.
129+
Re-baseline historical comparisons when upgrading from `0.3.x`.
130+
131+
---
132+
133+
## [0.3.0] - 2026-02-16
134+
135+
Baseline for the pre-`0.4.0` command/runtime generation used by existing studies.
136+

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ Extropy creates synthetic populations grounded in real-world distributions, conn
3838
```bash
3939
pip install extropy-run
4040
export OPENAI_API_KEY=sk-...
41-
# or: ANTHROPIC_API_KEY=... / AZURE_OPENAI_API_KEY=...
41+
# or: ANTHROPIC_API_KEY=... / AZURE_API_KEY=... + AZURE_ENDPOINT=...
4242
```
4343

4444
Requires Python 3.11+. [uv](https://github.com/astral-sh/uv) recommended.

‎docs/releases/v0.4.0.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# Extropy v0.4.0 Release Notes
2+
3+
Release date: 2026-02-24
4+
5+
This document is the full release narrative for `v0.4.0`. It is intentionally
6+
more detailed than the high-level changelog entry and is designed for operators,
7+
maintainers, and applied-research users upgrading existing studies.
8+
9+
## Executive Overview
10+
11+
`v0.4.0` is the first release where the platform behavior is strongly aligned with
12+
the current study architecture:
13+
14+
- scenario-first pipeline ownership,
15+
- explicit quality gates across sampling and networking,
16+
- timeline-safe simulation semantics for evolving scenarios,
17+
- stricter automation contracts for agentic harnesses.
18+
19+
The release includes broad runtime and tooling hardening from spec generation
20+
through final simulation analysis, with emphasis on realism, determinism, and
21+
operational clarity.
22+
23+
## Why This Release Matters
24+
25+
In `v0.3.0` and earlier, there were still mixed-era command and data contracts.
26+
Those contracts made it easier for automation to drift into stale command patterns
27+
or for long evolving scenarios to end too early due to static convergence heuristics.
28+
29+
`v0.4.0` addresses these structural issues by:
30+
31+
1. simplifying the command path to one canonical pipeline,
32+
2. giving scenario stage ownership over scenario semantics (including household focus),
33+
3. making simulation logic explicit about evolving timelines and new-information epochs,
34+
4. improving data quality gates and topological checks before expensive simulation runs.
35+
36+
## Major Improvements by Area
37+
38+
### 1) CLI and Pipeline Architecture
39+
40+
The command flow is now explicitly:
41+
42+
`extropy spec -> extropy scenario -> extropy persona -> extropy sample -> extropy network -> extropy simulate -> extropy results`
43+
44+
What changed:
45+
46+
- scenario extension generation is integrated in `extropy scenario` (instead of split command chains),
47+
- output/inspection flow is centered on `results` and `query`,
48+
- command docs and operator docs are aligned with implemented flags and behaviors.
49+
50+
Operational impact:
51+
52+
- less command ambiguity,
53+
- fewer stale script paths,
54+
- clearer ownership of population vs scenario semantics.
55+
56+
### 2) Simulation Runtime Realism and Evolving Timelines
57+
58+
`v0.4.0` brings structural changes to evolving scenario handling:
59+
60+
- timeline-aware stopping behavior:
61+
- convergence/quiescence auto-stop is no longer blindly applied when future timeline events remain,
62+
- explicit override available via scenario config and runtime flag semantics.
63+
- provenance/epoch-aware re-reasoning:
64+
- new information can trigger re-reasoning in a principled way,
65+
- supports committed-agent reconsideration patterns without content keyword heuristics.
66+
- conversation interleaving:
67+
- conversations can be interleaved during timestep reasoning loops,
68+
- avoids unrealistic "all talk only after all reasoning" dynamics.
69+
70+
Operational impact:
71+
72+
- improved temporal realism for multi-event scenarios,
73+
- reduced premature stop risk in long-horizon studies,
74+
- better alignment between information arrival and agent updates.
75+
76+
### 3) Sampling, Household Coherence, and Scenario Ownership
77+
78+
Sampling and household pathways were hardened:
79+
80+
- stronger lifecycle normalization and household coherence behaviors,
81+
- exact count guarantees improved in sampling loops,
82+
- better partner/dependent naming and member consistency handling.
83+
84+
Also, household semantics are now clearly scenario-owned where they affect downstream
85+
simulation behavior. This prevents base-population artifacts from leaking scenario-specific
86+
assumptions.
87+
88+
Operational impact:
89+
90+
- higher-quality sample datasets,
91+
- fewer contradictory household/persona states before network and sim stages,
92+
- clearer study reproducibility.
93+
94+
### 4) Network Generation and Topology Gating
95+
96+
Network stage received quality and determinism upgrades:
97+
98+
- generated network config defaults are enabled by default for meaningful topology,
99+
- deterministic structural role handling improved,
100+
- strict gate behavior hardened for practical acceptance criteria,
101+
- resource and worker auto-tuning improved for large studies.
102+
103+
Operational impact:
104+
105+
- fewer low-information network outputs,
106+
- better reproducibility across reruns,
107+
- clearer gate outcomes before simulation spend.
108+
109+
### 5) Provider Runtime Reliability and Long-Call Stability
110+
111+
Provider and runtime call paths were hardened:
112+
113+
- long-response stability improvements (including streaming-oriented fixes),
114+
- async client reuse and event-loop-close handling fixes,
115+
- rate/queue and token accounting reliability improvements.
116+
117+
Operational impact:
118+
119+
- lower failure probability during high-fidelity or long-duration runs,
120+
- better run stability under high throughput settings.
121+
122+
### 6) THINK/SAY and Reasoning Trace Fidelity
123+
124+
The simulation now better tracks and persists internal/external divergence:
125+
126+
- `THINK` vs `SAY` pathways are persisted and classifiable,
127+
- macro context and intent accountability are strengthened in prompt flow,
128+
- conversation turn behavior is more explicit by fidelity tier.
129+
130+
Operational impact:
131+
132+
- stronger micro-realism in agent expression and social signaling,
133+
- better post-run diagnostics for behavior interpretation.
134+
135+
## Breaking Changes and Required Migration Work
136+
137+
The following are breaking or operationally significant:
138+
139+
1. `extend` workflow removed from active user path.
140+
2. global/root `--json` usage removed from CLI surface; use `cli.mode=agent`.
141+
3. estimate command is hidden/disabled pending parity work; do not depend on it in release automation.
142+
4. scenario/household semantics ownership shifted to scenario artifacts.
143+
5. scripts using older `--study-db` assumptions should migrate to study-folder + `--study` conventions.
144+
145+
### Migration Checklist
146+
147+
1. Set automation mode:
148+
- `extropy config set cli.mode agent`
149+
2. Update pipeline scripts to canonical flow:
150+
- `spec -> scenario -> persona -> sample -> network -> simulate -> results`
151+
3. Verify scenario and persona file path assumptions:
152+
- `scenario/<name>/scenario.vN.yaml`
153+
- `scenario/<name>/persona.vN.yaml`
154+
4. Remove hard dependencies on estimate in CI paths until re-enabled.
155+
5. Re-baseline long evolving scenario comparisons because stopping/re-reasoning semantics changed.
156+
157+
## Known Operational Guidance for v0.4.0
158+
159+
- For expensive studies, run gated dry passes first (sample/network validation) before full sim.
160+
- Use one small simulation smoke pass before large multi-timestep runs.
161+
- Keep run metadata and scenario versions with seed references for comparability.
162+
- Prefer execution through an agentic harness for deterministic triage and replay.
163+
164+
## Versioning and Packaging
165+
166+
- Package version: `0.4.0`
167+
- Version source: `extropy/__init__.py`
168+
- Publish workflow: GitHub release-triggered PyPI publish flow remains unchanged.
169+
170+
## Suggested GitHub Release Body (Copy/Paste)
171+
172+
Title:
173+
174+
`v0.4.0 - Scenario-first pipeline hardening, timeline-safe simulation, and runtime reliability`
175+
176+
Body:
177+
178+
`v0.4.0` is a major architecture and operations release. It finalizes the scenario-first command path, hardens sampling/network quality gates, and upgrades simulation behavior for evolving timelines with timeline-aware stopping, epoch-based re-reasoning, and improved conversation scheduling.
179+
180+
This release also includes broad command/documentation alignment, provider/runtime stability improvements, and stronger reasoning trace fidelity (`THINK` vs `SAY` persistence and accountability context).
181+
182+
Breaking changes include removal of legacy `extend` workflow paths from active operation, removal of root `--json` command usage patterns in favor of `cli.mode=agent`, and temporary hiding/disablement of `estimate` until parity work is complete.
183+
184+
See `CHANGELOG.md` for full detail and migration checklist.
185+

‎extropy/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
"""Extropy: Simulate how populations respond to scenarios."""
22

3-
__version__ = "0.3.0"
3+
__version__ = "0.4.0"

0 commit comments

Comments
 (0)