ReqLLM v2 architecture migration

[mikehostetler]

ReqLLM v2 draft

This draft PR starts the ReqLLM v2 architecture migration branch. ReqLLM v2 is intended to be a completely separate release path from the current ReqLLM package line, not a wholesale replacement merged all at once.

Feedback is welcome directly on this branch and PR while the architecture is still being shaped.

Goals

• Gradually pull the best architecture ideas from reqllm_next into req_llm.
• Preserve current req_llm public behavior while refactoring internals incrementally.
• Separate semantic request/response models from provider wire formats.
• Put provider-specific request encoding, response decoding, stream event parsing, and option translation behind provider-owned boundaries.
• Keep fixture-backed compatibility coverage as proof that provider behavior still works during the migration.
• Make each architecture step small enough to review independently.

Implementation plan

Checklist items in this section represent Beadwork epics, not individual tasks.

• req-qqb - Transition coverage to scenario-based tests: added the provider scenario contract and registry, extracted core text/tool/object/reasoning scenarios, rewired comprehensive provider coverage and mix req_llm.model_compat to use the shared scenario registry, added fixture guardrails, documented the workflow, and hardened scenario lookup/capability handling.
• req-aa2 - Map scenario taxonomy and modality coverage gaps: added a machine-checkable modality taxonomy for text and non-text behavior, guarded scenario groups against model_compat capability drift, aligned focused provider scenario routes, documented fixture-backed proof versus known gaps, and captured brainstormed follow-up epics.

Brainstormed next steps

This list is brainstormed and subject to change. Items should be promoted into separate Beadwork epics before implementation.

• Promote OCR into focused fixture-backed coverage once a stable provider/model target is selected.
• Add vision-input replay scenarios for image binary, image URL, and mixed text/image messages.
• Add document-input replay scenarios for file IDs, inline PDFs, OpenRouter file-parser behavior, and OpenAI Responses file handling.
• Split image generation into basic generation, edit/source image, mask, and provider option scenarios.
• Add audio-output chat scenarios for models that return text plus audio metadata or transcripts.
• Add video/media URL replay coverage where providers support it, and explicit rejection scenarios where they do not.
• Convert focused non-text provider macros into reusable scenario modules once the taxonomy is stable.
• Extract provider wire-format request encoding behind provider-owned modules.
• Extract provider response decoding behind provider-owned modules.
• Extract streaming event parsing behind provider-owned modules.
• Move deterministic request planning and option translation into a clearer internal layer.
• Keep live fixture recording explicit and reviewable when scenario behavior changes.
• Prepare v2 release notes and compatibility guidance once the internal migration is stable.

Current verification

• mix compile --warnings-as-errors
• mix test test/req_llm/scenarios test/mix/tasks/model_compat_test.exs
• mix test test/coverage/openai/web_search_test.exs --include coverage --only scenario:web_search_basic
• REQ_LLM_MODELS="openai:gpt-4o-mini" mix test test/coverage/openai/comprehensive_test.exs --include coverage
• mix test