refactor(flows): wire the semantic shape through PaperFlow.build, rename to PaperSemantic*, and remove paper_flow#140
Merged
Conversation
…deprecate paper_flow PaperFlow.build now selects both paper knowledge shapes by cfg type: PaperStructureCfg -> PaperStructureTree (unchanged) and PaperFlowCfg -> PaperFlowResult (moved in from paper_flow, not duplicated). PaperFlow is generic over its result type, with constructor overloads that bind the result type from the cfg type, so each shape's callers keep a precise static return under basedpyright standard mode; a BaseFlowCfg fallback overload keeps other cfg types constructible and dispatches to NotImplementedError at runtime. paper_flow becomes a deprecated thin wrapper that emits a DeprecationWarning and delegates to PaperFlow(PaperFlowCfg(...)).build(input). Its signature is unchanged, so the magic-input introspection path is unaffected, and it stays grandfathered by the operation-naming contract rather than being removed. Tests, the paper example, the pdf-rag e2e slice, the paper flow design page, the naming contract, the library guide, and the component catalog row move to the config-bound entry point; a new test covers the deprecation warning and delegation. Co-Authored-By: Claude Fable 5 <[email protected]>
keli-wen
added
type: refactor
… wrapper Per PR #140 owner feedback, this replaces the deprecation with an outright removal and clarifies the semantic naming. - Rename `PaperFlowCfg` -> `PaperSemanticCfg` and `PaperFlowResult` -> `PaperSemanticResult` across configs, knowledge, flows, library, magic surfaces, tests, examples, docs, and contexts. `PaperFlowCfg` read like a parent of `PaperStructureCfg`, which it is not; the result is renamed for coherence now that no `paper_flow` function survives to anchor the old name. - Remove the `paper_flow` wrapper entirely (owner overruled the deprecation): drop the function, its `__all__` export, the `warnings` import, and the deprecation tests. `PaperFlow(cfg).build` is now the single entry point for both paper shapes. Update the naming contract so it no longer grandfathers a deleted symbol, and sweep the remaining prose references (README, AGENTS, docs, contexts, labels). - Point the magic examples and tests at `collect_news`, the only remaining public flow with the `(input, *, cfg)` signature that magic introspects, since paper no longer exposes such a function. - Bump stale model ids touched by this change to `gpt-5.6-luna` (the `PaperSemanticCfg` default, the paper example, the pdf-rag e2e slice, the magic resolver default, and the surrounding docs), and rename the e2e paths-filter key `paper_flow` -> `paper_semantic`. - Document that embedding is a downstream (library) concern, not a build concern: the `PaperSemanticCfg`/module docstrings note that vectors are minted at `LocalKnowledgeLibrary.open(..., embedding_model=...)` (examples use `text-embedding-3-small`), so no embedding field is added to the cfg. - Add a real-run snapshot to the module docstring from an actual arXiv `1706.03762v7` build under `gpt-5.6-luna`: the structure shape yields 17 nodes (13 leaves); the semantic shape chunks to 15 pages / 33 chunks, but the cited-summary step's verbatim-quote check rejected every sampled model's paraphrase this run, so no summary line is shown. Co-Authored-By: Claude Fable 5 <[email protected]>
keli-wen
changed the title
keli-wen
added a commit
that referenced
this pull request
Jul 23, 2026
…e, README restructure, contributor setup skill (#142) ## Summary Aligns the repository's narrative with the converged July 2026 positioning: QuantMind is an agent-native workbench for financial knowledge extraction, structured by two engineering dimensions — **context engineering** (any source → typed knowledge) and **harness engineering** (any agent → domain specialist). This PR lands the canonical positioning page, restructures the README around that story, and makes the README's agent-native contributing prompts real. ## Changes - **`contexts/design/positioning.md` (new)** — the single canonical positioning source: positioning and hero, the two dimensions, the bet, evaluation (design phase, no results claimed), the LLMQuant Data relationship, and the roadmap. The V1/V2 labels are documented as a poster-only contrast device; serious prose uses the dimension names. Registered in the design index and `CONTEXT_MAP.md`. Supersedes the April positioning spec. - **`README.md`** — workbench-first restructure: original slogan restored; Knowledge Engineering and The Vision sections with the two architecture figures; agent-path-first Quick Start with `PaperStructureCfg` / `PaperSemanticCfg` examples on one `PaperFlow`; a design-phase evaluation `[!NOTE]` referencing Anthropic's "Demystifying evals for AI agents"; LLMQuant Data production section with screenshot; direction-based roadmap; agent-native contributing prompts. Prose is unwrapped (no fixed-width hard wrapping). - **`AGENTS.md`** — positioning paragraph aligned to the dimension names and linked to the canonical page. - **`quantmind-dev` skill** — new `references/setup.md` (contributor setup and issue filing) with `SKILL.md` routing so the README prompts (`set me up as a contributor`, `file an issue`, `contribute a change`) resolve; mirrored byte-identically under `.agents/`. - **`contexts/dev/github-writing.md`** — the no-hard-wrap prose rule now also covers `README.md`. - **Assets** — the two architecture figures and the LLMQuant Data screenshot used by the README. This branch also carries two pending follow-up commits from `feat/harness-close-134-pr-title-and-boundary` (repo-root-relative cross-references in skills and contexts) that had no open PR of their own. ## Verification `bash scripts/verify.sh` green (ran in the pre-push hook); `tests/test_contexts.py` passes with the new page registered. README example symbols (`PaperFlow`, `PaperStructureCfg`, `PaperSemanticCfg`, `collect_news`, `batch_run`) verified against `quantmind/flows` and `quantmind/configs` exports on master after #140. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
PaperFlow.buildselects both paper knowledge shapes by the bound cfg type, so one config-bound flow produces every shape as the module docstring and the architecture constraint intend:PaperStructureCfg -> PaperStructureTree(unchanged)PaperSemanticCfg -> PaperSemanticResult(the source-first chunk/summary pipeline, moved in from the formerpaper_flow— the logic is relocated, not duplicated)NotImplementedErrorPaperFlowis generic over its result type with constructor overloads that bind the result type from the cfg type, so each shape's callers keep a precise static return underbasedpyrightstandard mode. ABaseFlowCfgfallback overload keeps other cfg types constructible so the runtimeNotImplementedErrorbranch stays reachable and type-clean.This revision applies the owner feedback on top of the original wiring change:
PaperFlowCfg -> PaperSemanticCfgandPaperFlowResult -> PaperSemanticResult.PaperFlowCfgread like a parent ofPaperStructureCfg(it is not), and the result is renamed for coherence now that nopaper_flowfunction survives to anchor the old name. The sweep covers configs, knowledge, flows, library, magic surfaces, tests, examples,docs/, andcontexts/.paper_flowis deleted outright (function, export,warningsimport, and its deprecation tests) rather than kept as a warning wrapper.PaperFlow(cfg).buildis the single entry point for both shapes. The operation-naming contract no longer grandfathers a deleted symbol, and the remaining prose references (README,AGENTS.md, docs, contexts, labels) are updated.collect_news, the only remaining public flow with the(input, *, cfg)signature thatresolve_magic_inputintrospects. Paper no longer exposes such a function, so this reflects the real surface.gpt-5.6-luna: thePaperSemanticCfgdefault, the paper example, the pdf-rag e2e slice, the magic resolver default, and the surrounding docs. The e2e paths-filter key is renamedpaper_flow -> paper_semantic.PaperSemanticCfg. The build produces only source, chunk, and summary text; vectors are minted at persistence time from theembedding_modelbound atLocalKnowledgeLibrary.open(...)(examples usetext-embedding-3-small). ThePaperSemanticCfgand module docstrings now say so in one line.Real run
Both shapes were run once against arXiv
1706.03762v7undergpt-5.6-luna, and the module docstring carries a short snapshot:"Attention Is All You Need".gpt-5.6-luna,gpt-5.5,gpt-5.2,gpt-4o) all paraphrased and the check raisedValueError, so no summary line is shown. This verbatim-quote strictness is pre-existing behavior of the summary pipeline (unchanged by this PR) and only surfaced here by the live run; it is called out for a follow-up, not fixed in this refactor.Related Issue
Closes #139
Verification
bash scripts/verify.sh— green (ruff format + ruff check + basedpyright + lint-imports +pytest --cov: 426 passed, 85.64% coverage, floor 75%).python scripts/verify_pdf_rag_e2e.py) is non-required and needsOPENAI_API_KEY+ public arXiv/model access; it was not run in CI here. The real-run notes above record the observed live behavior of both shapes.Checklist
type(scope): summary.bash scripts/verify.shpasses.🤖 Generated with Claude Code