Ordinal

A visual node-based graph editor for modeling, visualizing, and executing complex systems through hierarchical container-based ontologies.

Ordinal is a standalone Svelte 4 SPA served by Rhode's web server. You build graphs by placing nodes, drawing connections, and letting the system automatically discover semantic hierarchy using Union-Find algorithms. Graphs are saved as .ologic YAML blueprints and can be loaded, shared, validated, and executed headlessly via Ordinal-MCP.

Three Modes

Ordinal operates in three distinct modes on the same canvas. Switch modes from the toolbar — the node palette and available types change to match.

Knowledge Mode

Build AI completion pipelines. Connect document sources through AI processing nodes to file outputs. Token counting tracks LLM context size in real-time so you can stay within model limits.

Node types: input, static, ai, text_file_source, pdf_file_source, text_file_output, source, process, output

Typical pattern: text or PDF sources feed into an AI node (with a prompt template), which writes to a text file output. Chain multiple AI nodes for multi-step processing pipelines.

Automation Mode

Build agent orchestration graphs. Two sub-modes:

Agent Graph — Model multi-agent systems. Place workers, orchestrators, oracles (human-in-the-loop gates), and process nodes. Oracles represent decision points where a human must approve before execution continues.

Action Graph — CI/CD style automation. Triggers kick off sequences of bash or Python script nodes, with variables, approval gates, and artifact outputs. Good for modeling deployment pipelines, scheduled jobs, and approval workflows.

Diagramming Mode

Architecture visualization. 20+ node types cover the full range of infrastructure and system design:

server, database, api, cloud, container, queue, cache, gateway, firewall, loadbalancer, user, monitor, static, source, decision, ai, process, worker, orchestrator, oracle, default

Use this mode to document system architecture, communicate designs, or model the topology of a running system.

Ontology System

The core concept: connected components form hierarchy automatically.

The key pattern: a bridge node declared outside a container, with inputs: pointing to that container's ID, triggers promotion to the next hierarchy level. This gives you semantic boundaries without explicit wrapping.

Detection runs in two modes:

• Implicit — hierarchy is derived entirely from connection topology using Union-Find. No nesting required in the YAML.
• Explicit — YAML hierarchy is preserved as written. When you load a blueprint that declares networks: > factories: > machines:, Ordinal respects that structure rather than re-deriving it.

Both validators (frontend JS and backend Python) enforce the same ontology rules.

For the full formal specification — including the Union-Find algorithms, edge resolution rules, and complexity analysis — see ONTOLOGY.md.

The Formula

The complete ontology detection is a composition of three morphisms on the graph:

Ω(G) = W(F(M(G)))

Where M detects machines (Union-Find on node edges), F detects factories (Union-Find on machine edges), and W detects networks (Union-Find + BFS on factory edges). Each level defines a vertex set from the previous level's output, resolves edges upward, computes connected components, and filters by minimum cardinality. The result is a strict containment hierarchy — linear time, no overlap.

This formula is rooted in ordinal logic: the idea that structure emerges from connection at successive levels of abstraction. An .ologic file is a declarative graph that Ordinal's ontology algorithm transforms into a hierarchical system model. The name "O-logic" comes from the O-machine concept — a Turing machine augmented with an oracle function. In Ordinal's case, the oracle is the human operator who decides what to connect and at what level of abstraction. The algorithm discovers the hierarchy; the human provides the intent.

Blueprint Format (.ologic)

Graphs are stored as YAML blueprints with a .ologic extension. The root key is logic:, with mode: and version: set at the top level.

logic:
  mode: diagramming
  version: '2.0'
  factories:
    - id: web-stack
      machines:
        - id: frontend
          nodes:
            - id: cdn
              type: cloud
              title: CDN
              outputs: [gateway]
            - id: gateway
              type: gateway
              title: API Gateway
              outputs: [api]
            - id: api
              type: api
              title: REST API
      nodes:
        - id: db
          type: database
          title: Postgres
          inputs: [frontend]
        - id: cache
          type: cache
          title: Redis
          inputs: [frontend]

This produces a factory (web-stack) containing one machine (frontend) with three nodes, plus two bridge nodes (db, cache) that connect into the machine — triggering factory-level detection.

Ordinal ships with 29 built-in templates covering common patterns across all three modes. Load any template from the palette to get started immediately.

Canvas Features

The canvas is a custom implementation — no third-party graph library.

Tech Stack

Running

npm install
npm run dev      # Dev server (localhost:5173 by default)
npm run build    # Build and output to Rhode's static directory

In production, Ordinal is served by Rhode at /ordinal/.

Validation

Ordinal uses a two-validator architecture:

• Frontend (JS) — runs on paste and load for instant feedback. Catches structural errors before any server round-trip.
• Backend (Python) — runs via Rhode's API and through Ordinal-MCP. Used for server-side validation, PLM enforcement, and pipeline execution.

Both validators enforce the same ontology rules: valid node types per mode, legal connection patterns, hierarchy consistency, and blueprint schema correctness.

Integration

Ordinal is the visual layer in a three-part system:

Ordinal-MCP wraps Ordinal's capabilities as MCP tools for use by AI agents and external systems. It is not a standalone implementation — it delegates to Ordinal and Rhode for validation, rendering, and execution.

License

MIT