MetaMo Prototype

MetaMo is an experimental control loop for Qwestor-style assistants. It predicts the best next action (respond, clarify, search, verify, decompose, think, synthesize) by parsing the user request, updating a stateful goal/anti-goal model, and routing execution through a LangGraph workflow.

How It Works

• parser.py – Asks an LLM (OpenAI or Gemini) to turn the raw query into normalized context signals (urgency, complexity, ambiguity, evidence needs, etc.).
• engine.py – Maintains the long-lived state (goals, anti-goals, modulators) and scores every action for the current turn. It returns the winning action plus diagnostics that explain why it was chosen.
• graph.py – Builds the LangGraph state machine that wires together the parser, engine, prompt templates, and the action-specific LLM calls. Search/verification nodes are currently simulated and can be swapped with real tools.
• runner.py – A stress-test harness that replays curated sessions. It is useful for regression testing and for observing how the engine’s internal signals evolve over multiple turns.

System flow

flowchart LR
    Q[User query] --> CP[context_parser / parse_context]
    CP --> EN[engine.step selects action]
    EN --> PS[prompt_shaper builds system prompt]
    PS -->|route_action| AR{Action router}
    AR --> RESP[act_respond\nquick_answer]
    AR --> CLAR[act_clarify\nsingle question]
    AR --> DECO[act_decompose\nplan steps]
    AR --> THINK[act_think\nreasoned answer]
    AR --> SEARCH[act_search\nsimulated evidence]
    AR --> VERIFY[act_verify\nsimulated verification]
    AR --> SYNTH[act_synthesize\nsimulated synthesis]
    SEARCH --> SEARCH_E[search_evidence]
    VERIFY --> VERIFY_E[verify_synthesis]
    SYNTH --> SYNTH_E[research_synthesis]
    RESP & CLAR & DECO & THINK & SEARCH_E & VERIFY_E & SYNTH_E --> PU[post_update updates engine_state]
    PU --> ST[engine_state stored for next turn]

Loading

Requirements

• Python 3.11+
• pip install langgraph langchain-core langchain-openai langchain-google-genai langchain langchain-community python-dotenv fastapi "uvicorn[standard]"
• API access to at least one provider:
  • OpenAI – needs OPENAI_API_KEY, optional OPENAI_MODEL (defaults to gpt-4.1-mini).
  • Google Gemini – needs GEMINI_API_KEY, optional GEMINI_MODEL (defaults to gemini-3-flash-preview).

Quick environment setup

./setup_env.sh            # creates .venv and installs dependencies
source .venv/bin/activate

The script accepts an optional path argument if you prefer a different venv location (e.g., ./setup_env.sh .venv-metam). It reuses the environment on subsequent runs.

Configuration

Copy .env.example to .env and adjust the values (or export them before running):

LLM_PROVIDER=openai          # or "gemini"
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini     # optional override
# GEMINI_API_KEY=...
# GEMINI_MODEL=gemini-1.5-pro

Only the keys for the selected provider are required. LLM_PROVIDER defaults to gemini if omitted. The example file keeps both providers so you can switch quickly by changing LLM_PROVIDER.

Running the Stress Harness

python runner.py

runner.py instantiates the compiled LangGraph app, replays every scripted session, and prints (1) the chosen action, (2) the contextual signals produced by parser.parse_context, (3) the modulators/goals tracked inside the engine, and (4) the text returned by the action node. This is the fastest way to validate changes to engine.py, prompt shaping, or the parser contract.

Use replay_runner.py --source-run <run-directory> for controlled ablation tests with frozen parser contexts. The live runner only selects the session set; ablation switches belong to the replay runner.

Running the Recommendation API

The recommendation API is intended for later Qwestor integration. It runs the parser and motivation engine, then returns the recommended action only. It does not return a user-facing answer.

python -m uvicorn api.main:app --host 0.0.0.0 --port 8020

Health check:

curl http://localhost:8020/health

Recommendation endpoint:

curl -X POST http://localhost:8020/recommend-action \
  -H "Content-Type: application/json" \
  -d '{"session_id":"demo","query":"Search for recent papers comparing MCMC and variational inference uncertainty quality.","recent_history":[],"project_context":{"research_topic":"MCMC vs VI uncertainty"}}'

Tuning the Engine

Key knobs live in engine.init_state()["params"]:

• *_alpha values control how quickly modulators react to new context.
• decompose_* thresholds guard when decomposition is allowed.
• reflective_think_bonus / reflective_search_penalty adjust reflective action scores.

Adjust these numbers, then re-run python runner.py to see how the selected actions and telemetry change over long sessions. The printed diagnostics help you spot oscillations, cold-start behavior, and anti-goal drift.

Troubleshooting

• Missing API keys raise a RuntimeError before any network call is attempted.
• If the parser cannot coerce the provider output into JSON after three retries, the run aborts with a clear error message. Inspect the provider logs or last_error hint.
• LangGraph must be installed; otherwise importing build_graph fails. Install langgraph 0.2+.
• All commands run locally; no persistence is created unless you store engine_state yourself.