335 lines
7.0 KiB
Markdown
335 lines
7.0 KiB
Markdown
# Formats
|
|
|
|
## Purpose
|
|
|
|
Synaptopus uses JSON-facing artifact types as the bridge to future browser and TypeScript tooling:
|
|
|
|
- artifact manifest
|
|
- graph schema
|
|
- execution trace
|
|
- run report
|
|
- demo snapshot
|
|
|
|
These are generated today by the internal demo exporter. The examples below reflect the current output shapes rather than speculative formats.
|
|
|
|
All exported artifacts are wrapped in a versioned envelope with this top-level shape:
|
|
|
|
- `artifact_type`
|
|
- `schema_version`
|
|
- `payload`
|
|
- `metadata`
|
|
|
|
Example:
|
|
|
|
```json
|
|
{
|
|
"artifact_type": "graph_schema",
|
|
"schema_version": "1.0",
|
|
"payload": {
|
|
"nodes": [],
|
|
"edges": []
|
|
},
|
|
"metadata": {}
|
|
}
|
|
```
|
|
|
|
## Artifact Manifest
|
|
|
|
The manifest is the directory-level index for a set of exported artifacts.
|
|
|
|
Top-level fields:
|
|
|
|
- `schema_version`
|
|
- `artifacts`
|
|
- `metadata`
|
|
|
|
Each artifact entry has:
|
|
|
|
- `artifact_type`
|
|
- `file_name`
|
|
|
|
Example:
|
|
|
|
```json
|
|
{
|
|
"schema_version": "1.0",
|
|
"artifacts": [
|
|
{ "artifact_type": "graph_schema", "file_name": "graph.json" },
|
|
{ "artifact_type": "execution_trace", "file_name": "trace.json" },
|
|
{ "artifact_type": "run_report", "file_name": "report.json" },
|
|
{ "artifact_type": "demo_snapshot", "file_name": "snapshot.json" }
|
|
],
|
|
"metadata": {
|
|
"example": "parity_pressure",
|
|
"snapshot_after_accepted": 2
|
|
}
|
|
}
|
|
```
|
|
|
|
## Graph Schema
|
|
|
|
The graph schema describes node roles and wiring. It does not encode full runtime behavior by itself.
|
|
|
|
Top-level fields:
|
|
|
|
- `nodes`
|
|
- `edges`
|
|
|
|
Each node has:
|
|
|
|
- `node_id`
|
|
- `node_type`
|
|
- `input_names`
|
|
- `output_names`
|
|
|
|
Each edge has:
|
|
|
|
- `source_node_id`
|
|
- `source_output`
|
|
- `target_node_id`
|
|
- `target_input`
|
|
|
|
Example:
|
|
|
|
```json
|
|
{
|
|
"artifact_type": "graph_schema",
|
|
"schema_version": "1.0",
|
|
"payload": {
|
|
"nodes": [
|
|
{
|
|
"node_id": "generator",
|
|
"node_type": "generator",
|
|
"input_names": ["state"],
|
|
"output_names": ["candidate"]
|
|
},
|
|
{
|
|
"node_id": "policy",
|
|
"node_type": "policy",
|
|
"input_names": ["state", "candidate", "critique", "category"],
|
|
"output_names": ["decision", "accepted"]
|
|
}
|
|
],
|
|
"edges": [
|
|
{
|
|
"source_node_id": "generator",
|
|
"source_output": "candidate",
|
|
"target_node_id": "critic",
|
|
"target_input": "candidate"
|
|
}
|
|
]
|
|
},
|
|
"metadata": {}
|
|
}
|
|
```
|
|
|
|
## Execution Trace
|
|
|
|
The execution trace captures the real runtime behavior of a system under the generic accept/reject loop.
|
|
|
|
Top-level fields:
|
|
|
|
- `accepted`
|
|
- `attempts`
|
|
- `final_state`
|
|
- `total_seconds`
|
|
|
|
Each step trace contains:
|
|
|
|
- `previous_state`
|
|
- `next_state`
|
|
- `candidate`
|
|
- `accepted`
|
|
- `elapsed_seconds`
|
|
- `metadata`
|
|
|
|
The metadata payload is intentionally architecture- and example-specific, but it must still be JSON-safe. For the XOR novelty demo it contains:
|
|
|
|
- `critique`
|
|
- `category`
|
|
- `decision`
|
|
|
|
Example excerpt:
|
|
|
|
```json
|
|
{
|
|
"artifact_type": "execution_trace",
|
|
"schema_version": "1.0",
|
|
"payload": {
|
|
"accepted": [
|
|
{
|
|
"candidate": [0, 1],
|
|
"accepted": true,
|
|
"metadata": {
|
|
"critique": {
|
|
"outputs": [0.9850980332426884],
|
|
"loss": 0.0
|
|
},
|
|
"category": {
|
|
"winner": 0,
|
|
"matched": true,
|
|
"new_category": false,
|
|
"delta_vigilance": false
|
|
},
|
|
"decision": {
|
|
"accepted": true,
|
|
"label": "accept"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"metadata": {}
|
|
}
|
|
```
|
|
|
|
## Generic And Example-Specific Trace Fields
|
|
|
|
The execution trace has two layers:
|
|
|
|
- generic runtime fields, which should remain stable across examples
|
|
- `metadata`, which may vary by example or architecture family
|
|
|
|
Generic fields:
|
|
|
|
- `previous_state`
|
|
- `next_state`
|
|
- `candidate`
|
|
- `accepted`
|
|
- `elapsed_seconds`
|
|
|
|
Example-specific metadata should stay JSON-safe and should be interpreted by consumers only when they know the example or system family.
|
|
|
|
## Run Report
|
|
|
|
The run report is a compact summary artifact for comparison, dashboarding, and experiment logging.
|
|
|
|
Top-level fields inside `payload`:
|
|
|
|
- `parameters`
|
|
- `accepted_count`
|
|
- `attempt_count`
|
|
- `total_seconds`
|
|
- `sequence_analysis`
|
|
- `average_attempts_per_accept`
|
|
|
|
Example:
|
|
|
|
```json
|
|
{
|
|
"artifact_type": "run_report",
|
|
"schema_version": "1.0",
|
|
"payload": {
|
|
"parameters": {
|
|
"example": "xor_novelty",
|
|
"accepted_count": 2,
|
|
"max_attempts_per_accept": 4
|
|
},
|
|
"accepted_count": 2,
|
|
"attempt_count": 3,
|
|
"total_seconds": 0.00019715959206223488,
|
|
"sequence_analysis": {
|
|
"item_count": 2,
|
|
"alphabet_size": 4,
|
|
"unigram_entropy_bits": 1.0,
|
|
"conditional_entropy_bits": 0.0,
|
|
"normalized_entropy": 0.5,
|
|
"predictability": 1.0,
|
|
"redundancy": 0.5
|
|
}
|
|
},
|
|
"average_attempts_per_accept": 1.5
|
|
},
|
|
"metadata": {}
|
|
}
|
|
```
|
|
|
|
The `sequence_analysis` object is optional. When present, it currently contains:
|
|
|
|
- `item_count`
|
|
- `alphabet_size`
|
|
- `unigram_entropy_bits`
|
|
- `conditional_entropy_bits`
|
|
- `normalized_entropy`
|
|
- `predictability`
|
|
- `redundancy`
|
|
|
|
## Demo Snapshot
|
|
|
|
The demo snapshot artifact is the first checkpoint/resume format in Synaptopus. It is currently scoped to the internal demos rather than arbitrary user-defined systems.
|
|
|
|
Top-level fields inside `payload`:
|
|
|
|
- `demo_name`
|
|
- `system`
|
|
- `record`
|
|
- `parameters`
|
|
|
|
The `system` object stores the mutable model internals needed to resume execution, such as ART1 categories and backpropagation weights. The `record` object stores the accumulated execution history up to the checkpoint.
|
|
|
|
Example:
|
|
|
|
```json
|
|
{
|
|
"artifact_type": "demo_snapshot",
|
|
"schema_version": "1.0",
|
|
"payload": {
|
|
"demo_name": "parity_pressure",
|
|
"system": {
|
|
"critic_network": {},
|
|
"categorizer_network": {},
|
|
"acceptance_threshold": 0.8
|
|
},
|
|
"record": {
|
|
"accepted": [],
|
|
"attempts": [],
|
|
"final_state": {
|
|
"accepted": [[0, 0, 1], [1, 0, 0]],
|
|
"attempts": 5
|
|
},
|
|
"total_seconds": 0.0005
|
|
},
|
|
"parameters": {
|
|
"accepted_count": 2,
|
|
"max_attempts_per_accept": 12
|
|
}
|
|
},
|
|
"metadata": {
|
|
"demo_name": "parity_pressure"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Versioning
|
|
|
|
The current artifact schema version is:
|
|
|
|
- `1.0`
|
|
|
|
Any future breaking change to the envelope, manifest, or payload structures should increment the schema version rather than silently changing field meaning.
|
|
|
|
## Format Constraints
|
|
|
|
These constraints should remain stable:
|
|
|
|
- artifacts must be JSON-safe without Python-specific types
|
|
- exported files should be versioned via envelopes
|
|
- artifact sets should include a manifest
|
|
- tuples must serialize as arrays
|
|
- dataclass-like records must serialize as plain objects
|
|
- graph schemas must remain declarative
|
|
- traces must reflect actual runtime attempts and acceptances
|
|
- reports should stay compact and comparison-friendly
|
|
|
|
## Intended TypeScript Mapping
|
|
|
|
The natural future TypeScript split is:
|
|
|
|
- manifest interfaces
|
|
- artifact envelope interfaces
|
|
- graph schema interfaces
|
|
- trace interfaces
|
|
- report interfaces
|
|
|
|
Those should be derived directly from the current artifact contracts rather than reinterpreted independently in the frontend.
|