Skip to content

llm_context.md

Latest commit

 

History

History
245 lines (182 loc) · 8.45 KB

llm_context.md

File metadata and controls

245 lines (182 loc) · 8.45 KB
Raw

Ortelius LLM Context

One-Sentence Summary

Ortelius is a Codex-facing graph-population protocol system and Python toolkit for building, validating, inspecting, and materializing typed/fibered graph JSON.

What Ortelius Does

Ortelius gives Codex a repo-local workflow surface for creating candidate graph data. The workflow begins with a human graph-building request and a system protocol document. Codex compiles that request into a generated protocol bundle, then executes bounded graph-population actions through Markdown loop specs, JSON graph files, cursor state, execution logs, reports, and source-batch artifacts.

The key workflow prompt is:

MAKE-GRAPH

Use assets/protocol_assets/system/graph_population/v001/graph_population_protocol_schema.md
as the graph-build request compilation schema.

Make graph on domain: <domain>, with <N> node types and <M> instances of each
type, and then <E> edge types and <K> instances of each.

That minimal prompt is valid and sufficient. For broad or multi-model domains, missing graph intent triggers front-door triage; Codex must ask bounded alignment questions or propose candidate lenses and stop before source probing, bundle generation, type discovery, or graph JSON writes. Optional graph-intent fields can accelerate triage, but they are not required in the initial prompt.

What Ortelius Does Not Do

Ortelius v0.1.0 does not itself call Codex, crawl the web, persist to a graph database, train graph ML models, guarantee source completeness, or guarantee graph quality.

The protocol docs tell Codex how to structure the workflow. The Python package validates and materializes the graph JSON that workflow produces.

Semantic completion is stricter than structural validation. For ordinary MAKE-GRAPH, raw JSON counts do not satisfy targets unless the records are accepted, source-backed, field-sufficient, graph-intent-fit, and reconciled in the semantic acceptance report. Candidate records, deterministic completion records, and source-shape-only records do not count toward requested targets.

Source reconnaissance is Markdown-first: Codex must materialize graph intent, write source plans and batch packets, and audit generated mechanical code before source results can shape graph records.

Semantic acceptance is row-backed. For ordinary MAKE-GRAPH, a bundle must carry inspectable Markdown reports for semantic plan authority, source probe event order, type candidate review, type-specific field discovery, edge candidate review, edge-family diversity, edge-specific field discovery, domain membership boundaries, source evidence accounting, label quality, semantic sample audit, and accepted target reconciliation. Summary-only reports and raw counts do not satisfy graph completion.

Generated helper code is mechanical only. It may convert, count, serialize, or validate Markdown-authorized rows, but it must not decide graph intent, source strategy, type inventory, edge inventory, field discovery, acceptance status, or completion.

Graph Model

Ortelius uses two graph IDs:

<fiber_graph_id> -> <type_graph_id>

The type graph defines admissible node types and edge types. Type records also define field schemas expected on concrete records.

The fiber graph contains concrete nodes and concrete edges. Every fiber node has a type_id pointing to a type node. Every fiber edge has a type_id pointing to a type edge.

Core projection invariant:

edge = fiber_edges[e]
edge_type = type_edges[edge.type_id]
source_node = fiber_nodes[edge.source_id]
target_node = fiber_nodes[edge.target_id]

source_node.type_id == edge_type.source_type_id
target_node.type_id == edge_type.target_type_id

System Protocol Pair

The v001 system protocol pair lives here:

assets/protocol_assets/system/graph_population/v001/

Important files:

The protocol schema is the compiler/bundle generator. It handles MAKE-GRAPH and GENERATE-BUNDLE.

The control protocol is the executor. It handles EXECUTE-BUNDLE for an already generated bundle.

Generated Bundle Contract

Generated graph-population bundles belong under:

assets/protocol_assets/bundles/<domain_slug>/<protocol_id>/

Generated bundle contents typically include:

manifest.json
graph_population_protocol.md
control_loop_plan.md
loop_specs/
candidate_graphs/
runs/<run_id>/cursor.json
runs/<run_id>/execution_log.md
runs/<run_id>/reports/
  graph_intent_contract.md
source_batches/
batch_packets/
tool_outputs/

Generated bundles are ignored by git by default. The only tracked file in the generated-bundle root should be:

assets/protocol_assets/bundles/.gitkeep

Python Package Surface

Package:

src/ortelius/

Stable top-level imports:

from ortelius import GraphBundle, load_graph_bundle, validate_graph_bundle

Materializers:

from ortelius.materialize.networkx import (
    to_networkx_fiber_graph,
    to_networkx_type_graph,
)
from ortelius.materialize.pyg import validate_pyg_readiness, to_pyg_fiber_graph
from ortelius.materialize.dgl import validate_dgl_readiness, to_dgl_fiber_graph

Protocol checks:

from ortelius.protocol_assets import (
    validate_protocol_bundle,
    validate_system_protocol_assets,
)

CLI Examples

Validate the v001 system protocol assets:

uv run ortelius protocol validate-system --system-root assets/protocol_assets/system/graph_population/v001

Validate and inspect the minimal generated-bundle fixture:

uv run ortelius protocol validate-bundle --protocol-root tests/fixtures/protocol_assets/minimal_generated_bundle
uv run ortelius protocol inspect-bundle --protocol-root tests/fixtures/protocol_assets/minimal_generated_bundle

Validate and inspect the generic graph fixture:

uv run ortelius validate --graph-root tests/fixtures/graph_assets/minimal_generic/graphs --type-graph-id tg --fiber-graph-id fg --mode bootstrap
uv run ortelius inspect --graph-root tests/fixtures/graph_assets/minimal_generic/graphs --type-graph-id tg --fiber-graph-id fg

Run materialization smokes:

uv run ortelius materialize networkx --graph-root tests/fixtures/graph_assets/minimal_generic/graphs --type-graph-id tg --fiber-graph-id fg
uv run ortelius materialize pyg --graph-root tests/fixtures/graph_assets/minimal_generic/graphs --type-graph-id tg --fiber-graph-id fg
uv run ortelius materialize dgl --graph-root tests/fixtures/graph_assets/minimal_generic/graphs --type-graph-id tg --fiber-graph-id fg

Stable Links

Release Facts

  • Package name: ortelius
  • Current version: 0.1.0
  • Python: >=3.12
  • License: MIT
  • Protocol version: v001
  • Main CLI: ortelius
  • Main prompt: MAKE-GRAPH

LLM Handling Notes

When assisting with Ortelius:

  • Treat the protocol docs as operational documents, not background prose.
  • Treat generated bundle files as run authority once a bundle exists.
  • Do not invent hidden helper scripts as the workflow driver.
  • Do not infer graph intent silently for broad domains unless the prompt explicitly authorizes infer-and-proceed.
  • Do not claim the Python package performs autonomous crawling.
  • Do not commit generated domain bundles by default.
  • Keep examples domain-neutral unless the user explicitly requests a domain.