Homoiconic Meta Schema

Homoiconic Meta-Schema

Overview

Agent-friendly knowledge graphs need homoiconicity: code and data in the same representation, so agents can inspect and modify their own operational logic. Ch3 gives two constructs.

Meta-knowledge structures (Example 3-6). A metaschema describes the schema itself — it defines what an EntityType is (a name, a description, a list of property definitions). Then domain knowledge is stored using the same representation: a Person entity-type is just data with name, birth_date, occupation properties. The syntax of schema and data is identical. This skill runs the same validation at both levels: validate_entity_type checks a type against the metaschema; validate_data_against_type checks an instance against its type. Same machinery, two levels — that is the homoiconic property doing real work. It lets agents reason about knowledge completeness, dynamically update schemas as they learn, and self-evolve without external reprogramming.

Executable knowledge patterns (Example 3-7). Operational rules become first-class graph entities. A Rule has descriptive metadata, a condition (graph pattern match), and an action (tiered WHEN ... THEN SET ... / ELSE). Because the rule is data, agents can reason about rules, not just follow them — discover, modify, create rules, and explain decisions by citing the rule. This skill parses the tiered action, validates the rule has a parseable clause, and evaluates it in source order against facts (DetermineCustomerSegment: 25 purchases -> Premium, 15 -> Regular, 3 -> Basic). The DevOps OperationalRule (ValidateProductionDeployment) is the same construct applied to infrastructure.

When to Use

• Building agents that reason about or modify their own schema (Ch7 self-evolution)
• Storing business/operational rules as queryable graph data, not hidden code
• Validating agent-proposed schema extensions before applying them
• Representing the ontology itself as data the agent can query

Phrases: "homoiconic", "metaschema", "schema as data", "entity-type definition", "executable knowledge", "rule as graph entity", "self-evolving schema", "meta-knowledge".

When NOT to Use

• Static schemas. If the schema never changes, a plain class/struct is simpler; homoiconicity pays off only when the agent modifies its own structure.
• General code execution. evaluate_rule interprets a constrained tiered WHEN/THEN/ELSE grammar, NOT arbitrary code. Do not treat it as an interpreter for untrusted input.
• Schema PATTERN selection. Use schema-pattern-selector to choose Event-Centric vs Multi-Perspective etc.; this validates the homoiconic meta-level and executable rules.

Process

Rationalizations

Red Flags

• Entity-type passes but instances of it keep failing required-field checks. The type declares fields the data pipeline never populates — the schema and the extractor disagree.
• A Rule validates but evaluate_rule returns None for normal inputs. The action clauses don't cover the input range and there's no ELSE — add a default tier.
• WHEN clauses out of order in the source. Tiered evaluation will match the wrong tier; reorder most-specific-first.
• Agent proposes a schema extension with a property type outside the allowed set. Reject and surface — unchecked types are how schema drift enters a self-evolving system.

Non-Negotiable Verification

1. Run the benchmark battery. python cli.py benchmark must report 10/10:
   • valid Person type passes; missing-name, duplicate-property, invalid-type fail
   • data instance: required-present passes, missing-required and wrong-type fail
   • rule parses 2 WHEN + 1 ELSE; tiered eval gives 25->Premium, 15->Regular, 3->Basic
   • rule missing action fails
2. Run the scenario. python cli.py scenario customer-segment validates the Person type as data, validates an instance against it, and evaluates the segmentation rule across tiers.
3. Verify CLI help. python cli.py --help exits 0 and prints this SKILL.md description (so any harness can discover the skill from --help).

Security Posture

• Prompt injection. Entity-type definitions and Rule actions are untrusted data, often agent-proposed. The evaluator interprets only the constrained WHEN/THEN/ELSE grammar - never eval/exec - so injected text fails parsing rather than executing. A syntactically valid rule can still encode malicious LOGIC; review agent-proposed rules before storing them in the graph.
• Data exfiltration. No network calls, no file writes. Facts passed to evaluate_rule stay in-process; results go to stdout and the caller owns downstream piping.
• Privilege escalation. Self-modifying schemas are the escalation surface: an unchecked schema extension or rule rewrite widens what the agent may later assert. The validator rejects out-of-set property types, and rule evaluation returns a plain dict - it never mutates the graph or grants a capability; applying changes is a separate, gated step.

Source Attribution

Distilled from Agentic GraphRAG (O'Reilly, by Anthony Alcaraz and Sam Julien) Ch3 — Knowledge Representation, section "Homoiconic Knowledge Representation": meta-knowledge structures (Example 3-6, the metaschema + Person entity-type) and executable knowledge patterns (Example 3-7, the DetermineCustomerSegment Rule). The DevOps OperationalRule (ValidateProductionDeployment) in the chapter's "Homoiconic Knowledge Representation for Agent Adaptability" section is the same construct applied to infrastructure, feeding the Ch7 self-evolution work.