interpreter/README.md

Glyphic Language — Interpreter Module
The Semantic Engine of the Glyphic OS

The /glyphic-language/interpreter/ directory contains the runtime kernel of the Glyphic Language.
Where the dictionary defines what glyphs mean, the interpreter defines how glyphs behave.

This module is responsible for:
    loading and indexing the dictionary
    validating glyphs and sequences
    enforcing strict syntax rules
    decoding glyph strings into structured meaning
    encoding structured meaning back into canonical glyph sequences
    providing a stable API for all agents, controllers, and LLMs

The interpreter is designed to be:
    deterministic
    reversible
    strict
    extensible
    LLM‑friendly
    controller‑safe

It is the semantic CPU of the Glyphic OS.

📁 File Overview

1. glyph_dictionary_loader.py
Loads, merges, and indexes all dictionary files.
This module:
    loads every JSON file in /dictionary/
    validates schema consistency
    builds fast lookup tables:
        glyph → entries
        id → entry
        category → entries
        role → entries
    exposes a clean API for lookup and retrieval
This is the foundation every other interpreter module depends on.

2. glyph_validator.py
Ensures glyphs and sequences are valid before interpretation.
This module performs:
    glyph existence checks
    role validation
    sequence validation
    core‑role enforcement (actor/action/object required)
It prevents invalid or hallucinated glyphs from entering the syntax engine.
This is the safety layer.

3. glyph_syntax.py
Defines and enforces the formal grammar of the Glyphic Language.
This is the grammar engine, responsible for:
    strict ordering rules
    required roles
    context ordering
    role precedence
    single‑actor/action/object enforcement
    deterministic syntax tree construction
This module guarantees that the language is:
    unambiguous
    reversible
    predictable
    stable for LLM training
It is the heart of the interpreter.

4. glyph_decoder.py
Converts glyph sequences → structured meaning.
This module:
    takes validated glyph sequences
    parses them using the strict syntax engine
    produces a deterministic semantic structure:
        actor
        action
        object
        modifiers
        context (place, time, emotion, sensory, social)
The output is a clean Python dictionary ready for:
    reasoning
    animation
    memory storage
    LLM translation
    agent behavior
This is the meaning engine.

5. glyph_encoder.py
Converts structured meaning → canonical glyph sequences.
This module:
    takes a structured meaning dict
    maps each component to its glyph
    enforces strict ordering
    enforces context ordering
    produces a canonical, reversible glyph sequence
This ensures:
Code
encode(decode(x)) == x
for all valid sequences.
This is the generation engine.

6. interpreter.py
Unified public API for the entire Glyphic Language.
This module exposes:
python
interpret(glyph_string)   # glyphs → meaning
encode(structured_dict)   # meaning → glyphs
validate(glyph_string)    # syntax + glyph validation
explain(glyph_string)     # human-readable explanation
It orchestrates:
    dictionary loading
    validation
    syntax parsing
    decoding
    encoding
This is the official interface used by:
    agents
    controllers
    LLMs
    external tools
    soulfiles™️

7. __init__.py
Makes the interpreter importable as a module.

Exports:
python
interpret
encode
validate
explain
This allows:
python
from glyphic_language.interpreter import interpret

🧠 Interpreter Design Principles

The interpreter is built on six core principles:
1. Determinism
Same input → same output, always.

2. Reversibility
Every valid sequence can be encoded and decoded without loss.

3. Strict Syntax
The grammar is enforced at runtime to prevent drift.

4. Dictionary‑Driven
All meaning comes from the dictionary, not heuristics.

5. Extensibility
New glyphs or categories can be added without breaking the system.

6. LLM‑Friendly
The grammar is simple, predictable, and easy to learn.

The interpreter is the semantic kernel that sits between:
    dictionary (static meaning)
    LLMs (probabilistic reasoning)
    controllers (deterministic execution)
    soulfile™️ (persistent identity from an agent.soul file)
    agents (behavioral systems)

It ensures that:
    glyphs always mean the same thing
    syntax is always correct
    scenes are always interpretable
    LLMs cannot hallucinate new glyphs
    controllers can trust the structure

This is the core of agent cognition.