LLMQuant / LLMQuant/quant-mind

Tracking: Migrate Agent layer to OpenAI Agents SDK

Open
#71 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area: flows area: mind type: refactor
Dominant language
Python
Stars
3k
Forks
484
PR merge metrics
No merged PRs in 30d

Description

## Motivation

QuantMind invested ~3 months building a smolagents-derived Agent runtime in PRs #61, #65, and #67 (~1900 lines of `brain/` + `tools/` + supporting modules). We now believe this was a wrong direction:

- **Agent runtime is a commodity in 2026.** OpenAI Agents SDK, smolagents, LangGraph, etc. compete on the same surface. Maintaining our own gives QuantMind no differentiation.
- It consumes engineering time that should go into financial-domain work (data schemas, e2e pipelines, research-friendly memory patterns).

This issue tracks the migration to **OpenAI Agents SDK** as the underlying agent runtime, with QuantMind repositioning as a domain library on top.

> **Architecture update (2026-07-15):** Durable canonical collections and semantic indexing belong to the top-level `quantmind/library/` package tracked in #111. `mind/` owns cognition, tools, working memory, and later tree navigation; it may consume `library` but does not own persistence or index lifecycle. This supersedes the vague `KnowledgeStore` placement in the original roadmap below.

## Target Architecture

```
quantmind/
├── flows/ # e2e processing pipelines (paper_flow, news_flow, ...)
├── knowledge/ # Pydantic-based knowledge schema standard (Paper, News, ...)
├── library/ # canonical collections + derived semantic index (#111)
├── preprocess/ # fetch (arxiv/http/doi/local) + format (pdf/html/markdown)
├── mind/ # cognition, tools, working memory, tree navigation; no persistence
├── configs/ # centralized BaseFlowCfg + per-flow cfg + input types
├── magic.py # resolve_magic_input: natural language → (input, cfg)
└── utils/ # logger only
```

Key principle: QuantMind does **NOT** rebuild Agent runtime, lifecycle hooks, tracing, multi-agent handoff, or tool framework. Those come from `openai-agents`.

## Roadmap

- [ ] **PR1** (#70): Clean removal of self-built agent runtime
- [ ] **PR2**: `knowledge/` + `configs/` skeleton (Pydantic schemas + centralized cfg)
- [ ] **PR3**: `preprocess/` two-layer structure (fetch + format)
- [ ] **PR4**: `flows/` + `paper_flow` + `batch_run` + `magic.py`; concurrent removal of `flow/` and `llm/`
- [ ] **PR5**: `mind/memory/filesystem` MVP + trajectory archive
- [ ] **PR6+**: Semantic library (#111), paper-search integration (#112), PageIndex navigation (#95), additional sources, and observability cookbook

## Archive

The pre-pivot agent runtime is preserved as a snapshot on the [`archive/agent-runtime-final`](https://github.com/LLMQuant/quant-mind/tree/archive/agent-runtime-final) branch on origin for historical reference. It will not be merged back to master.

## References

- OpenAI Agents SDK docs: https://openai.github.io/openai-agents-python/
- Lifecycle / RunHooks: https://openai.github.io/openai-agents-python/ref/lifecycle/
- MCP integration (filesystem server): https://openai.github.io/openai-agents-python/mcp/
- Tracing: https://openai.github.io/openai-agents-python/tracing/
- SDK announcement: https://openai.com/index/the-next-evolution-of-the-agents-sdk/

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the target architecture and the referenced PRs #61, #65, #67, and #70, then inspect the current brain/, tools/, flow/, and llm/ areas. This issue is a migration tracker rather than a self-contained task; it is done only when the roadmap’s migration work has been completed.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
ai, backend
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.