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
13 changes: 8 additions & 5 deletions .github/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,14 @@ The workflow installs `uv.lock`, then calls the arms of
contains only Python 3.11 and runs `--arm test-full`. The `gnn-conformance` job
(display name `gnn conformance (pinned)`) runs `--arm all`
on Python 3.12 with `GNN_RUNTIME_PYTHON` set to the separate runtime provisioned from `specs/gnn-pin.json`.
There is no separate `gate` job. Pinned conformance always runs in the `gnn`
arm, where the shared `python -m gnn.importers check --repo .` reads the pin and
the pointer, and `scripts/validate_gnn_spec.py --verify-tag-remote` checks the
pinned v5.1.0 tag resolves to commit `75c834bd` and verifies the parser digests
before parsing; missing runtime dependencies must fail, never skip. PDF rendering remains
There is no separate `gate` job. The `gnn` arm checks exporter drift, then
`scripts/validate_gnn_spec.py --verify-tag-remote` owns deep conformance and the
shared pin/pointer/workflow/job check through qualified external workers.
Require independently reviewed `GNN_BOOTSTRAP` and `GNN_SOURCE_MANIFEST` job
inputs and complete content/module/installed-origin admission through exit.
The workflow downloads both from the immutable producer resource revision and
verifies their source-owned SHA-256 digests before use; never invent download
URLs or weaken admission. Missing prerequisites fail, never skip. PDF rendering remains
an explicit local `--arm render` selection. The workflow uses pinned
`astral-sh/setup-uv` directly, not the Institute composite; see
[`../docs/gate.md`](../docs/gate.md) for the exact action and command map.
Expand Down
24 changes: 12 additions & 12 deletions .github/GNN.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,21 +7,21 @@
(`75c834bd8519dc7b5adc4d24f16bf393cfd1ecdf`) and records SHA-256 digests for
the five parser files under `src/gnn/`.

The job installs that commit into a separate Python 3.12 runtime, then invokes
the canonical release gate with `--arm all` and `GNN_RUNTIME_PYTHON` set to that runtime. Its `gnn`
arm runs the estate's shared reader,
`python -m gnn.importers check --repo . --require-pointer --workflow
.github/workflows/ci.yml --job gnn-conformance`, from that runtime, then the
offline drift check and the deep pinned-parser conformance check. The reader
owns pin discovery and validation, and reports a pointer that fails to name the
pin file, the pinned revision, the workflow or the job. A missing runtime
fails instead of skipping conformance. See
The job selects the canonical release gate with `--arm all` and a separate
`GNN_RUNTIME_PYTHON`. It must also receive independently reviewed
`GNN_BOOTSTRAP` and `GNN_SOURCE_MANIFEST` resources before hosted acceptance.
Within the `gnn` arm, exporter drift is checked first; the project validator
then owns deep conformance and the producer's syntax/pointer/workflow/job
check in separate isolated qualified lifetimes. The shared producer remains
authoritative for pin discovery and validation. Missing resources, runtime,
installed provenance, or exit revalidation fail rather than skip. See
[`docs/gate.md`](../docs/gate.md) for the complete job and arm map, and
[`docs/gnn.md`](../docs/gnn.md) for standalone validation commands.

The validator checks that the resolved `gnn.__version__` matches the pin tag,
verifies the installed parser file digests, parses `specs/gridworld_3x3.gnn.md`
with the pinned `MarkdownGNNParser`, and compares the declared parameters and the `A`,
Independent full-package content and actual module ownership are admitted
before target GNN execution and revalidated at verdict exit. The validator
also checks version and recorded parser hashes, parses the committed document
with the pinned `MarkdownGNNParser`, and compares declared parameters and `A`,
`B`, `C`, `D`, and `E` matrices against the runtime model built by
`blockference.gnn`; it also requires the pinned semantic validator, the
B-orientation check, and the consistency checker to report no errors or
Expand Down
3 changes: 3 additions & 0 deletions .github/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,9 @@ arms of the canonical gate in [`scripts/release_check.py`](../scripts/release_ch
* the Python 3.12 `gnn-conformance` job (display name
`gnn conformance (pinned)`) runs `--arm all` with `GNN_RUNTIME_PYTHON` set to a
separate pinned runtime provisioned from `specs/gnn-pin.json`.
Independently reviewed `GNN_BOOTSTRAP` and `GNN_SOURCE_MANIFEST` inputs must
also be delivered before hosted acceptance; source-only local proof does
not establish installed provenance or provide those hosted artifacts.

The arms cover Ruff linting, repository-wide Markdown link/anchor validation,
mypy, the test suite, notebook hygiene and execution, real pipeline and CLI
Expand Down
12 changes: 7 additions & 5 deletions .github/workflows/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,13 @@ release gate in two jobs:

The second job retains the display name `gnn conformance (pinned)` and installs
the revision in [`../../specs/gnn-pin.json`](../../specs/gnn-pin.json) into a
separate runtime; its `gnn` arm then calls the shared
`python -m gnn.importers check --repo .` from that runtime. The full suite runs on both Python versions; all other release
arms run with conformance on Python 3.12. Missing pinned-runtime validation
fails the gate. There is no separate `gate` job, and PDF rendering remains an
explicit local arm.
separate runtime. Its `gnn` arm invokes the project validator for guarded deep
conformance and the shared importer check. Independently reviewed bootstrap
and full-manifest job inputs must be delivered before hosted acceptance;
no machine-local path or invented publication URL substitutes for them.
The full suite is selected on both Python versions; other release arms run
on Python 3.12. Missing prerequisites fail. There is no separate `gate` job;
PDF rendering remains an explicit local arm.

The workflow uses pinned `astral-sh/setup-uv` directly, not the Institute
composite. [`../../docs/gate.md`](../../docs/gate.md) is authoritative for the
Expand Down
29 changes: 26 additions & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -57,9 +57,10 @@ jobs:
# Validates the committed GNN specification with the parser pinned in
# specs/gnn-pin.json. The pinned revision is installed into a separate runtime
# because the GNN distribution requires numpy>=2 while this package
# resolves numpy 1.x. The gnn arm runs the shared `python -m gnn.importers
# check` from that runtime, and the validator verifies the installed parser
# file digests against the pin record before parsing.
# resolves numpy 1.x. The project validator owns both guarded conformance
# and shared importer checks. Independently reviewed immutable resources are
# downloaded and SHA-256 checked before release execution; parser-file
# digests alone are not complete source or installed-origin admission.
name: gnn conformance (pinned)
runs-on: ubuntu-latest

Expand All @@ -80,6 +81,26 @@ jobs:
- name: Install locked package and development dependencies
run: uv sync --locked --extra dev --python 3.12

- name: Prepare reviewed GNN admission resources
id: resources
run: |
set -euo pipefail
# Resource delivery revision, not the parser revision in specs/gnn-pin.json.
BASE="https://raw.githubusercontent.com/ActiveInferenceInstitute/Generalized_Notation_Notation/66d491f86895443cf588011cc6f40c37b8bae8fd/interop"
RESOURCES="$RUNNER_TEMP/gnn-resources"
mkdir -p "$RESOURCES"
curl --fail --silent --show-error --location --proto '=https' --tlsv1.2 \
"$BASE/gnn_bootstrap.py" --output "$RESOURCES/gnn_bootstrap.py"
curl --fail --silent --show-error --location --proto '=https' --tlsv1.2 \
"$BASE/v5.1.0-source-manifest.json" --output "$RESOURCES/v5.1.0-source-manifest.json"
(
cd "$RESOURCES"
echo "f638d4c01fe7de31e43d793e59bf382d0c3d1a82f365c59238334a2b40adfb37 gnn_bootstrap.py" | sha256sum --check --strict
echo "43b33c0b2b40386afa3f306fec4cc13bc1fd7c3b570fbf11d5008bad5c8e6b51 v5.1.0-source-manifest.json" | sha256sum --check --strict
)
echo "bootstrap=$RESOURCES/gnn_bootstrap.py" >> "$GITHUB_OUTPUT"
echo "manifest=$RESOURCES/v5.1.0-source-manifest.json" >> "$GITHUB_OUTPUT"

- name: Provision the pinned GNN parser runtime
id: runtime
run: |
Expand All @@ -98,4 +119,6 @@ jobs:
- name: Release arms (including Python 3.12 full tests and GNN conformance)
env:
GNN_RUNTIME_PYTHON: ${{ steps.runtime.outputs.python }}
GNN_BOOTSTRAP: ${{ steps.resources.outputs.bootstrap }}
GNN_SOURCE_MANIFEST: ${{ steps.resources.outputs.manifest }}
run: uv run python scripts/release_check.py --arm all
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@ coverage.xml

# Generated artefacts (commit on demand)
result.csv
ignored.csv
*.csv.bak
results/
output/
Expand Down
20 changes: 11 additions & 9 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,15 +24,17 @@ The grid-world model is declared in `specs/gridworld_3x3.gnn.md` (Generalized
Notation Notation) and generated from the implementation by
`blockference.gnn.render_spec`; `uv run python scripts/export_gnn_spec.py
--check` fails when the committed document drifts. The upstream parser is
pinned in `specs/gnn-pin.json` (GNN v5.1.0, commit `75c834bd8`), and
`python -m gnn.importers check --repo .` reads that pin and the `.github/GNN.md`
pointer while `scripts/validate_gnn_spec.py` parses the document with that
revision, builds the runtime model from the declared parameters, and requires the
declared matrices to match. Do not add a second pin reader: the shared reader is
upstream. Both checks need an external runtime (`GNN_ROOT` or
`GNN_RUNTIME_PYTHON`); the required `gnn-conformance` CI job provisions one from
the pin and runs `scripts/release_check.py --arm gnn`. Do not
hand-edit `specs/gridworld_3x3.gnn.md`: change the model or fixture in
pinned in `specs/gnn-pin.json` (GNN v5.1.0, commit `75c834bd8`).
`scripts/validate_gnn_spec.py` owns both deep conformance and the shared
pin/pointer/workflow/job check through `blockference/gnn_source.py`.
Require the selected separate interpreter plus independently reviewed
`GNN_BOOTSTRAP` and `GNN_SOURCE_MANIFEST` resources. Complete source/module
admission must remain active through verdict exit; metadata inspection alone
is not qualification. Never add a local pin reader or an unchecked direct
`-m gnn.importers` path. Installed provenance and source-artifact proof remain
distinct. Hosted resource delivery is a release prerequisite, not an assumed
published artifact. The required `gnn-conformance` job runs the `gnn` arm.
Do not hand-edit `specs/gridworld_3x3.gnn.md`: change the model or fixture in
`blockference/` and regenerate with `scripts/export_gnn_spec.py`. See
`docs/gnn.md`.

Expand Down
7 changes: 7 additions & 0 deletions GRTs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,3 +15,10 @@ The optional OpenAI provider is selected explicitly with `--provider openai` and
configured by the caller; there are no implicit global paths or provider instances. Offline
tests and release gates never make network requests. A provider response is research input,
not a software-integrity or scientific-validity verdict; preserve its provenance separately.

An explicit `Path` corpus means a readable regular UTF-8 file. It is admitted
before workspace preparation or optional provider construction; missing,
directory, broken-link, unreadable, and invalid-UTF-8 inputs fail without
changing request/data/report sentinels. `None` selects the built-in corpus.
Existing readable filename strings retain file behavior; other strings remain
literal text, including empty or long text. No provider fallback is inferred.
22 changes: 18 additions & 4 deletions GRTs/agents.py
Original file line number Diff line number Diff line change
Expand Up @@ -52,19 +52,31 @@ def prepare(self) -> None:
self.research_data.write_text("", encoding="utf-8")


def _read_corpus_file(path: Path) -> str:
if path.is_dir():
raise IsADirectoryError(f"corpus must be a readable UTF-8 file: {path}")
if not path.is_file():
raise FileNotFoundError(f"corpus file not found: {path}")
return path.read_text(encoding="utf-8")


class OfflineCorpusProvider:
"""Deterministic provider that answers from a local text corpus."""
"""Use readable explicit Paths, existing filename strings, or literal/default text."""

def __init__(self, corpus: str | Path | None = None) -> None:
if corpus is None:
self.corpus = (
"Active inference links observations, beliefs, actions, and expected free energy."
)
elif isinstance(corpus, Path):
self.corpus = _read_corpus_file(corpus)
else:
corpus_path = Path(corpus)
self.corpus = (
corpus_path.read_text(encoding="utf-8") if corpus_path.is_file() else str(corpus)
)
try:
is_file = corpus_path.is_file()
except (OSError, ValueError):
is_file = False
self.corpus = _read_corpus_file(corpus_path) if is_file else corpus

def complete(self, prompt: str) -> str:
"""Return stable corpus sentences selected by prompt terms."""
Expand Down Expand Up @@ -182,6 +194,8 @@ def build_provider(
if name == "offline":
return OfflineCorpusProvider(corpus)
if name == "openai":
if isinstance(corpus, Path):
_read_corpus_file(corpus)
return OpenAIProvider(model=model, timeout=timeout)
raise ValueError("provider must be 'offline' or 'openai'")

Expand Down
29 changes: 14 additions & 15 deletions GRTs/data3/README.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,18 @@
# `GRTs/data3/` — shared working corpus

Files in this folder are **the agents' communication channel**. The
LangChain agents in `GRTs/agents.py` read and write here.
These checked-in files are retained historical corpus/workspace material, not
a live LangChain persona protocol. Current runtime locations come from an
explicit `ResearchWorkspace(root)`.

| File | Read by | Written by | Purpose |
|-------------------------------|-----------------|--------------------|--------------------------------------------|
| `O_Project_description.txt` | both | human (seed) | The original task description. |
| `requests.txt` | Research Joe | Professor Karl | Outstanding research questions. |
| `research_data.txt` | Professor Karl | Research Joe | Gathered evidence / sources. |
| `report.txt` | human | Professor Karl | The final write-up. |
| File | Current role |
| --- | --- |
| `O_Project_description.txt` | Optional prompt context. |
| `requests.txt` | Human input, seeded only when missing. |
| `research_data.txt` | Research data written by `ResearchOrchestrator`. |
| `report.txt` | Report written by `ResearchOrchestrator`. |

## Conventions

* Files are plain UTF-8 text.
* The agents append/overwrite with `WriteFileTool`; treat any file as
potentially mutated by the next run.
* Keep the seed `O_Project_description.txt` checked in; treat the rest as
ephemeral artefacts (do not rely on their git history).
`OfflineCorpusProvider` is deterministic and network-free. OpenAI is an
explicit optional provider requiring external credentials. The implementation
has no Research Joe/Professor Karl agents or `WriteFileTool` calls.
Preserve the corpus, reports, and historical communication files; updating
this description does not authorize running a provider or rewriting them.
19 changes: 13 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,10 @@ uv run python scripts/release_check.py --arm all --gnn-runtime /path/to/gnn-runt
uv run blockference pipeline --config configs/smoke.yml --output-root output
```

The release gate requires a separate pinned GNN runtime; replace the example
The release gate requires a separate pinned GNN runtime and independently
reviewed `GNN_BOOTSTRAP`/`GNN_SOURCE_MANIFEST` resources; replace the example
interpreter path above with yours. [`docs/gate.md`](docs/gate.md) defines the
arms and CI mapping, and [`docs/gnn.md`](docs/gnn.md) explains runtime setup.
arms and CI mapping, and [`docs/gnn.md`](docs/gnn.md) explains admission/setup.

The CLI has three explicit commands:

Expand All @@ -44,6 +45,11 @@ summary/model/policies, an NPZ model archive, PNG visualisations, a GIF, a log,
`manifest.json`, and one aggregate `validation_report.json`. Parquet is an
optional additional format; CSV and JSON remain required. A non-empty run
directory is refused unless `--reuse` is supplied explicitly.
Models, policies, summaries, and visual histories retain `(run, agent)`
ownership; independent runs are not concatenated. Version-2 artifact layouts
and exact diagnostic/category checks are documented in
[`docs/pipeline.md`](docs/pipeline.md). Historical version-1 trees are not
silently migrated or re-certified.

For single-agent runs, `simulation.initial_state` remains the compatibility
default. For multi-agent runs (`n_agents > 1`) the simultaneous-transition
Expand Down Expand Up @@ -115,10 +121,11 @@ The grid-world generative model is declared in
the upstream parser pinned in [`specs/gnn-pin.json`](specs/gnn-pin.json)
(schema `gnn-importer-pin/v1`, GNN v5.1.0, commit
`75c834bd8519dc7b5adc4d24f16bf393cfd1ecdf`): the estate's shared reader
`gnn.importers` validates that pin and the [`.github/GNN.md`](.github/GNN.md)
pointer, and the validator reads the declared parameters back, builds the runtime
model from them, and requires the declared matrices to match exactly. See [`docs/gnn.md`](docs/gnn.md) for the commands and the
conformance contract.
owns pin/pointer validation inside a fully admitted external worker. The
validator reads declared parameters back, builds the runtime model, and
requires exact matrices and policy cardinalities. Source execution,
installed provenance, and scientific adequacy are separate boundaries.
See [`docs/gnn.md`](docs/gnn.md) for the commands and conformance contract.

GNN maintains a [downstream adoption
guide](https://github.com/ActiveInferenceInstitute/Generalized_Notation_Notation/blob/main/docs/gnn/integration/downstream_adoption.md)
Expand Down
Loading
Loading