{"id":28256883,"url":"https://github.com/sl-mar/quantcoderfs","last_synced_at":"2025-10-28T15:34:54.008Z","repository":{"id":292191003,"uuid":"977510333","full_name":"SL-Mar/quantcoderfs","owner":"SL-Mar","description":"A full-stack application that automates trading algorithms generation from academic papers","archived":false,"fork":false,"pushed_at":"2025-06-01T14:55:49.000Z","size":8206,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"dev","last_synced_at":"2025-06-17T12:42:30.259Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SL-Mar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-04T11:27:38.000Z","updated_at":"2025-06-12T19:43:47.000Z","dependencies_parsed_at":"2025-05-08T16:29:17.034Z","dependency_job_id":"e1562176-578a-4145-86f4-5a003d27833d","html_url":"https://github.com/SL-Mar/quantcoderfs","commit_stats":null,"previous_names":["sl-mar/quantcoderfs"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/SL-Mar/quantcoderfs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SL-Mar%2Fquantcoderfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SL-Mar%2Fquantcoderfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SL-Mar%2Fquantcoderfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SL-Mar%2Fquantcoderfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SL-Mar","download_url":"https://codeload.github.com/SL-Mar/quantcoderfs/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SL-Mar%2Fquantcoderfs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268340273,"owners_count":24234699,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-19T23:14:25.018Z","updated_at":"2025-10-28T15:34:48.972Z","avatar_url":"https://github.com/SL-Mar.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\n# QuantCoder FS\n\n**Local-first agent-based workflows for quantitative strategy extraction and automation**\n\n**Development Status:** Active development on `dev` branch. Current focus is on optimizing the AI workflow to reduce latency and improve compilation success rates. Note: models such as `gpt-4o-mini` have exhibited compatibility issues with Pydantic-based output validation.\n\nQuantCoder FS is a research platform that transforms financial articles into executable trading strategies using modular agentic pipelines. Designed to operate locally without reliance on cloud infrastructure or authentication systems, the platform enables structured exploration of language model capabilities in quantitative finance.\n\nThis repository contains the FastAPI backend, CrewAI-based agents, and modular orchestration logic for summarizing financial text and generating QuantConnect-compatible code. Performance depends on the selected LLM model and the clarity or relevance of the input article.\n\n\u003e The strategy research, including demonstrations and benchmarks, is published at: [https://quantcoderfs.substack.com/s/strategies](https://quantcoderfs.substack.com/s/strategies)\n\u003e Technical documentation and development updates are available at: [https://quantcoderfs.substack.com/s/development-updates-and-technical](https://quantcoderfs.substack.com/s/development-updates-and-technical)\n\n---\n\n## Project Scope\n\nQuantCoder FS is not a software-as-a-service product. It is a reproducible environment for the automated transformation of financial content into Python code, backed by a formal and inspectable flow of operations:\n\n* Parsing PDF or textual articles with embedded financial logic\n* Extracting structural sections and generating condensed summaries\n* Translating insights into boilerplate or production-ready trading code\n* Running local backtests via LEAN CLI when appropriate\n\n---\n\n## Key Features\n\n* Automated Research-to-Code workflow\n* Structured CrewAI pipeline: PDF → Summary → Code → AST Validation → Refinement\n* Local-first design: no login, no key storage\n* Output persistence in both user workspace and Lean environment folders\n* One-click local backtesting via LEAN engine\n\n---\n\n## Architecture Overview\n\n```\nFinancial Article (PDF)\n        ↓\n PDFLoader + TextPreprocessor\n        ↓\n HeadingDetector + SectionSplitter\n        ↓\n     CrewAI Flow (CodingFlow)\n        ↓\nExtract → Summarize → Code → Validate → Refine\n        ↓\n   Save to disk + Trigger lean backtest (optional)\n```\n\n---\n\n## CodingFlow v1.1 – Agent Workflow Description\n\nThe main orchestration is implemented as `CodingFlow` (defined in `flows/code.py`) and consists of a sequential CrewAI pipeline using five agents:\n\n1. **Section Extraction**: PDF content is processed via OCR and rule-based logic to identify document structure.\n2. **Summarization**: A dedicated agent condenses extracted sections into a concise, actionable summary.\n3. **Code Generation**: A third agent synthesizes Python code targeting the QuantConnect API.\n4. **AST Validation**: The generated code is parsed to check for syntax errors using Python’s `ast` module.\n5. **Refinement**: If a syntax issue is detected, the code is automatically revised by a corrective agent.\n\nEach stage is validated via typed Pydantic models (`SummaryResponse`, `GeneratedCode`) to ensure structural conformity.\n\n---\n\n### Interface Walkthrough\n\nBelow is a snapshot of the QuantCoder FS interface during the extraction and code generation process.\n\n![Interface View](frontend/public/QCFS_demo3.png)\n*Figure 1 – Interface showing the PDF reader (left) and generated QuantConnect code (right). The active document is “Benchmarks as Limits to Arbitrage: Understanding the Low Volatility Anomaly”.*\n\n---\n\n### LLM Workflow Trace\n\nA detailed log from the backend console illustrates the successful completion of each agentic step.\n\n![LLM Log](frontend/public/QCFS_LLM_Log.png)\n*Figure 2 – Backend console log showing task dispatch and successful strategy generation using GPT-4.1.*\n\n---\n\n### Lean Backtest Output\n\nOnce code generation is complete, a local Lean backtest is triggered. The following screenshot shows the backtest results for the low volatility strategy.\n\n![Backtest Output](frontend/public/QCFS_Backtest.png)\n*Figure 3 – LEAN backtest results printed in the terminal. The engine serves as both a compilation validator and a runtime executor.*\n\n---\n\n## PDF Analysis Pipeline\n\nThe section extraction logic used in the first stage of the flow is encapsulated in a custom CrewAI tool and consists of:\n\n* `PDFLoader`: Reads the entire PDF content using `pdfplumber`, preserving page order.\n* `TextPreprocessor`: Removes URLs, numbering, headers, and irrelevant formatting artifacts.\n* `HeadingDetector`: Uses both rule-based regular expressions and spaCy NLP to detect potential section titles.\n* `SectionSplitter`: Splits the text into structured sections based on detected headings, assigning each a `type_hint` field (e.g., \"methodology\", \"findings\").\n\n---\n\n## Backend Directory Structure\n\n```bash\nbackend/\n├── agents/        # CrewAI agents for parsing, summarizing, and coding\n├── core/          # Logging configuration, environment settings, usage tracking\n├── models/        # Typed Pydantic schemas\n├── routers/       # FastAPI route definitions (e.g., /filemanager, /coder)\n├── utils/         # Preprocessing and validation utilities\n└── workflows/     # CrewAI flows, including CodingFlow\n```\n\n## Frontend Directory Structure\n\n```bash\nfrontend/\n├── components/    # PDF viewer, code display, chat panel\n├── lib/           # State management and API abstraction\n├── pages/         # Next.js page routing\n├── public/        # Static assets (screenshots, icons)\n├── styles/        # Global Tailwind CSS styles\n├── types/         # TypeScript interfaces and shared types\n├── next.config.js # Next.js config file\n└── package.json   # Project metadata and dependencies\n```\n\n---\n\n## Installation\n\n### Step 1: Clone the repository\n\n```bash\ngit clone https://github.com/SL-Mar/quantcoderfs.git\ncd quantcoderfs\ngit checkout dev\n```\n\n### Step 2: Set up a virtual environment\n\n```bash\npython -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n```\n\n### Step 3: Configure environment variables\n\n```env\nOPENAI_API_KEY=your-key-here\nMODEL_NAME=gpt-4o\n```\n\n### Step 4: Launch the API server\n\n```bash\nuvicorn backend.main:app --reload --port 8000\n```\n\nInteractive documentation available at:\n[http://localhost:8000/docs](http://localhost:8000/docs)\n\n---\n\n## End-to-End Workflow\n\n1. Upload a PDF containing a trading-related research article.\n2. The system parses and analyzes the document’s structure.\n3. An LLM generates a summary and synthesizes initial code.\n4. The code is checked for syntax errors and optionally refined.\n5. A backtest may be triggered using Lean CLI.\n6. The code is saved to both the working directory and Lean-compatible folders.\n7. Results appear in the developer console or terminal.\n\n---\n\n## Lean Integration\n\nWhen a strategy is successfully generated, a background process runs:\n\n```bash\nlean backtest \"Algorithm.Python/\u003cfilename\u003e.py\"\n```\n\nThis enables rapid iteration and testing using the local LEAN environment.\n\n---\n\n## Tooling Overview\n\n| Component                 | Access | Description                                  |\n| ------------------------- | ------ | -------------------------------------------- |\n| QuantCoder FS Backend     | Open   | Modular PDF → Code pipeline                  |\n| Frontend Interface        | Open   | Stateless Next.js app                        |\n| Authentication / Accounts | None   | No user accounts or login required           |\n\n---\n\n## License\n\nThis software is released under the Apache License 2.0.\nSee `LICENSE.md` for terms of use and redistribution.\n\n---\n\n## References\n\n* [QuantCoder FS Documentation \u0026 Updates](https://quantcoderfs.substack.com/s/development-updates-and-technical)\n* [QuantCoder FS: Strategy Research](https://quantcoderfs.substack.com/s/strategies)\n* [Medium: *Toward Automating Quantitative Finance Research*](https://medium.com/ai-advances/towards-automating-quantitative-finance-research-c868a2a6477e)\n\n---\n\n## Citation\n\n```\nS.M. Laignel. (2025). QuantCoder FS: LLM-powered strategy coding and automation for Quantitative Finance. GitHub Repository. https://github.com/SL-Mar/quantcoderfs\n```\n\n---\n\n## Contributing\n\nDevelopment occurs on the `dev` branch. Please submit pull requests against `dev`. I welcome contributions to:\n\n* New agent types or flows\n* Frontend interface improvements\n* PDF parsing tools or validation enhancements\n\n---\n\n## Known Issues\n\n* `gpt-4o-mini` occasionally returns non-conforming outputs that fail Pydantic validation and for this reason, is normally de-activated in the selection list.\n* `o1` is excessively expensive and should be avoided. It is by default de-activated in the code.\n* OCR-based PDFs are currently not supported. The system assumes machine-readable text.\n* Latency and error rate are higher when summarization is run on documents with inconsistent or sparse structure.\n\n---\n\n## Changelog\n\n**Current Version:** v1.1 (AI Workflow)\n\n* Introduced `CodingFlow v1.1` using CrewAI sequential tasking.\n* Added syntax validation and conditional refinement.\n* Enabled local backtesting via Lean CLI integration.\n\nThis version defines the current software baseline. Future versions will align with major changes to agent logic or orchestration.\n\n---\n\n## Author\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eS.M. Laignel\u003c/b\u003e\u003cbr\u003e\n  Founder of \u003cb\u003eSL MAR\u003c/b\u003e consultancy\u003cbr\u003e\n  Quant Developer — modular automation for research workflows in quantitative finance.\u003cbr\u003e\u003cbr\u003e\n  🌐 \u003ca href=\"https://quantcoderfs.substack.com\"\u003eSubstack — QuantCoderFS R\u0026D\u003c/a\u003e\u003cbr\u003e\n  💻 \u003ca href=\"https://github.com/sl-mar/quantcoderfs\"\u003eGitHub Repository\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsl-mar%2Fquantcoderfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsl-mar%2Fquantcoderfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsl-mar%2Fquantcoderfs/lists"}