schema-factory

name	schema-factory
description	Build, lint, ingest, compose Drescher-style schemas
license	MIT
tier	2
allowed-tools	["read_file","write_file","shell"]
related	["schema-mechanism","experiment","debugging","planning"]
tags	["moollm","schemas","drescher","deterministic","reasoning"]
credits	["Gary Drescher — Schema Mechanism (1991)","Henry Minsky — Blocksworld examples"]

SCHEMA-FACTORY

"Deterministic checks first, LLM second."

Build, lint, ingest, compose, and generate context for Drescher-style schemas.

---

Why This Exists

Gary Drescher's schema mechanism is strongest when it has:

1. Prescriptive schema-schema — what valid schemas must look like
2. Deterministic layer — evaluate and refine before asking the LLM
3. Context generator — emit only needed patterns and evidence

The goal is hybrid orchestration: Python does deterministic work, Cursor/LLM handles synthesis, MOOLLM stays explicit about what came from where.

---

Key Files

File	Purpose
SCHEMA-SCHEMA.yml	Drives linting and ingestion
schema_tool.py	CLI for all operations
examples/schema-example.yml	Compact schema set
examples/henry-minsky-blocksworld.yml	Classic microworld data

---

Quick Use

# Validate schemas
python3 schema_tool.py lint examples/schema-example.yml

# Compose action chain toward goal
python3 schema_tool.py compose --schemas examples/schema-example.yml --goal postgres-running

# Generate LLM context bundle
python3 schema_tool.py context --schemas examples/schema-example.yml --goal pyvision-running

---

Methods

LINT

Validate schema against schema-schema.

Input: One or more schema files (YAML)
Output: Pass/fail + diagnostics
Emits: schema_lint
Checks: Required fields, type validation, reliability range, non-empty context/result

python3 schema_tool.py lint my-schemas.yml

INGEST

Update schemas from experience logs or observed transitions.

Input: Experience logs
Output: Updated schema set + evidence counts
Emits: schema_ingest
Deterministic: No LLM calls; only schema updates

python3 schema_tool.py ingest experience-log.yml --into my-schemas.yml

COMPOSE

Build action chain toward goal.

Input: Schema set + goal
Output: Composed action chain + rationale
Emits: schema_compose

python3 schema_tool.py compose --schemas my-schemas.yml --goal target-state

CONTEXT

Generate compact context bundle for LLM synthesis.

Input: Schema set + goal + optional focus items
Output: Compact context bundle
Emits: context_generate
Includes: id, action, context, result, reliability, extended_context, extended_results

python3 schema_tool.py context --schemas my-schemas.yml --goal target-state --focus item1,item2

---

Schema Structure

schema:
  id: "unique-identifier"
  action: "what-the-schema-does"
  context:
    - precondition-1
    - precondition-2
  result:
    - postcondition-1
  reliability: 0.85  # 0.0-1.0
  
  # Optional
  extended_context: [...]
  extended_results: [...]
  evidence_count: 47
  marginal_attribution: {...}

---

Principles

1. Deterministic checks first, LLM second — Python validates before synthesis
2. Emit events for traceability — Know what happened where
3. Prefer small, explicit context bundles — Don't dump everything
4. Schema-schema can evolve — Via the same learning loop it governs

---

The Schema-Schema

The SCHEMA-SCHEMA.yml defines what valid schemas must look like:

• Required fields and their types
• Reliability range constraints
• Context/result non-empty rules
• Extension field patterns

This is prescriptive — schemas that don't match get lint errors.

---

Integration with LLM

The factory provides deterministic foundation for LLM reasoning:

# 1. Python validates and composes
schema_factory compose --goal postgres-running

# 2. Output becomes LLM context
"Here are the relevant schemas and a proposed action chain..."

# 3. LLM synthesizes and refines
"Based on these schemas, I recommend..."

# 4. Results feed back into ingest
schema_factory ingest --experience new-observations.yml

---

Dovetails With

• ../schema-mechanism/ — Theoretical foundation (Drescher)
• ../experiment/ — Schemas drive experiment design
• ../debugging/ — Schema failures are bugs to investigate
• ../planning/ — Schema composition is planning

---

"Validate structure. Compose plans. Generate context. Let the LLM shine where it should."