System Flexible Graph Design: Wrapping Open-Source Repositories Behind Typed Swappable Engine Slots

Modern software teams face a recurring dilemma when building AI-assisted systems. If an agent generates every functional module from scratch on each prompt, the system pays high token latency, loses deterministic guarantees, and regresses on edge cases that open-source libraries solved years ago. Conversely, if an agent glues together arbitrary third-party GitHub repositories with direct imports across the codebase, a single upstream breaking change, license incompatibility, or missing runtime binary breaks the entire pipeline. In Loop Engine (baltor.ai and getagentfoundry.si), we solve this through System Flexible Graph Design: every functional unit sits behind a fixed, typed, versioned contract edge with swappable engines registered in engine_slots.yaml.

This architecture enforces a strict separation between what a functional boundary guarantees and which engine executes it at runtime. Whether a slot is backed by a containerized GitHub repository adapter, a zero-dependency Baltor-native engine, or a hardware-accelerated variation, callers communicate exclusively through the typed edge.

One Loop Runtime and the Fixed Contract Edge

A foundational rule in Loop Engine is that Loop is the only executable graph vertex. Practitioner, Intelligence, and Solution are roles; deterministic, hybrid, and non-deterministic are execution modes. We never introduce ad-hoc Node subclasses for third-party tools. Instead, a discrete cognitive or act step Loop node executes its narrowly scoped assignment using selected context and resources, separately initialized harnesses, permitted harness changes, and expectation checks, iterating until declared completion conditions are met while protecting against repeated external effects and keeping publication separate from completion.

When a Loop requires a specialized capability (such as entity resolution blocking, PDF layout compilation, 3D skeletal inverse kinematics, or statutory decision screening), it invokes an Engine Slot. Each slot defines a 7-Layer ComponentEnvelope:

1. Layer 1 (Typed Versioned Edge): Strict JSON Schema or Python dataclass definitions for request fields, result fields, and explicit machine-readable refusal codes.
2. Layer 2 (Pre-Condition and Post-Condition Invariants): Deterministic assertions checked before the engine runs and before its output is accepted.
3. Layer 3 (Declared Effect Authority): Explicit permissions for filesystem paths, network egress, shell subprocesses, model calls, and secret access. Discovery is strictly effect-free.
4. Layer 4 (Resource and Latency Budgets): Memory ceilings, CPU/GPU core allocations, and wall-clock timeouts enforced by the host runner.
5. Layer 5 (Individual and Group Conformance Kit): A mandatory test suite that every engine registered to the slot must pass individually and in multi-component pipeline groups.
6. Layer 6 (Pinned Source Provenance and License): Upstream Git repository URL, exact commit SHA-256, SPDX license identifier, and container image digest.
7. Layer 7 (Runtime Selection Policy and Evidence Ledger): Declared preference order and observed latency/accuracy telemetry allowing real-time engine switching without touching caller code.

How External GitHub Projects Enter the Library

Before building any new functional component, our engineering pipeline searches existing open-source repositories, published papers, and reference designs so we never reinvent the wheel unnecessarily. When we harvest a project from GitHub (through getagentfoundry.si), it enters the system through a three-step protocol:

• Step 1: Containerized Adapter Wrapping. The external repository is pinned to an immutable commit hash and license, isolated inside the container or sandbox profile required by its trust boundary, and wrapped in an adapter that translates its native API into the slot's Layer 1 typed request and result schema.
• Step 2: Pairing with a Baltor-Native Engine. Relying solely on an external binary or third-party service creates a single point of failure (as we saw when the private jev-1.13.0 registry was unreachable in clean environments). Therefore, every slot that wraps an external repository also receives a Baltor-native engine beside it that passes the exact same Layer 5 conformance kit.
• Step 3: Compact Contract Card Indexing (≤ 2,048 Bytes). To scale discovery above one million served component files without overflowing model context windows, the planner never loads full source files during graph assembly. It reads only the compact baltor_contract_card.json (under 2 KB), composes the solution graph, and materializes source bytes only for the selected engine.

Empirical Comparison: Direct Repo Imports vs. Swappable Engine Slots

We evaluated 40 multi-component engineering workflows across three integration architectures in compare.baltor.ai/systems and compare.baltor.ai/graphs: (1) regenerating code from scratch per prompt, (2) direct unencapsulated third-party imports, and (3) Loop Engine's 7-layer swappable engine slots:

Concrete Slot Definition and Runtime Selection

Below is a concrete excerpt showing how an engine slot in engine_slots.yaml binds an external containerized repository adapter alongside a zero-dependency Baltor-native engine and enforces deterministic conformance switching:

slot_id: entity_blocking_canopy_v1
contract_version: "1.0.0"
input_schema: schemas/entity_blocking_request_v1.json
output_schema: schemas/entity_blocking_result_v1.json
conformance_kit: tools/test_entity_blocking_slot_conformance.py
engines:
  - engine_id: splink_duckdb_container_v4
    kind: external_repo_adapter
    source_repo: "https://github.com/moj-analytical-services/splink"
    pinned_commit: "8f3c91a4e2b7d019c54a82e10f9d4b7c6a12e304"
    spdx_license: "MIT"
    sandbox_profile: "container_read_only_workspace"
    priority: 10
  - engine_id: baltor_native_sql_canopy_v1
    kind: baltor_native
    entrypoint: "loop_engine.engines.entity_blocking:NativeSqlCanopyEngine"
    spdx_license: "LicenseRef-Baltor-Proprietary"
    sandbox_profile: "in_process_deterministic"
    priority: 20
selection_policy:
  mode: "evidence_and_availability"
  require_conformance_receipt: true
  on_unavailable_or_timeout: "explicit_receipt_then_next_qualified_engine"

Individual, Group, and End-to-End Conformance Testing

A typed interface alone does not guarantee that two engines are truly interchangeable. In many plugin architectures, two adapters satisfy the same JSON Schema or Python protocol on paper, yet behave differently on boundary inputs, error recovery, or resource cleanup. When a caller swaps Engine A for Engine B in production, downstream steps break silently because Engine B returns unnormalized coordinate frames, sorts records in a different order, or swallows timeout exceptions.

To prevent behavioral drift between engines, Loop Engine enforces a three-tier conformance testing protocol defined in our Functional Component Standard (compare.baltor.ai/systems):

1. Tier 1 (Individual Slot Conformance Kit): Every slot in engine_slots.yaml points to an executable conformance kit (for example, tools/test_entity_blocking_slot_conformance.py). Whether an engine is an external GitHub repository running inside a read-only container or a Baltor-native Python/Rust implementation, it is fed the exact same golden input fixtures, malformed boundary payloads, and resource-limit probes. Both engines must produce equivalent typed outputs and identical refusal codes before either can be registered as active.
2. Tier 2 (Multi-Component Group Testing): Functional components rarely run in isolation. An Observation blocking slot feeds a Control Loop hypothesis-tree slot, which feeds a Bayesian log-odds verifier slot. We test connected component subgraphs across all valid Cartesian combinations of registered engines (for example, splink_duckdb_container_v4 + native_hypothesis_tree versus baltor_native_sql_canopy_v1 + native_hypothesis_tree) to verify that edge invariants hold across engine boundaries.
3. Tier 3 (End-to-End Solution Graph Replay): Before any catalog promotion, complete solution graphs are replayed in a clean environment with deterministic seed locking and network effect isolation.

Why Discovery Must Stay Under 2,048 Bytes per Component

As our component library scales past one million distinct served component files across creative 3D assets, shaders, physics controllers, and investigative verifiers (assets.baltor.ai), loading full source code during planning is impossible. By enforcing that every component publishes a self-contained baltor_contract_card.json under 2,048 bytes, a planning Loop can inspect 50 candidate contract cards in less than 15,000 tokens, verify type compatibility across edges, and materialize full implementation bytes only for the winning nodes.

Preserving Unchanged Implementations

When a customer revises one step of a creative or analytical project, the solution graph preserves every unchanged component implementation instead of paying tokens and wall-clock time to regenerate working code. Only the affected slot or parameter edge is re-evaluated, and every step emits a signed run receipt recording which engine executed, its resource usage, and its conformance verification status. Explore the interactive graph architecture comparisons at compare.baltor.ai/systems and compare.baltor.ai/graphs.