LLMQuant / LLMQuant/quant-mind
design(config): define ownership of typed operation inputs
@keli-wen is already working on this.
Since Jul 18, 2026.
- Dominant language
- Python
- Stars
- 3k
- Forks
- 484
- PR merge metrics
- No merged PRs in 30d
Description
## Context
PR #120 exposed an unresolved design boundary in the operation input and configuration layer. `quantmind/configs/paper.py` currently combines paper identifiers such as `ArxivIdentifier` and `DoiIdentifier`, transport locators such as `HttpUrl` and `LocalFilePath`, and content inputs such as `RawText`. Some are structurally duplicated in other flow modules, while some variants validate as `PaperInput` even though Paper Flow V1 rejects them at runtime.
This issue intentionally separates the cross-flow Pydantic placement decision from #119 and PR #120. The Paper Flow refactor should not silently establish a repository-wide convention while implementing one vertical slice.
## Questions to Resolve
- When two inputs have the same fields and discriminator, should they share one transport-level Pydantic type or remain domain-specific nominal types?
- Should operation input unions contain only currently executable variants, or may they include reserved variants that fail at runtime?
- Should reusable source locators live under `quantmind.configs`, `quantmind.preprocess`, a dedicated input package, or beside the public operation that consumes them?
- Should a flow configuration remain flat, or compose stage-specific models such as ingest, parsing, chunking, summarization, persistence, and runtime settings?
- Which values should be closed enums or literals, and which extension points must remain open strings?
- How should any move preserve Pydantic JSON schema, YAML and magic resolution, discriminator stability, imports, and migration behavior?
## Design Options
### Shared structural types
Define reusable values such as `HttpSource`, `LocalFileSource`, and `RawTextSource`, then compose them into operation-specific discriminated unions.
This minimizes duplication but can erase domain semantics when the same shape has different content guarantees or runtime behavior.
### Flow-owned nominal types
Keep each input model beside its operation and give it a domain-specific name such as `PaperPdfUrl` or `EarningsReleaseUrl`, even when fields match.
This preserves semantic intent but duplicates validation and transport behavior.
### Hybrid boundary
Share transport primitives and validators while exposing operation-owned semantic wrappers or aliases. Operation unions contain only supported variants; future variants are introduced when their resolver exists. Stage-specific configuration models are composed by a small operation or pipeline config.
This is the initial candidate, not a decision. The discussion should test it against current paper, earnings, news, batch, magic, YAML, and schema-generation use cases.
## Acceptance Criteria
- [ ] Document the ownership rule for reusable transport values, domain identifiers, operation inputs, and stage configuration.
- [ ] Decide whether unsupported reserved variants belong in public discriminated unions.
- [ ] Define naming and import conventions that avoid same-named models with different semantics.
- [ ] Show the intended Pydantic JSON schema for at least Paper and Earnings inputs.
- [ ] Specify compatibility and migration behavior for existing Python, YAML, and magic callers.
- [ ] Implement focused `unittest.TestCase` coverage and one concise example after the design is accepted.
## Related Work
- #119 defines Source → Artifact → SearchProjection and the fixed Paper Flow V1 result.
- #120 implements that vertical slice and uses a typed `PaperArtifactKind` for the closed paper-artifact search discriminator without attempting this broader input/config relocation.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.