X40 Schemas: Autonomous Workflow Automation Experiments

An experimentation stack for workflow automation built around JSON Schema–driven OpenAI API calls and Node-RED flows.
Instead of focusing primarily on cellular automata, this repo now treats cellular automata as one optional sandbox inside a broader system for iterating on, judging, and evolving automation workflows.

🧬 Project Overview

X40 Schemas is designed to help you:

• Prototype workflow automations as Node-RED flows.
• Define strict contracts for LLM inputs/outputs using JSON Schema.
• Call OpenAI models via schema-aware helpers that validate and hydrate responses.
• Run experiments automatically, log results, and compute composite fitness scores.
• Close the loop with an autonomous Node-RED controller that proposes, runs, and judges experiments continuously.

Core areas of the repo:

• openai_json_schemas/ – Shell + Node helpers for JSON Schema–first OpenAI calls.
• src/schemas/ – Canonical schemas for hypotheses, judgments, Node-RED flows, and more.
• node_red/flows/ – Node-RED flows for the autonomous researcher and LLM judge.
• x40_experiments/ – On-disk registry of experiments, analytics, and fitness scores.
• src/ – Python utilities (including the legacy cellular automata sandbox).

Cellular automata lives in src/rich_cellular_automata.py and related modules and now serves as an example environment, not the primary focus.

🏗️ Architecture

1. Schema‑First LLM I/O

• OpenAI JSON helpers in openai_json_schemas/:
  • openai_json_of_schema.sh – Call OpenAI and validate the JSON response against a schema.
  • openai_gen_json_schema.sh / openai_gen_vetted_schema.sh – Generate and vet schemas.
  • ajv_validate.sh, compare_hydrators.py, and tests under schemas/ + objects/.
• Shared schemas in src/schemas/:
  • hypothesis_schema.json – Next‑experiment proposals.
  • experiment_judgment_schema.json – Structured verdicts for completed runs.
  • node_red_flow_schema.json and related flow schemas.

Together, these pieces enforce typed, inspectable contracts between OpenAI, Node-RED, and the Python tooling.

2. Experiment Registry and Fitness Scoring

• Experiments are stored under x40_experiments/ with prompts, flows, metrics, and judgments.
• x40_experiments/scripts/compute_fitness.py:
  • Scans experiment directories and emits:
    • analytics/fitness_summary.json – Compact view used by the controller.
    • analytics/fitness_details.json – Full archive of scores and signals.
    • analytics/novelty_archive.json – Tracks behavior fingerprints for novelty.
  • Computes a composite fitness based on:
    • technical_success, novelty, simplicity, interaction, efficiency, reuse, and placeholders for external/revenue signals.
  • Adapts weights across generations (explore → pattern finding → exploit).

3. Node‑RED Flows

Key flows live in node_red/flows/:

• autonomous_researcher.json
  • Orchestrates the full loop:
    1. Recompute fitness via compute_fitness.py.
    2. Call the hypothesis LLM (using hypothesis_schema.json) to propose the next experiment.
    3. Materialize a new experiment directory (prompt, slug, refs, node types).
    4. Invoke run_experiment.sh to execute the flow.
    5. Append lifecycle events to analytics/meta_log.jsonl.
    6. Call the judge service and then self‑loop for the next iteration.
• judge_experiments.json
  • Exposes an HTTP endpoint (default POST /judge on port 1891).
  • Loads traces + metrics, builds a rich prompt, and calls openai_json_of_schema.sh.
  • Writes judgment.json alongside each experiment and updates registry.json.
  • Always returns a structured response and fails conservatively when parsing issues occur.

See docs/autonomous_research_workflow.md for a deep dive into this architecture.

4. Legacy / Sandbox: Cellular Automata

The original project started as an AI‑powered cellular automata sandbox:

• src/rich_cellular_automata.py – Rich‑based terminal simulation driver.
• src/cellular_automata.py, src/llm_cellular_automata.py, src/visualization.py.
• openai_json_schemas/ + src/schemas/cell_schema.json, environment_schema.json, etc. for structured LLM‑driven cell behavior.

These components are still available for experimentation and demos, but the primary active work is now around workflow automation and Node-RED experiments rather than cellular automata research.

🚀 Quick Start: Workflow Automation Loop

Prerequisites

1. Python + dependencies

   From the repo root:

   pip install -r requirements.txt

2. Node.js / Node-RED

   Install Node-RED globally (or via Docker) and ensure it can run custom user directories.

3. OpenAI API key

   export OPENAI_API_KEY='your-api-key-here'

1. Compute Fitness Scores

You can recompute experiment fitness manually at any time:

python3 x40_experiments/scripts/compute_fitness.py --top-k 15

This populates x40_experiments/analytics/fitness_*.json and novelty_archive.json.

2. Start the LLM Judge Service

Run the Node-RED judge flow on port 1891:

node-red \
  --userDir x40_experiments/JUDGE_scorer/userdir \
  --flowFile ../node_red/flows/judge_experiments.json \
  --port 1891

This exposes POST /judge (default http://127.0.0.1:1891/judge), which:

• Validates input (experiment_id).
• Loads metrics, traces, and registry context.
• Builds a prompt and writes it to /tmp/x40_judge_prompt.txt.
• Calls openai_json_schemas/openai_json_of_schema.sh using experiment_judgment_schema.json.
• Persists judgment.json and updates registry.json.

3. Run the Autonomous Researcher Flow

Import node_red/flows/autonomous_researcher.json into a Node-RED runtime and start the flow:

• A single manual inject kicks off the loop.
• The flow then:
  • Refreshes fitness summaries.
  • Calls the hypothesis LLM using hypothesis_schema.json.
  • Materializes and runs new experiments.
  • Sends them to the judge.
  • Loops back for the next iteration.

The system stays in continuous experiment mode: generating prompts, launching flows, evaluating them, and updating fitness metrics without manual babysitting.

🧪 Optional: Cellular Automata Sandbox

If you’d like to explore the original cellular automata environment as a side experiment:

1. Ensure dependencies are installed (see above).

2. Run a simple rule‑based simulation (no OpenAI required):

   python src/rich_cellular_automata.py --ticks 50 --cells 15 --speed 0.3

3. Enable LLM‑driven behavior (requires OPENAI_API_KEY):

   python src/rich_cellular_automata.py --llm --ticks 20 --cells 5 --speed 1.0

These simulations demonstrate how JSON Schema–validated LLM calls can drive complex local dynamics, but they are no longer the main focus of the repo.

🔍 Troubleshooting

• OpenAI / schema issues
  • Verify OPENAI_API_KEY is set: echo $OPENAI_API_KEY.
  • Use openai_json_schemas/ajv_validate.sh to check schemas and outputs.
  • Check API quota, network connectivity, and any local proxy settings.
• Node-RED flow issues
  • Confirm the correct --userDir and --flowFile paths.
  • Use Node-RED’s debug sidebar and logs to inspect payloads.
  • Ensure filesystem paths in exec nodes are absolute and match your checkout.
• Fitness / experiment registry
  • Re-run compute_fitness.py to refresh analytics.
  • Inspect x40_experiments/analytics/*.json for signal breakdowns.

For more detail, see docs/autonomous_research_workflow.md.

🤝 Contributing

Contributions are welcome, especially around:

• New workflow patterns and Node-RED components.
• Additional JSON Schemas for common automation tasks.
• Improvements to the fitness heuristics and novelty detection.
• Better observability and dashboards for experiment telemetry.
• Refinements to the autonomous loop, including new judges or hypothesis strategies.

📄 License

This project is open source. Please check the license file for details.

---

Happy automating and experimenting! 🧬🧠⚙️