Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 16 additions & 3 deletions Biofirm_Generative_Model.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,15 +22,23 @@ symmetric `observation_bins` count (an odd number >= 3); the default of 3
preserves the below/at/above observation model, while larger odd counts (e.g. 5)
discretize the state around the target more finely.

Variable and relationship mappings are canonicalized by name at construction,
including dependency accumulation and random-draw assignment. Hash-equivalent
configurations replay in that order; preserve original artifacts and runtime
provenance for earlier insertion-order-dependent runs.

## Active inference

The active-inference controller discretizes each variable into observation
states around the target using the variable's configured `observation_bins`. It
constructs the PyMDP `A`, `B`, `C`, and `D` matrices with JAX-compatible arrays,
uses an empirical prior, performs state inference followed by policy inference,
and records the selected action. The action space is the three-step
decrease/hold/increase contract. Deterministic action selection is the default.
Stochastic selection requires a configured seed and uses a JAX PRNG key.
and records the effective control action. The action space remains the three-step
decrease/hold/increase contract. Action IDs are `0` for control below `-1e-12`,
`1` within `[-1e-12, 1e-12]`, and `2` above `1e-12`. Custom and generated decisions
must satisfy the same finite, bounded control/action rule before a transition.
Deterministic action selection is the default. Stochastic selection requires a
configured seed and uses a JAX PRNG key.

The generative-model structure is specified in Generalized Notation Notation at
[`models/biofirm_ecosystem_variable.gnn.md`](models/biofirm_ecosystem_variable.gnn.md);
Expand Down Expand Up @@ -66,3 +74,8 @@ configuration snapshot and SHA-256 hash, controller name, package version, seed,
summary, and immutable transition records. Consumers must validate the complete
document before analysis or visualization; missing, extra, non-finite, or
tampered fields are errors.
Validation also checks initial values and zero initial controls, bounds noise by
three configured standard deviations, reconstructs clipped next-state values and
recomputes posterior entropy from stored beliefs. Rejected historical documents
remain evidence and must not be rewritten to pass these checks; keys and schema
version remain unchanged.
14 changes: 9 additions & 5 deletions CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,12 @@ When no `--config` is supplied, the packaged default is used
non-finite numbers, invalid ranges, duplicate or alias-colliding variable
names, dependency cycles, and incomplete action vectors.

Variable, relationship-target and dependency mappings are frozen in canonical
name order at construction. Hash-equivalent configurations therefore assign
random draws and accumulate relationship effects in the same order. This changes
replay semantics for earlier insertion-order-dependent runs: retain their original
artifacts and package-version provenance rather than regenerating evidence.

## Top-level keys

| Key | Type | Required | Default | Meaning |
Expand Down Expand Up @@ -69,6 +75,8 @@ acyclic.
The active-inference controller builds the PyMDP `A`, `B`, `C`, and `D`
matrices with JAX-compatible arrays using each variable's `observation_bins`.
The action space is the fixed three-step decrease/hold/increase contract.
Action IDs describe effective control: `0` below `-1e-12`, `1` within
`[-1e-12, 1e-12]`, and `2` above `1e-12`, including zero control strength.

## Output definition

Expand All @@ -94,11 +102,7 @@ The action space is the fixed three-step decrease/hold/increase contract.
"unit": "index"
}
},
"relationships": {
"biodiversity": {
"dependencies": { "water_quality": 0.1 }
}
},
"relationships": {},
"controller": {
"name": "active-inference",
"stochastic": false
Expand Down
19 changes: 14 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,11 @@ controller identity, and package version. Invalid configuration, unavailable
optional dependencies, malformed provider responses, and failed controller
calls produce errors; they do not create empty success artifacts.

`parse-description` keeps signed decimal and leading-decimal ranges within their
original sentences. Extracted values retain units and original evidence
offsets; nearest-variable attribution and near-equidistant ambiguity reporting
are unchanged. A range cannot borrow a variable alias from another sentence.

`scenarios` runs the same seeds across multiple validated ecosystem
configurations and reports per-scenario summaries plus a final-uncertainty
estimate, so scenario variants can be compared without asserting calibrated
Expand All @@ -78,11 +83,15 @@ Live research writes a JSON/Markdown pair for each region/persona plus a
manifest containing integrity hashes. Every artifact records the request
hash, prompt version, source hash, a provider-cost estimate, a human review
state, and a set of structured findings extracted verbatim from the provider
response (with hedge-aware confidence). Resume is allowed only when both files,
their hashes, the prompt version/hash, and the source hash agree. Structural
validation establishes artifact integrity; it never certifies the factual
quality of citations or research claims. Research execution is split into
independently rerunnable acquire/prepare/execute/parse/render stages.
response (with hedge-aware confidence). Each complete pair is hashed and
checkpointed to the manifest before another provider job starts. A later
provider or rendering failure leaves committed pairs resumable; an incomplete
pair is not a completed manifest entry. Resume requires both files, their
hashes, the prompt version/hash, and the source hash to agree. Manifest costs
estimate committed artifact entries, not billed provider usage. Structural
validation establishes artifact integrity, never factual quality of citations
or research claims. Execution remains split into independently rerunnable
acquire/prepare/execute/parse/render stages.

## Configuration

Expand Down
19 changes: 19 additions & 0 deletions TODO.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,25 @@ workflows, P2 documentation and repository coherence, P3 experimental
scientific and product expansion. Every item lands with tests, documentation,
and an explicit acceptance check before it is marked complete.

## 2026-11-13 scoped qualification

The independent `tests/test_research.py` and `tests/test_text_business.py`
modules passed all 37 cases without loading the PyMDP backend. This qualifies
the BF-C per-pair research checkpoint and BF-D decimal-range repairs, not live
provider evidence or a native simulation gate. Their current consumer guidance
is updated. The BF-F single-variable configuration example no longer references
undeclared `water_quality`; the validator's rejection contract is unchanged.

At that qualification boundary, the complete four-file acceptance was blocked:
the prepared Python 3.12 environment had PyMDP 1.0.4 rather than 1.0.5, so BF-A,
BF-B and BF-E remained unqualified. On 2026-11-16, the unchanged frozen lock was
successfully provisioned with PyMDP 1.0.5 in an isolated integration environment.
Those originally authored software repairs are now selected with their
regressions and behavior documentation for native acceptance. This records source
selection and a resolved runtime prerequisite, not a passing gate or scientific
acceptance. Historical measurements, owner decisions and scientific prerequisites
are unchanged.

## Completed/Closed

Implemented in source, tests, and CI. Preserved here for auditability; do not
Expand Down
10 changes: 10 additions & 0 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,10 @@ environment.
All commands validate the same schema before running, so
`biofirm validate --config path.json` is the fastest way to check a file.

The reference's single-variable example uses `"relationships": {}`. A
dependency must name another declared variable; validation rejects undeclared
sources.

## What validation rejects

Unknown fields, non-finite numbers, invalid ranges, duplicate or
Expand Down Expand Up @@ -46,6 +50,9 @@ never commit a key.
- The canonical JSON serialization of the validated configuration is hashed
(SHA-256) and snapshotted into every simulation artifact, so a run can be
audited against the exact configuration that produced it.
- Variable, relationship-target and dependency maps are frozen in canonical name
order, so hash-equivalent configurations use the same random-draw and summation
order. Preserve older insertion-order-dependent artifacts and provenance.
- `output.directory` (default `artifacts`) is the directory used when a command
writes by default, and `output.write_by_default` controls whether
`simulate`/`sweep` write without an explicit `--output`.
Expand All @@ -58,6 +65,9 @@ or `business`. The active-inference controller builds PyMDP `A`, `B`, `C`, and
`observation_bins`; the action space is the fixed three-step
decrease/hold/increase contract. See [`../CONFIGURATION.md`](../CONFIGURATION.md)
for the parameter table.
Action IDs describe effective signed control, including zero and near-zero
strengths, using the `1e-12` threshold in the reference. Custom decisions must
obey the same finite, bounded control/action contract before simulation succeeds.

## Related

Expand Down
67 changes: 33 additions & 34 deletions docs/gate.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,16 +25,16 @@ document.
| `sync` | 0.0s | 0.0s | Lock the environment for the selected interpreter. |
| `deps` | 0.0s | 0.0s | Verify uv.lock matches the manifests. |
| `lint` | 1.0s | 0.1s | ruff check and ruff format --check on src tests tools. |
| `types` | 18.0s | 0.3s | Strict mypy on src/biofirm. |
| `test` | 74.0s | 24.6s | pytest with the 90% coverage floor (the full suite). |
| `test-fast` | 27.0s | 18.4s | pytest without coverage and without tests/test_gnn.py. |
| `links` | 3.0s | 1.0s | tools/verify_repository.py: relative links, source data, notebooks, credential patterns, required documents. |
| `types` | 18.0s | 0.4s | Strict mypy on src/biofirm. |
| `test` | 74.0s | 29.4s | pytest with the 90% coverage floor (the full suite). |
| `test-fast` | 27.0s | 14.8s | pytest without coverage and without tests/test_gnn.py. |
| `links` | 3.0s | 0.3s | tools/verify_repository.py: relative links, source data, notebooks, credential patterns, required documents. |
| `docs` | 1.0s | 0.4s | biofirm validate and biofirm validate-data. |
| `bandit` | 2.0s | 1.0s | bandit on src and tools. |
| `build` | 28.0s | 10.1s | Build sdist and wheel into dist/. |
| `install` | 32.0s | 22.5s | Install dist/ into a clean venv and exercise the CLI outside the checkout, from the locked requirements. |
| `secret` | 54.0s | 23.5s | gitleaks scan with a synthetic negative control. |
| `gnn` | 5.0s | 7.8s | Pinned GNN conformance: the shared gnn.importers reader from the pinned revision, then tests/test_gnn.py. |
| `bandit` | 2.0s | 0.4s | bandit on src and tools. |
| `build` | 28.0s | 3.3s | Build sdist and wheel into dist/. |
| `install` | 32.0s | 17.7s | Install dist/ into a clean venv and exercise the CLI outside the checkout, from the locked requirements. |
| `secret` | 54.0s | 9.3s | gitleaks scan with a synthetic negative control. |
| `gnn` | 5.0s | 0.9s | Pinned GNN conformance: the shared gnn.importers reader from the pinned revision, then tests/test_gnn.py. |

`gate` and `all` are meta arms and are not timed here: `gate` checks this
document and `all` runs the other arms in order. `test-fast` had no CI arm
Expand All @@ -48,16 +48,16 @@ once per command.

## Measured facts

- Full suite (`test`): **115 passed** with
**90.58% coverage** against the
- Full suite (`test`): **160 passed** with
**90.91% coverage** against the
90% floor.
- Fast arm (`test-fast`): **102 passed**.
- Fast arm (`test-fast`): **145 passed**.
It runs the same suite without coverage and without `tests/test_gnn.py`,
which the `gnn` arm owns.
- GNN conformance (`gnn`): **15 passed**.
The full suite reports 2 skips from
`tests/test_gnn.py`: its pinned-parser checks need the export the `gnn` arm
writes, so they skip there and run here.
The full suite reports 0 skips from
`tests/test_gnn.py`. Its pinned-parser checks run when a prepared export is
available, otherwise they skip; the separate `gnn` arm requires that export.

The preserved pre-gate baseline reported
**119 passed** at
Expand All @@ -73,9 +73,9 @@ CI compares them.
| --- | --- | --- |
| Host | `Darwin/arm64` | `Darwin/arm64` |
| Python | `3.12.16` | `3.12.16` |
| uv | `0.13.7` | `0.13.7` |
| `uv.lock` SHA-256 | not recorded | `ba33e645ea9521dbd6708dc830afabe681f57a6c7f4a711f3a6e956295049aaa` |
| Recorded | `2026-11-12` | `2026-11-12T09:55:02-0800` |
| uv | `0.13.7` | `0.13.8` |
| `uv.lock` SHA-256 | not recorded | `e6d9bd0a85a6ba11b554b2f73032dd0ba58ec37e11e9f7a0c36a6f03b7ca6fff` |
| Recorded | `2026-11-12` | `2026-11-16T13:26:10-0800` |

## Receipt

Expand All @@ -100,26 +100,25 @@ CI compares them.
},
{
"arm": "types",
"seconds": 0.3,
"seconds": 0.4,
"status": "passed"
},
{
"arm": "test",
"coverage_percent": 90.58,
"seconds": 24.6,
"coverage_percent": 90.91,
"seconds": 29.4,
"status": "passed",
"tests_passed": 115,
"tests_skipped": 2
"tests_passed": 160
},
{
"arm": "test-fast",
"seconds": 18.4,
"seconds": 14.8,
"status": "passed",
"tests_passed": 102
"tests_passed": 145
},
{
"arm": "links",
"seconds": 1.0,
"seconds": 0.3,
"status": "passed"
},
{
Expand All @@ -129,27 +128,27 @@ CI compares them.
},
{
"arm": "bandit",
"seconds": 1.0,
"seconds": 0.4,
"status": "passed"
},
{
"arm": "build",
"seconds": 10.1,
"seconds": 3.3,
"status": "passed"
},
{
"arm": "install",
"seconds": 22.5,
"seconds": 17.7,
"status": "passed"
},
{
"arm": "secret",
"seconds": 23.5,
"seconds": 9.3,
"status": "passed"
},
{
"arm": "gnn",
"seconds": 7.8,
"seconds": 0.9,
"status": "passed",
"tests_passed": 15
}
Expand Down Expand Up @@ -242,13 +241,13 @@ CI compares them.
},
"coverage_floor": 90,
"environment": {
"lock_sha256": "ba33e645ea9521dbd6708dc830afabe681f57a6c7f4a711f3a6e956295049aaa",
"lock_sha256": "e6d9bd0a85a6ba11b554b2f73032dd0ba58ec37e11e9f7a0c36a6f03b7ca6fff",
"machine": "arm64",
"python": "3.12.16",
"system": "Darwin",
"uv": "0.13.7"
"uv": "0.13.8"
},
"recorded": "2026-11-12T09:55:02-0800",
"recorded": "2026-11-16T13:26:10-0800",
"schema": "biofirm-gate-receipt/v1"
}
```
Expand Down
19 changes: 15 additions & 4 deletions docs/io.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,13 @@ checked against the configuration's variable set, `metrics` is exactly
`posterior_entropy`, and every value must be finite. Read or write this format
through `SimulationResult`/`validate_result_document` rather than by hand.

Validation checks initial values and zero initial controls, bounds transition
noise by three configured standard deviations, reconstructs clipped next-state
values, and recomputes posterior entropy from recorded beliefs. Action IDs must
match effective signed control using the `1e-12` hold threshold, including zero
and near-zero strengths. Artifact keys and schema version remain unchanged.
Retain rejected historical documents as evidence; do not rewrite them to pass.

Use it as:

```bash
Expand All @@ -65,10 +72,14 @@ Each artifact records the request hash, prompt version, source hash, a
provider-cost estimate, a human review state, and structured findings extracted
verbatim from the provider response (with hedge-aware confidence).

Resume is allowed only when both files, their hashes, the prompt version and
hash, and the source hash agree. Structural validation establishes artifact
integrity; it never certifies the factual quality of citations or research
claims. Execution is split into independently rerunnable
Each complete JSON/Markdown pair is hashed and checkpointed to the manifest
before another provider job starts. A later provider or rendering failure
therefore leaves already committed pairs resumable; an incomplete pair is not a
completed manifest entry. Resume is allowed only when both files, their hashes,
the prompt version and hash, and the source hash agree. Manifest costs estimate
committed artifact entries, not billed provider usage. Structural validation
establishes artifact integrity; it never certifies factual quality of citations
or research claims. Execution remains split into independently rerunnable
acquire/prepare/execute/parse/render stages.

## Where outputs belong
Expand Down
13 changes: 10 additions & 3 deletions src/biofirm/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -210,13 +210,15 @@ class RelationshipConfig:
def __post_init__(self) -> None:
if not isinstance(self.dependencies, Mapping):
raise ConfigError("relationship dependencies must be an object")
object.__setattr__(self, "dependencies", MappingProxyType(dict(self.dependencies)))
if not isinstance(self.target, str) or not self.target.strip():
raise ConfigError("relationship targets must be non-empty strings")
for source, coefficient in self.dependencies.items():
if not isinstance(source, str) or not source.strip():
raise ConfigError("relationship dependency keys must be non-empty strings")
_finite(coefficient, f"relationships.{self.target}.dependencies.{source}")
object.__setattr__(
self, "dependencies", MappingProxyType(dict(sorted(self.dependencies.items())))
)

@classmethod
def from_dict(cls, target: str, raw: Mapping[str, Any]) -> RelationshipConfig:
Expand Down Expand Up @@ -350,9 +352,14 @@ def __post_init__(self) -> None:
raise ConfigError("configuration.variables must be an object")
if not isinstance(self.relationships, Mapping):
raise ConfigError("configuration.relationships must be an object")
object.__setattr__(self, "variables", MappingProxyType(dict(self.variables)))
object.__setattr__(self, "relationships", MappingProxyType(dict(self.relationships)))
self.validate()
# Hash-equivalent mappings must assign RNG draws and sums identically.
object.__setattr__(
self, "variables", MappingProxyType(dict(sorted(self.variables.items())))
)
object.__setattr__(
self, "relationships", MappingProxyType(dict(sorted(self.relationships.items())))
)

@classmethod
def from_dict(cls, raw: Mapping[str, Any]) -> BiofirmConfig:
Expand Down
4 changes: 2 additions & 2 deletions src/biofirm/controllers.py
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ def act(self, values: Mapping[str, float]) -> ControlDecision:
for name, variable in self.config.variables.items():
action = int(self._rng.integers(0, 3))
controls[name] = float((action - 1) * variable.control_strength)
action_ids[name] = action
action_ids[name] = _action_for_control(controls[name])
return ControlDecision(
controls=controls,
action_ids=action_ids,
Expand Down Expand Up @@ -205,7 +205,7 @@ def act(self, values: Mapping[str, float]) -> ControlDecision:
belief = np.asarray(qs[0]).reshape(-1)
vfe = float(np.asarray(info["vfe"]).reshape(-1)[0])
controls[name] = float((action - 1) * variable.control_strength)
action_ids[name] = action
action_ids[name] = _action_for_control(controls[name])
beliefs[name] = tuple(float(item) for item in belief)
vfes[name] = vfe
efes[name] = tuple(float(item) for item in np.asarray(expected).reshape(-1))
Expand Down
Loading
Loading