anrl formal specification
weighted directed multigraph · epistemic confidence markers · transformer-optimized
abstract data model
an anrl document consists of a sequence of nodes and edges forming a weighted, directed multigraph with epistemic confidence markers.
entity node
a discrete, uniquely identifiable semantic concept. a person, service, project — any named thing in the domain.
primitive node
a scalar value, instruction, constraint, or unstructured text block attached to the most recently declared entity.
relational edge
an explicit typed graph link between two entities. prevents column slippage and enables multi-hop reasoning.
causal edge
distinguishes a directional state change, transition, or causation between two entities. not mere correlation.
formal syntax
anrl syntax is line-oriented. indentation is permitted for human readability but is semantically ignored by the compiler.
Every ANRL statement must be prefixed by a weight marker. Quantization tiers: !1.0 (critical), !0.8 (high), !0.5 (normal, default), !0.2 (weak), !0.0 (suppress). The formatter quantizes continuous weights to these 5 discrete tiers before rendering — empirically sufficient for LLMs to distinguish attention priorities without float noise confusion.
Defines an entity and its semantic schema type. Entity identifiers use underscore-delimited PascalCase by convention. The type suffix provides semantic context for downstream reasoning. Generic type suffixes (:: Object, :: Array) are elided in output to reduce token cost.
Attaches a scalar value or block to the most recently declared entity. Prefixes: * (static data/fact), ^ (system instruction/intent), % (constraint/guardrail), $ (few-shot example). The ? suffix encodes epistemic confidence — if omitted, implicitly ?1.0 (verified).
Explicitly links two entities with a typed, directed relation. The relation label is free-text but should be descriptive. Multi-hop reasoning collapses if relations are modeled as flat string attributes (*owner: John_Doe) — edges are the preferred form for any relationship that might be traversed in reasoning.
Models causation or temporal transition. Semantically stronger than a relational edge — implies directional state change, not mere association. Used in event logs, incident reports, and causal reasoning chains.
A suffix applied to primitives or edges, denoting epistemic certainty. If omitted, confidence is implicitly ?1.0 (fully verified) — compilers should suppress ?1.0 in text emission to save tokens. Three tiers: VERIFIED (?1.0, suppressed), KNOWN (?0.7–0.9), SPECULATIVE (?0.2–0.5).
syntactic elision
to minimize token-count overhead, parsers and compilers must support elision for default values. compilers should omit defaults during emission.
!0.5 @Worker :: Node !0.5 *status: healthy ?1.0
@Worker :: Node *status: healthy
empirical implementation constraints
based on benchmarking across multiple models and tasks, anrl implementations must adhere to the following constraints for reliable llm ingestion.
ANRL zero-shot syntax parsing is gated by model size. ≥7B parameters: parse ANRL natively with zero overhead. <7B parameters: ~30% accuracy penalty due to syntax unfamiliarity. Requires supervised fine-tuning (SFT) on ANRL datasets to achieve baseline parity.
Multi-hop reasoning collapses if relations are modeled as flat string attributes. Violative: *owner: John_Doe. Compliant: @Service --owned_by--> @John_Doe. The distinction enables the formatter output to be a heterogeneous graph embedded in text.
The same ?confidence operator requires different system prompts for different tasks. Mode A (conflict resolution) requires an explicit canonical prompt instructing "prefer highest confidence." Mode B (hedging) requires no prompt — adding one produces incorrect behavior. Any API emitting ANRL must know the downstream task type. Workaround: use ^query directives at document top.
document structure best practices
for optimal llm comprehension, structure an anrl document chronologically:
^query: Which service is degraded? ^traverse: dependency graph ^return: root cause entity
Declare ^query:, ^traverse:, and ^return: at the top of the context window to signal task type to the LLM.
!1.0 @NorthStar :: Primary_Service !1.0 @Query_Target :: Incident
Declare highly weighted, frequently referenced entities early in the document. The project linker duplicates top-K anchors into every file's prelude.
!0.8 @Service_API :: Service *version: 2.4.1 !0.8 @Service_API --depends_on--> @NorthStar
Declare remaining entities, primitives, and edges. Avoid interleaving unassociated entities where possible.