Skip to content

Tier 2 AI Content Pipeline — Review Round 2

Fresh review against the current MAID codebase.

Verified fixes

These specific concerns look addressed in the document:

  • Phase 0 provider API expansion is now acknowledged: the doc explicitly states current CompletionOptions is insufficient and that Phase 0 must land first (tier2-ai-content-pipeline.md:236-252, 105-150). This matches the current code, where CompletionOptions still only exposes plain text options (packages/maid-engine/src/maid_engine/ai/providers/base.py:92-103).
  • maid ai is not implemented today and the main command section now labels it as proposed (tier2-ai-content-pipeline.md:300-305). This matches the CLI, which has no ai Typer group (packages/maid-engine/src/maid_engine/cli/app.py:28-100).
  • Provider defaults / no-config behavior are mostly described correctly: ollama_host defaults to http://localhost:11434, chatjimmy_enabled defaults to True, and MockProvider is only registered when no other providers register (packages/maid-engine/src/maid_engine/config/settings.py:315-331, packages/maid-engine/src/maid_engine/ai/registry.py:326-380).
  • Admin-secret startup blocker is now called out (tier2-ai-content-pipeline.md:307-312), and the code really does reject the insecure default secret outside debug mode (packages/maid-engine/src/maid_engine/config/settings.py:1090-1194).
  • Budget/caching is correctly described as new infrastructure, not an extension of the existing dialogue budget/cache systems (tier2-ai-content-pipeline.md:282-289, 4225-4233).
  • Pack extension is now duck-typed rather than protocol-changing (tier2-ai-content-pipeline.md:4548-4565), which matches existing optional-pack patterns such as getattr(..., "register_component_types", None) and hasattr(pack, "register_api_routes") (packages/maid-engine/src/maid_engine/core/engine.py:696-698, packages/maid-engine/src/maid_engine/api/admin/router.py:1125-1128).
  • Structured-output sketches consistently route through complete_with_fallback() (tier2-ai-content-pipeline.md:1264-1475), which is the right fallback-aware API in the current registry (packages/maid-engine/src/maid_engine/ai/registry.py:184-256).

Remaining issues

1) HIGH — “Pipeline-compatible” YAML examples are still not loader-valid

  • Doc sections: 2.2 / example YAML (tier2-ai-content-pipeline.md:403-440, 477-560, 1807-1819, 4627-4644)
  • What’s wrong: several examples still use top-level fields the real loader rejects.
  • Room examples include top-level attributes (:434-438, :4642).
  • The NPC example includes top-level dialogue, schedule, and relationships (:503-560).
  • The fallback template sketch also emits top-level attributes (:1817-1819).
  • Why this is wrong in MAID: standard loader entity types only allow:
  • room: exits, zone
  • npc/item: location plus the reserved loader keys and components/tags (packages/maid-engine/src/maid_engine/loader/entity_types.py:7-28). Unknown top-level fields are rejected (packages/maid-engine/src/maid_engine/loader/assembler.py:55-79).
  • Suggested fix: rewrite every YAML example and fallback sketch to stay strictly component-centric. Move dialogue data into DialogueComponent; move schedule into ScheduleComponent; remove or componentize top-level attributes; ensure every example would actually survive the current loader’s top-level validation rules.

2) HIGH — ExtendedRoomComponent example still uses the wrong field names

  • Doc sections: room example in 3.1 / room YAML (tier2-ai-content-pipeline.md:417-431)
  • What’s wrong: the doc uses fields that do not exist on the real model:
  • time_descriptions
  • atmosphere
  • details
  • Why this is wrong in MAID: the real ExtendedDescriptions / ExtendedRoomComponent model uses:
  • time_variants
  • atmosphere_text
  • random_details and/or conditional_details
  • weather_effects, mood are valid (packages/maid-stdlib/src/maid_stdlib/components/extended_room.py:711-752, 472-489)
  • Suggested fix: update the room examples and any schema sketches to the actual field names. Otherwise the document is still teaching authors to generate invalid ExtendedRoomComponent payloads.

3) HIGH — ChatJimmy structured-output guidance is internally contradictory and not supported by the current client surface

  • Doc sections: 0.2, 2.3, and Phase 0 plan (tier2-ai-content-pipeline.md:109-116, 240-247, 4695-4700)
  • What’s wrong: the document says two incompatible things:
  • earlier: ChatJimmy = same as Ollama / JSON mode flag (:115, :246)
  • later: ChatJimmy adapter update = ignore structured fields, return text only (:4699)
  • Why this is a real problem: the vendored ChatJimmy client surface currently only exposes selected_model, system_prompt, and top_k; there is no visible JSON mode / response schema / tool-use parameter in ChatOptions or the request builder (packages/maid-engine/src/maid_engine/ai/providers/_jimmiedchat/models.py:22-34, packages/maid-engine/src/maid_engine/ai/providers/_jimmiedchat/client.py:149-167, 289-305).
  • Suggested fix: pick one story and make the document consistent. If ChatJimmy has no structured-output API today, say so explicitly and route it through GenericJSONAdapter until a real server capability exists.

4) MEDIUM — maid ai is only marked “proposed” in the command section; later sections still present it as existing behavior

  • Doc sections: proposed marker (tier2-ai-content-pipeline.md:300-305) versus later behavior narratives (:4600-4619, :4657-4667, :1067-1087)
  • What’s wrong: later sections switch back to present-tense implementation language, e.g.:
  • “The maid ai generate command handles this explicitly” (:4600)
  • shell transcripts for maid ai cache stats (:1079-1087)
  • local-Ollama usage examples (:4657-4667)
  • Why this is misleading: there is still no maid ai group in the CLI (packages/maid-engine/src/maid_engine/cli/app.py:28-100), and no packages/maid-engine/src/maid_engine/cli/ai.py file.
  • Suggested fix: add a repeated PROPOSED / NOT YET IMPLEMENTED callout to every later section that shows maid ai commands or transcripts, especially Sections 3.11 and 14.3–14.4.

5) MEDIUM — Mock-provider command behavior is still described as if implemented, but current code cannot do it

  • Doc sections: 14.3 No-Provider Behavior (tier2-ai-content-pipeline.md:4600-4644)
  • What’s wrong: the doc shows maid ai generate ... --provider mock producing a valid YAML skeleton and special no-provider UX.
  • Why this doesn’t match MAID today: current MockProvider is just a plain text responder that returns a canned string; it does not know how to emit structured generation skeletons (packages/maid-engine/src/maid_engine/ai/providers/base.py:486-519).
  • Suggested fix: either mark the entire mock-provider transcript as proposed future UX, or explicitly state that Phase 0/1 also require a new generation-layer mock adapter on top of the current plain-text MockProvider.

6) LOW — The “exact field names” checklist for ItemComponent is still incomplete

  • Doc section: agent-output requirements (tier2-ai-content-pipeline.md:2820-2827)
  • What’s wrong: the checklist says payloads must match registered Pydantic models exactly, but the ItemComponent line omits real fields such as template_id, is_bound, owner_id, container_capacity, and contents.
  • Why this matters: these are real fields on the current model (packages/maid-stdlib/src/maid_stdlib/components/core.py:448-463). The names shown are not wrong, but the list reads more exhaustive than it really is.
  • Suggested fix: either mark the list as “common examples” rather than exact/exhaustive, or expand it to include the full current ItemComponent schema.

Bottom line

Do not ship yet.

The major conceptual fixes are in place, but the document still contains loader-invalid YAML and at least one real component-schema mismatch (ExtendedRoomComponent). Those are exactly the kinds of errors this design is supposed to prevent.