Implement XIC v1.5: Symbolic Pipeline Abstraction with Glyph-Aware Transformations
Implements all phases of the symbolic pipeline extension: **Phase 1: Symbolic Pipeline Abstraction** - Created glyphos/symbolic_pipeline.py with: - SymbolicStep: tracks individual pipeline steps (name, kind, payload, context) - SymbolicPipelineResult: complete pipeline execution result (steps, output_text, fused_symbol) - run_symbolic_pipeline(prompt, context, glyph_id): high-level pipeline entrypoint - Integrated with glyphos/__init__.py exports **Phase 2: Glyph-Aware Transformations** - Updated glyphos/cognitive_kernel.py: - run_symbolic_prompt() now thin wrapper around pipeline - Maintains backward compatibility - Updated xic_ops.py operations: - op_RUN_PROMPT: uses pipeline in symbolic mode - op_STREAM: uses pipeline with line-by-line output - op_CALL_GLYPH: routes through pipeline with explicit glyph_id parameter - Context propagation: glyph_id automatically injected into LAIN context **Phase 3: XIC Instruction Semantics v1.5** - Created XIC_SEMANTICS_v1_5.md: - Formal specification of all 9 XIC instructions - Complete semantics: preconditions, postconditions, side effects - Symbolic vs compressed behavior for each op - Context model and pipeline semantics - Execution paths (compressed vs symbolic) - Backward compatibility guarantees **Phase 4: Demo Program & Validation** - Created programs/demo_symbolic_pipeline.gx.json - Demonstrates symbolic pipeline with glyph-aware cognition - Uses CALL_GLYPH, RUN_PROMPT, SET_CONTEXT, CHAIN, LOG - All 7 validation tests pass: ✅ Pipeline module imports ✅ Pipeline execution ✅ Glyph-aware transformations ✅ Demo program ✅ CALL_GLYPH result storage ✅ Backward compatibility ✅ run_symbolic_prompt() wrapper **Phase 5: Final Report** - Created XIC_SYMBOLIC_PIPELINE_REPORT.md - Architecture and module hierarchy - Integration points and data flow - Design decisions and rationale - Usage examples Key Features: - Step-level introspection: full SymbolicPipelineResult with step history - Glyph-aware: explicit glyph_id routing through LAIN kernel - Formal semantics: complete specification for tool builders - Backward compatible: all v1 programs work unchanged - No breaking changes: compressed execution path untouched Constraints Met: ✅ No GPU code ✅ No XIC v2 binary container ✅ No .gx format changes ✅ Full backward compatibility
This commit is contained in:
GlyphRunner System
@@ -0,0 +1,411 @@
|
||||
# XIC Instruction Semantics v1.5
|
||||
|
||||
**Version**: 1.5
|
||||
**Date**: 2026-05-21
|
||||
**Status**: Formal Specification
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
XIC v1.5 is a symbolic and compressed execution virtual machine. It provides:
|
||||
|
||||
1. **Dual execution modes**: Compressed (via execute_gx) and symbolic (via symbolic pipeline)
|
||||
2. **Explicit instruction set semantics**: Formal definitions of preconditions, postconditions, and side effects
|
||||
3. **Glyph-aware symbolic processing**: Integration with LAIN 8-lane cognition and glyph metadata
|
||||
4. **Context propagation**: Symbolic context flows through chains of operations
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
XICContext (model_path, mode, params, context, symbolic_mode, _state)
|
||||
↓
|
||||
XIC Instructions (9 ops in OP_TABLE)
|
||||
↓
|
||||
Dual paths:
|
||||
- Compressed: execute_gx() → decompresses .gx → execs Python
|
||||
- Symbolic: run_symbolic_pipeline() → LAIN 8 lanes → fused_symbol
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## XICContext Model
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Meaning |
|
||||
|-------|------|---------|
|
||||
| `model_path` | Optional[str] | Path to .gx model file. Set by LOAD_MODEL. |
|
||||
| `mode` | str | Execution mode: "chat", "eval", "benchmark", "symbolic". Default: "chat". |
|
||||
| `params` | Dict[str, Any] | Execution parameters (temperature, trace, profile, use_gpu, etc.). |
|
||||
| `context` | Dict[str, Any] | (In params["context"]) Symbolic/cognitive context metadata (domain, style, glyph_id, etc.). |
|
||||
| `symbolic_mode` | bool | True if mode == "symbolic". Controls routing in RUN_PROMPT/STREAM/CALL_GLYPH. |
|
||||
| `_state` | Dict[str, Any] | Internal state: last_result, last_symbolic_result, last_symbolic_pipeline, glyph_* keys. |
|
||||
|
||||
### Context Propagation
|
||||
|
||||
- `SET_CONTEXT <key> <value>` adds/updates keys in `ctx.params["context"]`.
|
||||
- Context is passed to `run_symbolic_pipeline(context=...)` in symbolic operations.
|
||||
- Glyph operations add `glyph_id` to context automatically.
|
||||
|
||||
---
|
||||
|
||||
## Instruction Semantics
|
||||
|
||||
### 1. LOAD_MODEL
|
||||
|
||||
**Signature**
|
||||
```json
|
||||
{ "op": "LOAD_MODEL", "args": ["<path_to_gx_file>"] }
|
||||
```
|
||||
|
||||
**Preconditions**
|
||||
- Argument must be a valid string (path).
|
||||
|
||||
**Postconditions**
|
||||
- `ctx.model_path = path`
|
||||
|
||||
**Side effects**
|
||||
- Prints `[XIC] Model loaded: <path>`
|
||||
|
||||
**Symbolic behavior**
|
||||
- No effect on `ctx.symbolic_mode`.
|
||||
|
||||
**Compressed behavior**
|
||||
- `ctx.model_path` is used by RUN_PROMPT/STREAM to load the .gx file.
|
||||
|
||||
---
|
||||
|
||||
### 2. SET_MODE
|
||||
|
||||
**Signature**
|
||||
```json
|
||||
{ "op": "SET_MODE", "args": ["<mode>"] }
|
||||
```
|
||||
|
||||
**Preconditions**
|
||||
- `mode` ∈ {"chat", "eval", "benchmark", "symbolic", ...}
|
||||
|
||||
**Postconditions**
|
||||
- `ctx.mode = mode`
|
||||
- If `mode == "symbolic"`: `ctx.symbolic_mode = True`
|
||||
- If `mode != "symbolic"`: `ctx.symbolic_mode = False`
|
||||
|
||||
**Side effects**
|
||||
- Prints `[XIC] Mode set to: <mode>`
|
||||
|
||||
**Remarks**
|
||||
- Setting mode to "symbolic" enables routing through symbolic pipeline (run_symbolic_pipeline).
|
||||
- All other modes use compressed execution (execute_gx).
|
||||
|
||||
---
|
||||
|
||||
### 3. SET_PARAM
|
||||
|
||||
**Signature**
|
||||
```json
|
||||
{ "op": "SET_PARAM", "args": ["<key>", <value>] }
|
||||
```
|
||||
|
||||
**Preconditions**
|
||||
- Arguments: key (str), value (any).
|
||||
|
||||
**Postconditions**
|
||||
- `ctx.params[key] = value`
|
||||
|
||||
**Side effects**
|
||||
- Prints `[XIC] Parameter <key> = <value>`
|
||||
|
||||
**Remarks**
|
||||
- `use_gpu`, `trace`, `profile` are reserved parameter names.
|
||||
- Parameters are passed to execute_gx (if used).
|
||||
|
||||
---
|
||||
|
||||
### 4. SET_CONTEXT
|
||||
|
||||
**Signature**
|
||||
```json
|
||||
{ "op": "SET_CONTEXT", "args": ["<key>", <value>] }
|
||||
```
|
||||
|
||||
**Preconditions**
|
||||
- Arguments: key (str), value (any).
|
||||
|
||||
**Postconditions**
|
||||
- `ctx.params["context"][key] = value`
|
||||
- If `ctx.params["context"]` doesn't exist, it is created.
|
||||
|
||||
**Side effects**
|
||||
- Prints `[XIC] Context <key> = <value>`
|
||||
|
||||
**Usage**
|
||||
- Build symbolic context metadata: `SET_CONTEXT "domain" "ai"`, `SET_CONTEXT "style" "analytic"`.
|
||||
- Context is passed to symbolic operations (RUN_PROMPT, STREAM, CALL_GLYPH).
|
||||
|
||||
---
|
||||
|
||||
### 5. RUN_PROMPT
|
||||
|
||||
**Signature**
|
||||
```json
|
||||
{ "op": "RUN_PROMPT", "args": ["<prompt>"] }
|
||||
```
|
||||
|
||||
**Preconditions**
|
||||
- Argument: prompt (str).
|
||||
|
||||
**Postconditions**
|
||||
- If `ctx.symbolic_mode == True`:
|
||||
- `ctx._state["last_symbolic_result"] = output_text`
|
||||
- `ctx._state["last_symbolic_pipeline"] = SymbolicPipelineResult`
|
||||
- If `ctx.symbolic_mode == False`:
|
||||
- Requires `ctx.model_path` to be set (LOAD_MODEL must be called first).
|
||||
- `ctx._state["last_result"] = ExecutionContext`
|
||||
|
||||
**Symbolic behavior** (ctx.symbolic_mode=True)
|
||||
- Calls `run_symbolic_pipeline(prompt, context=ctx.params.get("context"))`.
|
||||
- Routes through LAIN 8-lane cognition kernel.
|
||||
- Prints `[XIC-SYMBOLIC] <output_text>`
|
||||
- Stores full SymbolicPipelineResult for inspection (steps, fused_symbol).
|
||||
|
||||
**Compressed behavior** (ctx.symbolic_mode=False)
|
||||
- Calls `execute_gx(ctx.model_path, trace=ctx.params.get("trace"), profile=ctx.params.get("profile"))`.
|
||||
- Decompresses .gx binary and executes Python code.
|
||||
- Prints `[XIC] Execution complete` and result.
|
||||
|
||||
**Remarks**
|
||||
- The prompt argument is informational in compressed mode (not used).
|
||||
- In symbolic mode, the prompt is the primary input to LAIN cognition.
|
||||
|
||||
---
|
||||
|
||||
### 6. STREAM
|
||||
|
||||
**Signature**
|
||||
```json
|
||||
{ "op": "STREAM", "args": ["<prompt>"] }
|
||||
```
|
||||
|
||||
**Preconditions**
|
||||
- Argument: prompt (str).
|
||||
|
||||
**Postconditions**
|
||||
- Same as RUN_PROMPT, but output is streamed line-by-line.
|
||||
|
||||
**Symbolic behavior**
|
||||
- Calls `run_symbolic_pipeline(prompt, context=...)`.
|
||||
- Streams output_text line-by-line with `[XIC-STREAM]` prefix.
|
||||
- Stores pipeline result in `ctx._state["last_symbolic_pipeline"]`.
|
||||
|
||||
**Compressed behavior**
|
||||
- Calls `execute_gx(...)`.
|
||||
- Streams result line-by-line with `[XIC-STREAM]` prefix.
|
||||
|
||||
**Side effects**
|
||||
- Multiple print statements (one per line).
|
||||
|
||||
---
|
||||
|
||||
### 7. CHAIN
|
||||
|
||||
**Signature**
|
||||
```json
|
||||
{ "op": "CHAIN", "args": ["<label>"] }
|
||||
```
|
||||
|
||||
**Preconditions**
|
||||
- Argument: label (str).
|
||||
|
||||
**Postconditions**
|
||||
- `ctx.params["chain_label"] = label`
|
||||
|
||||
**Side effects**
|
||||
- Prints `[XIC-CHAIN] Entering chain: <label>`
|
||||
|
||||
**Remarks**
|
||||
- CHAIN is a control marker for human readability and logging.
|
||||
- It does not affect execution but allows grouping operations into named chains.
|
||||
- Chain label is preserved in `ctx.params` for inspection.
|
||||
|
||||
---
|
||||
|
||||
### 8. CALL_GLYPH
|
||||
|
||||
**Signature**
|
||||
```json
|
||||
{ "op": "CALL_GLYPH", "args": ["<glyph_id>", "<payload>"] }
|
||||
```
|
||||
|
||||
**Preconditions**
|
||||
- Arguments: glyph_id (str), payload (str, optional).
|
||||
|
||||
**Postconditions**
|
||||
- Stores result in `ctx._state[f"glyph_{glyph_id}"]` with:
|
||||
- `output_text`: Final text from cognition
|
||||
- `fused_symbol`: Fused symbolic representation (if produced)
|
||||
- `steps`: List of pipeline steps taken
|
||||
|
||||
**Symbolic behavior**
|
||||
- Calls `run_symbolic_pipeline(prompt=payload, context=glyph_context, glyph_id=glyph_id)`.
|
||||
- `glyph_context = ctx.params.get("context", {}) | {"glyph_id": glyph_id}`
|
||||
- Routes through symbolic pipeline with explicit glyph_id parameter.
|
||||
- The glyph_id is injected into LAIN context for glyph-aware transformations.
|
||||
- Prints `[XIC-GLYPH] <output_text>`
|
||||
|
||||
**Compressed behavior**
|
||||
- Not applicable. CALL_GLYPH is only used in symbolic mode.
|
||||
- If called in compressed mode, raises error (or gracefully falls back to symbolic).
|
||||
|
||||
**Remarks**
|
||||
- CALL_GLYPH enables glyph-aware cognition: the symbolic pipeline explicitly marks the operation as glyph-driven.
|
||||
- The LAIN kernel can use glyph_id to apply glyph-specific transformations or select glyph metadata.
|
||||
|
||||
---
|
||||
|
||||
### 9. LOG
|
||||
|
||||
**Signature**
|
||||
```json
|
||||
{ "op": "LOG", "args": ["<message>"] }
|
||||
```
|
||||
|
||||
**Preconditions**
|
||||
- Argument: message (str, optional).
|
||||
|
||||
**Postconditions**
|
||||
- None (pure side effect).
|
||||
|
||||
**Side effects**
|
||||
- Prints `[XIC-LOG] <message>`
|
||||
|
||||
**Remarks**
|
||||
- LOG is a no-op from an execution standpoint; purely for instrumentation and debugging.
|
||||
|
||||
---
|
||||
|
||||
## Symbolic Pipeline Semantics
|
||||
|
||||
### run_symbolic_pipeline() Entrypoint
|
||||
|
||||
```python
|
||||
def run_symbolic_pipeline(
|
||||
prompt: str,
|
||||
context: Dict[str, Any] | None = None,
|
||||
glyph_id: str | None = None,
|
||||
) -> SymbolicPipelineResult
|
||||
```
|
||||
|
||||
**Behavior**:
|
||||
1. Creates SymbolicStep for initial_prompt.
|
||||
2. If glyph_id is provided:
|
||||
- Adds glyph_id to context.
|
||||
- Creates SymbolicStep for glyph_call.
|
||||
3. Compresses prompt via GXCompressor.compress().
|
||||
4. Builds minimal manifest/segments.
|
||||
5. Calls CognitiveKernel.execute_symbolic(manifest, segments, payload, mode="symbolic", context=context).
|
||||
6. Extracts output_text and fused_symbol from result.
|
||||
7. If fused_symbol is present:
|
||||
- Creates SymbolicStep for fusion.
|
||||
8. Returns SymbolicPipelineResult(steps, output_text, fused_symbol).
|
||||
|
||||
### SymbolicPipelineResult
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class SymbolicPipelineResult:
|
||||
steps: List[SymbolicStep] # Execution steps taken
|
||||
output_text: str # Final text output
|
||||
fused_symbol: Optional[Dict] # Fused symbolic representation
|
||||
```
|
||||
|
||||
### SymbolicStep
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class SymbolicStep:
|
||||
name: str # Step name (e.g., "initial_prompt", "glyph:xyz", "fusion")
|
||||
kind: str # Step kind ("prompt", "glyph_call", "fused_symbol")
|
||||
payload: Any # Step data (prompt text, fused_symbol dict, etc.)
|
||||
context: Dict[str, Any] # Context at this step
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Execution Paths
|
||||
|
||||
### Compressed Path (ctx.symbolic_mode=False)
|
||||
|
||||
```
|
||||
RUN_PROMPT or STREAM
|
||||
↓
|
||||
Check ctx.model_path
|
||||
↓
|
||||
execute_gx(path, trace=..., profile=...)
|
||||
↓
|
||||
Load .gx binary → decompress via GSZ3 → compile → exec Python
|
||||
↓
|
||||
Store result in ctx._state["last_result"]
|
||||
```
|
||||
|
||||
### Symbolic Path (ctx.symbolic_mode=True)
|
||||
|
||||
```
|
||||
RUN_PROMPT or STREAM or CALL_GLYPH
|
||||
↓
|
||||
run_symbolic_pipeline(prompt, context, glyph_id)
|
||||
↓
|
||||
Compress prompt → build manifest/segments
|
||||
↓
|
||||
CognitiveKernel.execute_symbolic()
|
||||
↓
|
||||
LAIN 8-lane cognition (structural, semantic, compression, metadata, hints, predictive, imprint, epoch)
|
||||
↓
|
||||
Fuse lanes → produce output_text and fused_symbol
|
||||
↓
|
||||
Store SymbolicPipelineResult in ctx._state["last_symbolic_pipeline"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Context Flow
|
||||
|
||||
**Example: Glyph-Aware Cognition**
|
||||
|
||||
```
|
||||
SET_CONTEXT "domain" "ai"
|
||||
SET_CONTEXT "style" "analytical"
|
||||
CALL_GLYPH "glyph://knowledge_integration" "How do compression and knowledge integrate?"
|
||||
```
|
||||
|
||||
**Flow**:
|
||||
1. SET_CONTEXT adds `context = {"domain": "ai", "style": "analytical"}` to `ctx.params["context"]`.
|
||||
2. CALL_GLYPH reads `context` and adds `glyph_id = "glyph://knowledge_integration"`.
|
||||
3. `run_symbolic_pipeline(prompt, context={"domain": "ai", "style": "analytical", "glyph_id": "..."}, glyph_id="...")` is called.
|
||||
4. Symbolic pipeline creates SymbolicStep(glyph_call, ...) with the full context.
|
||||
5. LAIN kernel executes with context, allowing glyph-aware transformations.
|
||||
6. Result (output_text, fused_symbol) is stored in `ctx._state["glyph_glyph://knowledge_integration"]`.
|
||||
|
||||
---
|
||||
|
||||
## Backward Compatibility
|
||||
|
||||
- All v1 XIC programs continue to work unchanged.
|
||||
- RUN_PROMPT behavior in compressed mode (symbolic_mode=False) is identical to v1.
|
||||
- New symbolic pipeline is additive and does not affect compressed execution.
|
||||
- run_symbolic_prompt() in glyphos/cognitive_kernel.py is a thin wrapper around the pipeline.
|
||||
|
||||
---
|
||||
|
||||
## Summary of Changes from v1
|
||||
|
||||
| Change | v1 | v1.5 |
|
||||
|--------|----|----|
|
||||
| Symbolic pipeline abstraction | Inline in run_symbolic_prompt | Separate glyphos/symbolic_pipeline.py |
|
||||
| Glyph-aware transformations | Manual context manipulation | Explicit glyph_id parameter in run_symbolic_pipeline |
|
||||
| Pipeline introspection | Limited (just output_text) | Full SymbolicPipelineResult (steps, fused_symbol) |
|
||||
| Formal semantics | Implicit (docstrings) | Explicit (XIC_SEMANTICS_v1_5.md) |
|
||||
|
||||
---
|
||||
|
||||
**End of Specification**
|
||||
Reference in New Issue
Block a user