welsberr
/
Synaptopus
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Synaptopus/docs/FORMATS.md

7.0 KiB
Raw Blame History

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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.