{"id":31068383,"url":"https://github.com/franksunye/quantdb","last_synced_at":"2025-09-15T21:07:52.487Z","repository":{"id":293042703,"uuid":"982750104","full_name":"franksunye/quantdb","owner":"franksunye","description":"High-performance stock data caching service based on AKShare data source, providing intelligent caching, RESTful API, and professional frontend interface.  🚀 Cloud Deployment Ready! Now provides complete cloud deployment solutions, including local development environment and Streamlit Cloud deployment version.","archived":false,"fork":false,"pushed_at":"2025-08-11T14:19:43.000Z","size":6701,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-11T14:54:22.123Z","etag":null,"topics":["streamlit","webapp"],"latest_commit_sha":null,"homepage":"https://quantdb-cloud.streamlit.app/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/franksunye.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-13T10:57:23.000Z","updated_at":"2025-08-11T14:19:26.000Z","dependencies_parsed_at":"2025-07-14T16:22:48.415Z","dependency_job_id":null,"html_url":"https://github.com/franksunye/quantdb","commit_stats":null,"previous_names":["franksunye/quantdb"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/franksunye/quantdb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/franksunye%2Fquantdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/franksunye%2Fquantdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/franksunye%2Fquantdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/franksunye%2Fquantdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/franksunye","download_url":"https://codeload.github.com/franksunye/quantdb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/franksunye%2Fquantdb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275320320,"owners_count":25443870,"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-09-15T02:00:09.272Z","response_time":75,"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":["streamlit","webapp"],"created_at":"2025-09-15T21:07:50.407Z","updated_at":"2025-09-15T21:07:52.446Z","avatar_url":"https://github.com/franksunye.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# QuantDB - High-Performance Python Stock Data Toolkit 🚀\n\n*English | [中文版本](README.zh-CN.md)*\n\n\u003e **Intelligent caching wrapper for AKShare with 90%+ performance boost** - Complete stock data ecosystem with smart SQLite caching for Chinese financial markets. Perfect for quantitative trading, financial analysis, and algorithmic trading in Python.\n\n![Version](https://img.shields.io/badge/version-2.2.9-blue)\n![License](https://img.shields.io/badge/license-MIT-green)\n![Python Package](https://img.shields.io/badge/PyPI-quantdb-blue)\n[![codecov](https://codecov.io/gh/franksunye/quantdb/branch/main/graph/badge.svg)](https://codecov.io/gh/franksunye/quantdb)\n![API](https://img.shields.io/badge/API-FastAPI-009688)\n![Database](https://img.shields.io/badge/Database-SQLite-4169E1)\n![Tests](https://img.shields.io/badge/Tests-259/259-success)\n![Frontend](https://img.shields.io/badge/Frontend-Streamlit-FF4B4B)\n![Cloud](https://img.shields.io/badge/Cloud-Ready-brightgreen)\n![Performance](https://img.shields.io/badge/Cache-90%25_faster-brightgreen)\n![Integration](https://img.shields.io/badge/Integration-Complete-success)\n![Status](https://img.shields.io/badge/Status-Production_Ready-success)\n\n**Intelligent caching wrapper for AKShare with 90%+ performance boost** - Complete stock data ecosystem with smart SQLite caching for Chinese financial markets.\n\n**🎉 NOW AVAILABLE ON PyPI!**\n[![PyPI version](https://badge.fury.io/py/quantdb.svg)](https://pypi.org/project/quantdb/)\n[![Downloads](https://pepy.tech/badge/quantdb)](https://pepy.tech/project/quantdb)\n\n```bash\npip install quantdb  # One command, instant 90%+ speed boost!\n```\n\n```python\nimport qdb  # Note: import name is 'qdb' for simplicity\ndf = qdb.get_stock_data(\"000001\", days=30)\n\n# New in v2.2.9: Multi-market support!\ndf_china = qdb.get_stock_data(\"000001\", days=30)  # China A-shares\ndf_hk = qdb.get_stock_data(\"00700\", days=30)      # Hong Kong stocks\nrealtime = qdb.get_realtime_data(\"000001\")        # Real-time quotes\nfinancials = qdb.get_financial_summary(\"000001\")  # Financial data\n```\n\n**Three product formats**: Python Package, API Service, and Cloud Platform for different user needs.\n\n## 🎯 Product Matrix\n\n### 📦 **QuantDB Python Package** - For Developers\n```bash\npip install quantdb\n```\n```python\nimport qdb  # Note: Package name is 'quantdb', import name is 'qdb'\ndf = qdb.get_stock_data(\"000001\", days=30)  # 90%+ faster than AKShare!\n```\n**Perfect for**: Quantitative researchers, Python developers, data scientists\n**Import Note**: Install as `quantdb`, import as `qdb` (like scikit-learn → sklearn)\n\n### 🚀 **API Service** - For Enterprises\n```bash\ncurl \"https://your-api.com/api/v1/stocks/000001/data?days=30\"\n```\n**Perfect for**: Enterprise teams, multi-user applications, production systems\n\n### ☁️ **Cloud Platform** - For Individual Investors\nVisit: [QuantDB Cloud Platform](https://quantdb-cloud.streamlit.app)\n**Perfect for**: Individual investors, data analysis, visualization\n\n## ✨ Core Features\n\n- **🚀 90%+ Performance Boost**: Smart SQLite caching, millisecond response time\n- **📦 Multiple Product Forms**: Python package, API service, cloud platform\n- **🔄 Full AKShare Compatibility**: Same API interface, seamless replacement\n- **💾 Local Caching**: Offline available, intelligent incremental updates\n- **📅 Trading Calendar Integration**: Smart data fetching based on real trading days\n- **🛠️ Zero Configuration**: pip install and ready to use\n- **☁️ Cloud Deployment Ready**: Supports Railway, Render, Alibaba Cloud, etc.\n- **🧠 Intelligent Updates**: Automatic missing data detection and fetching\n- **⚡ Real-time Data**: Live stock quotes and market data\n- **📊 Financial Analytics**: Complete financial indicators and ratios\n- **📈 Index Data**: Major market indices support (SSE, SZSE, etc.)\n- **📋 Stock Lists**: Complete market coverage and filtering\n\n## ⚡ Performance Highlights\n\n| Metric | Direct AKShare Call | QuantDB Package | Performance Improvement |\n|--------|-------------------|-------------|------------------------|\n| **Response Time** | ~1000ms | ~10ms | **99%** ⬆️ |\n| **Cache Hit** | N/A | 90%+ | **Smart Cache** ✅ |\n| **Trading Day Recognition** | Manual | Automatic | **Intelligent** 🧠 |\n| **Installation** | Complex setup | `pip install quantdb` | **One Command** 🚀 |\n\n## 📦 Installation \u0026 Import\n\n**Important**: Package name and import name are different (common practice in Python ecosystem)\n\n```bash\n# Install the package\npip install quantdb\n```\n\n```python\n# Import the package (note: import name is 'qdb')\nimport qdb\n\n# Start using immediately\ndf = qdb.get_stock_data(\"000001\", days=30)\nstats = qdb.cache_stats()\n```\n\n**Why different names?**\n- **Package name**: `quantdb` (descriptive, searchable on PyPI)\n- **Import name**: `qdb` (concise, easy to type)\n- **Similar to**: `scikit-learn` → `sklearn`, `beautifulsoup4` → `bs4`\n\n## 🚀 Quick Start\n\n### Option 1: Python Package (Recommended)\n```bash\n# Install the package\npip install quantdb\n\n# Import and use (note the different import name)\npython -c \"\nimport qdb  # Package: quantdb, Import: qdb\ndf = qdb.get_stock_data('000001', days=30)\nprint(f'Got {len(df)} records with 90%+ speed boost!')\nprint('✅ QuantDB package working perfectly!')\n\"\n```\n\n### Option 2: Cloud Platform Access\nDirect access to deployed Streamlit Cloud version:\n- **Frontend Interface**: [QuantDB Cloud](https://quantdb-cloud.streamlit.app)\n- **Complete Features**: Stock data query, asset information, cache monitoring, watchlist management\n\n### Option 3: Local API Service\n\n#### 1. Installation and Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/franksunye/quantdb.git\ncd quantdb\n\n# Install dependencies\npip install -r requirements.txt\n\n# Initialize database\npython src/scripts/init_db.py\n```\n\n#### 2. Start Services\n\n**Method 1: One-click Start (Recommended)**\n```bash\n# Enter frontend directory and run startup script\ncd quantdb_frontend\npython start.py\n# Script will automatically start backend API and frontend interface\n```\n\n**Method 2: Manual Start**\n```bash\n# 1. Start backend API (in project root)\npython src/api/main.py\n\n# 2. Start frontend interface (in new terminal)\ncd quantdb_frontend\nstreamlit run app.py\n\n# Access URLs\n# Frontend Interface: http://localhost:8501\n# API Documentation: http://localhost:8000/docs\n```\n\n**Method 3: Cloud Version Local Run**\n```bash\n# Run Streamlit Cloud version (integrated backend services)\ncd cloud/streamlit_cloud\nstreamlit run app.py\n# Access URL: http://localhost:8501\n```\n\n### 3. Using API\n\n```bash\n# Health check\ncurl http://localhost:8000/api/v1/health\n\n# Get stock data (auto-cached, displays real company names)\ncurl \"http://localhost:8000/api/v1/historical/stock/600000?start_date=20240101\u0026end_date=20240131\"\n\n# Get asset information (includes financial metrics)\ncurl \"http://localhost:8000/api/v1/assets/symbol/600000\"\n\n# View cache status\ncurl http://localhost:8000/api/v1/cache/status\n```\n\n### 4. Run Tests\n\n```bash\n# Run backend tests\npython scripts/test_runner.py --all\n\n# Run frontend tests\ncd quantdb_frontend\npython run_tests.py\n\n# Run performance tests\npython scripts/test_runner.py --performance\n```\n\n## 🤖 For AI Agents\n\nQuantDB is optimized for AI agent integration with comprehensive machine-readable documentation and standardized APIs.\n\n### ✨ AI Agent Features\n- **📋 Standardized Docstrings**: All functions use Google Style format with detailed parameter constraints\n- **🔧 Machine-Readable Schema**: Complete API specification in JSON format\n- **💡 Usage Examples**: Comprehensive examples for financial and index data analysis\n- **⚠️ Error Handling**: Detailed exception documentation with recovery strategies\n- **🎯 Type Safety**: Full type hints for all function parameters and return values\n\n### 🚀 Quick AI Agent Integration\n```python\nimport qdb\n\n# AI agents can access complete documentation\nhelp(qdb.get_stock_data)  # Detailed function documentation\nhelp(qdb.get_financial_summary)  # Financial analysis functions\nhelp(qdb.get_index_data)  # Market index functions\n\n# Example: AI agent can generate this code confidently\ndf = qdb.get_stock_data(\"000001\", days=30)  # Get recent stock data\nsummary = qdb.get_financial_summary(\"000001\")  # Get financial metrics\nrealtime = qdb.get_realtime_data(\"000001\")  # Get current quotes\n```\n\n### 📚 AI Agent Resources\n- **API Schema**: [qdb-ai-agent-schema.json](docs/ai-agent/qdb-ai-agent-schema.json) - Machine-readable API specification\n- **Usage Examples**: [AI Agent Examples](examples/ai_agent_usage_examples.py) - Complete usage patterns\n- **Financial Analysis**: [Financial Examples](examples/financial_and_index_analysis.py) - Advanced analysis workflows\n- **Documentation Guide**: [AI Agent Guide](docs/ai-agent/ai-agent-documentation-guide.md) - Integration best practices\n\n### 🎯 AI Agent Capabilities\nWith QuantDB, AI agents can:\n- ✅ **Understand precise API functionality** with detailed parameter constraints\n- ✅ **Generate correct code** with proper error handling\n- ✅ **Perform advanced financial analysis** with 80+ financial indicators\n- ✅ **Access comprehensive market data** including stocks, indices, and real-time quotes\n- ✅ **Optimize performance** using intelligent caching strategies\n\n### 📊 Supported Analysis Types\n- **Stock Analysis**: Historical data, real-time quotes, technical indicators\n- **Financial Analysis**: Quarterly reports, financial ratios, profitability metrics\n- **Index Analysis**: Market indices, sector performance, trend analysis\n- **Portfolio Management**: Multi-stock analysis, performance comparison\n\n## 🏗️ Architecture Overview\n\nQuantDB adopts modern microservice architecture with the following core components:\n\n- **🔧 Core Services**: Unified business logic layer supporting multiple deployment modes\n- **📡 FastAPI Backend**: High-performance REST API service\n- **📱 Streamlit Frontend**: Interactive data analysis interface\n- **☁️ Cloud Deployment**: Cloud deployment version supporting Streamlit Cloud\n- **🧪 Comprehensive Testing**: Complete test suite covering unit, integration, API, E2E tests\n- **📊 Smart Caching**: Intelligent caching system based on trading calendar\n\nFor detailed architecture design, please refer to [System Architecture Documentation](./docs/10_ARCHITECTURE.md).\n\n## 🔧 Technology Stack\n\n- **Backend**: FastAPI + SQLAlchemy + SQLite\n- **Frontend**: Streamlit + Plotly + Pandas\n- **Data Source**: AKShare (Official Stock Data)\n- **Caching**: Smart database caching + trading calendar\n- **Testing**: pytest + unittest (259 tests, 100% pass rate)\n- **Monitoring**: Real-time performance monitoring and data tracking\n- **Logging**: Unified logging system with completely consistent recording\n- **Integration**: Complete frontend-backend integration solution\n\n## 📚 Documentation\n\n| Document | Description |\n|----------|-------------|\n| [📋 Project Status](./docs/00_BACKLOG.md) | Current progress and priorities |\n| [📅 Changelog](./docs/01_CHANGELOG.md) | Version history and changes |\n| [🏗️ System Architecture](./docs/10_ARCHITECTURE.md) | Architecture design and components |\n| [🗄️ Database Architecture](./docs/11_DATABASE_ARCHITECTURE.md) | Database design and models |\n| [📊 API Documentation](./docs/20_API.md) | Complete API usage guide |\n| [🛠️ Development Guide](./docs/30_DEVELOPMENT.md) | Development environment and workflow |\n| [🧪 Testing Guide](./docs/31_TESTING.md) | Test execution and writing |\n| [📅 Trading Calendar Upgrade](./docs/TRADING_CALENDAR_UPGRADE.md) | Multi-market trading calendar system upgrade |\n| [📖 **DeepWiki Knowledge Base**](https://deepwiki.com/franksunye/quantdb) | Comprehensive knowledge base and documentation |\n\n\n## 💬 Support \u0026 Feedback\n\nWe welcome your feedback and are here to help! Choose the best channel for your needs:\n\n### 🐛 Bug Reports \u0026 Feature Requests\n- **GitHub Issues**: [Report bugs or request features](https://github.com/franksunye/quantdb/issues)\n- Please include version info, error messages, and reproduction steps\n\n### 💭 Community Discussion\n- **GitHub Discussions**: [Join the conversation](https://github.com/franksunye/quantdb/discussions)\n  - [🙏 Q\u0026A](https://github.com/franksunye/quantdb/discussions/categories/q-a) - Get help with usage questions\n  - [💡 Ideas](https://github.com/franksunye/quantdb/discussions/categories/ideas) - Share feature ideas and suggestions\n  - [🙌 Show and Tell](https://github.com/franksunye/quantdb/discussions/categories/show-and-tell) - Share your projects using QuantDB\n  - [📣 Announcements](https://github.com/franksunye/quantdb/discussions/categories/announcements) - Stay updated with latest news\n\n### 📚 Documentation \u0026 Resources\n- **Quick Help**: [FAQ](./docs/faq.md)\n- **Migration Guide**: [AKShare → QuantDB](./docs/guides/migration_akshare_to_quantdb.md)\n- **Full Documentation**: [https://franksunye.github.io/quantdb/](https://franksunye.github.io/quantdb/)\n\n### 🚀 Stay Connected\n- **PyPI Package**: [https://pypi.org/project/quantdb/](https://pypi.org/project/quantdb/)\n- **Live Demo**: [https://quantdb-cloud.streamlit.app/](https://quantdb-cloud.streamlit.app/)\n\n---\n*Response time: We aim to respond to issues within 24-48 hours. For urgent matters, please use GitHub Issues.*\n\n## 🎯 Project Status\n\n**Current Version**: v2.2.8 (Complete Multi-Feature Extension)\n**Next Version**: v2.3.0 (Enhanced Analytics and Performance)\n**MVP Score**: 10/10 (Core features complete, cloud deployment ready)\n**Test Coverage**: 259/259 passed (100%) - 222 backend + 37 frontend\n**Data Quality**: ⭐⭐⭐⭐⭐ (5/5) - Real company names and financial metrics\n**Frontend Experience**: ⭐⭐⭐⭐⭐ (5/5) - Professional quantitative data platform interface\n**Integration Status**: ✅ Complete frontend-backend integration, cloud deployment ready\n**Production Ready**: ⭐⭐⭐⭐⭐ (5/5) - Cloud deployment version complete\n**Cloud Deployment**: ✅ Streamlit Cloud version, directly using backend services\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🔗 Links\n\n- **GitHub**: [https://github.com/franksunye/quantdb](https://github.com/franksunye/quantdb)\n- **API Documentation**: http://localhost:8000/docs (access after starting service)\n- **Project Maintainer**: frank\n\n---\n\n⭐ If this project helps you, please give it a Star!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffranksunye%2Fquantdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffranksunye%2Fquantdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffranksunye%2Fquantdb/lists"}