feat: flows + magic apex layer (PR5 of OpenAI Agents SDK migration)

[keli-wen]

Summary

PR5 lands the apex layer of the OpenAI Agents SDK migration:

• quantmind/flows/ — paper_flow, batch_run + BatchResult, plus the internal _runner that wires RunConfig from BaseFlowCfg and composes multiple RunHooks into the single instance the SDK accepts.
• quantmind/magic.py — resolve_magic_input(natural_language, *, target_flow, ...) introspects a flow's input and cfg parameter annotations, builds a parameterized ResolvedFlowConfig[InputT, CfgT], and runs a lightweight resolver Agent. preview_resolve is the debug pretty-printer.
• Deletes the transitional packages now that the apex consumes them: quantmind/{flow,llm,config,models}/ and tests/{config,models}/.

After this PR the codebase has converged to the five permanent module roots (flows/, configs/, knowledge/, preprocess/, mind/) plus magic.py and utils/.

Highlights

paper_flow dispatch — isinstance chain on PaperInput's discriminated-union variants. Both HTTP and local-file branches share _format_by_content_type, which routes by Fetched.content_type (PDF / HTML / markdown / plain-text). DOI variant raises NotImplementedError pointing at the existing unpaywall follow-up — CrossrefMetadata does not expose a usable PDF URL.

batch_run — asyncio.Semaphore-bounded fan-out, deterministic error ordering, on_error: "raise" | "skip", on_progress callback. memory= is rejected at the signature layer (design doc §4.3.5) — for memory-accumulating workflows users write a serial loop themselves. BatchResult keeps parallel-arrays as primary representation and exposes successes / failures properties for the partitioned view; tokens_total / cost_estimate_usd defaults are placeholders that PR6's MemoryRunHooks will populate.

memory: object | None placeholder — paper_flow accepts the parameter today but the runtime is a no-op for any non-None value. PR6 narrows the type to a Memory Protocol and fills _collect_hooks + _archive_run_artifacts without changing the signature, batch_run, or magic.py introspection.

magic.py schema rendering — _pydantic_schema_str handles Annotated[X, ...] via __metadata__ (version-stable), unwraps Union[...] into oneOf, and gracefully degrades when a model holds non-JSON-schema fields (e.g. agents.ModelSettings carries callables). Falling back to a {title, fields} summary keeps the resolver useful.

Toolchain alignment

• [tool.basedpyright].exclude reduced to __pycache__ / .venv / build only.
• [tool.coverage.run].omit emptied; --cov-fail-under bumped from 65 to 75.
• Removed the two pydantic.* deprecation suppressors (they only covered the deleted models).
• Existing four import-linter contracts dropped references to the deleted packages.
• New fifth contract pins flows + magic as the apex layer; the deleted package names (quantmind.config, quantmind.flow, quantmind.llm, quantmind.models) are listed in forbidden_modules as a tripwire against accidental re-introduction.

Verify

[1/5] ruff format --check    OK
[2/5] ruff check             OK
[3/5] basedpyright           0 errors
[4/5] lint-imports           5 contracts KEPT
[5/5] pytest --cov           233 passed; coverage 89.48% (floor 75%)

Test plan

• bash scripts/verify.sh exits 0 with branch coverage ≥ 75 %
• grep -rn 'from quantmind\.\(flow\|llm\|config\|models\)' quantmind/ tests/ returns 0 hits
• All five import-linter contracts KEPT
• python -c "from quantmind.flows import paper_flow, batch_run, BatchResult, UnsupportedContentTypeError" succeeds
• python -c "from quantmind.magic import resolve_magic_input, preview_resolve, ResolvedFlowConfig" succeeds
• README runbook examples updated for paper_flow, batch_run, resolve_magic_input
• CLAUDE.md "Current Repository State" + "Roadmap" + "Things NOT to Do" rows refreshed

Follow-ups (not blocking this PR)

• quantmind/utils/logger.py reports 0 % coverage now that the transitional packages no longer import it. Add a smoke-test file under tests/utils/ whenever the logger gains a real consumer (PR6's memory layer is the first candidate).
• DOI → OA-PDF resolution (the NotImplementedError in paper_flow._fetch_and_format) needs the unpaywall fallback; tracked under PR4's deferred list.

Part of #71

🤖 Generated with Claude Code