# https://github.com/OpenBB-finance/OpenBB 项目说明书 生成时间：2026-05-17 18:27:47 UTC ## 目录 - [Introduction to OpenBB Platform](#page-introduction) - [Installation Guide](#page-installation) - [System Architecture](#page-architecture) - [Core Concepts](#page-core-concepts) - [OBBject System](#page-obbject-system) - [Provider Interface](#page-provider-interface) - [Data Providers Overview](#page-providers-overview) - [Developing Custom Providers](#page-provider-development) - [Extensions System](#page-extensions) - [Charting and Visualization](#page-charting) - [Command Line Interface](#page-cli) - [Desktop Application](#page-desktop-app) ## Introduction to OpenBB Platform ### 相关页面 相关主题：[Installation Guide](#page-installation), [System Architecture](#page-architecture)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/README.md) - [openbb_platform/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/README.md) - [cli/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/cli/README.md) - [openbb_platform/extensions/news/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/news/README.md) - [openbb_platform/extensions/commodity/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/commodity/README.md) - [openbb_platform/extensions/economy/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/economy/README.md) - [openbb_platform/extensions/technical/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/technical/README.md) - [openbb_platform/extensions/derivatives/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/derivatives/README.md) - [openbb_platform/extensions/regulators/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/regulators/README.md) - [openbb_platform/extensions/mcp_server/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/mcp_server/README.md) - [openbb_platform/providers/fmp/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/fmp/README.md) - [openbb_platform/providers/government_us/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/government_us/README.md) - [openbb_platform/providers/imf/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/imf/README.md)
# Introduction to OpenBB Platform ## Overview The OpenBB Platform is an open-source data integration foundation for financial data, designed to provide unified access to various financial data sources through a standardized Python interface. It enables developers and analysts to access market data, economic indicators, company fundamentals, and more through a consistent API. 资料来源：[README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/README.md) The platform follows a "connect once, consume everywhere" architecture, allowing seamless integration between different components and enabling data to be consumed across multiple interfaces including Python SDK, REST API, and the OpenBB Workspace enterprise UI. 资料来源：[README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/README.md) ## Architecture The OpenBB Platform consists of several interconnected layers that work together to deliver financial data to end users. ### System Architecture Diagram ```mermaid graph TD A[OpenBB Workspace] <--> B[OpenBB Platform REST API] B <--> C[Core Engine] C <--> D[Extensions] C <--> E[Data Providers] D --> F[Technical Analysis] D --> G[Economy] D --> H[News] D --> I[Commodity] D --> J[Derivatives] D --> K[Regulators] D --> L[MCP Server] E --> M[FMP] E --> N[IMF] E --> O[US Government] ``` ### Key Components | Component | Description | Type | |-----------|-------------|------| | Core Engine | Central processing unit handling requests and data normalization | Core | | Extensions | Domain-specific functionality modules | Plugin | | Providers | Data source integrations (FMP, IMF, Government US, etc.) | Plugin | | REST API | FastAPI-based HTTP interface for programmatic access | Interface | | Python SDK | Native Python interface via `obb` object | Interface | | MCP Server | Model Context Protocol server for AI agent integration | Extension | ## Installation ### Python Package Installation The primary method to install OpenBB Platform is via pip: ```bash pip install openbb ``` After installation, you can immediately start using the platform: ```python from openbb import obb output = obb.equity.price.historical("AAPL") df = output.to_dataframe() ``` 资料来源：[README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/README.md) ### Local Development Setup For local development with source code access, the following requirements must be met: - Git - Python 3.10 - 3.13 - Virtual Environment with `poetry` installed - Local copy of the [GitHub repository](https://github.com/OpenBB-finance/OpenBB.git) To install for local development: 1. Activate your virtual environment 2. Navigate to the `openbb_platform` folder 3. Run `python dev_install.py -e` to install all packages in editable mode 资料来源：[openbb_platform/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/README.md) ## Python SDK Usage ### Basic Usage The OpenBB Platform provides a unified `obb` object for all operations: ```python from openbb import obb # Fetch equity historical data result = obb.equity.price.historical("AAPL", start_date="2023-01-01") df = result.to_dataframe() ``` ### Setting API Keys Many data providers require API keys for authentication: ```python from openbb import obb obb.user.credentials.fred_api_key = "REPLACE_ME" obb.user.credentials.polygon_api_key = "REPLACE_ME" ``` 资料来源：[openbb_platform/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/README.md) ## REST API The OpenBB Platform includes a ready-to-use REST API built with FastAPI. To start the API server: ```bash uvicorn openbb_core.api.rest_api:app --host 0.0.0.0 --port 8000 --reload ``` API documentation is available under `/docs` endpoint. 资料来源：[openbb_platform/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/README.md) ### API Configuration Runtime settings and configurations for the REST API can be adjusted through system settings. See the [official documentation](https://docs.openbb.co/platform/settings/system_settings#api-settings) for detailed configuration options. ## Extensions Ecosystem Extensions provide domain-specific functionality and can be installed independently. Each extension follows the same installation pattern via pip. ### Available Extensions | Extension | Package Name | Description | |-----------|--------------|-------------| | Technical Analysis | `openbb-technical` | Technical analysis tools, indicators, and oscillators | | Economy | `openbb-economy` | Global macroeconomic data access | | News | `openbb-news` | News data integration | | Commodity | `openbb-commodity` | Commodity-related data and commands | | Derivatives | `openbb-derivatives` | Derivatives market data | | Regulators | `openbb-regulators` | Data from global market regulators | | MCP Server | `openbb-mcp-server` | Model Context Protocol server for AI agents | ### Extension Installation Install any extension using pip: ```bash pip install openbb-technical pip install openbb-economy pip install openbb-news ``` 资料来源：[openbb_platform/extensions/technical/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/technical/README.md), [openbb_platform/extensions/economy/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/economy/README.md), [openbb_platform/extensions/news/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/news/README.md) ### MCP Server Extension The MCP (Model Context Protocol) Server extension allows OpenBB Platform routes to be exposed as tools for AI agents. It supports inline MCP configuration for granular control: ```python from openbb_mcp_server.models.mcp_config import MCPConfigModel ``` Configuration properties include: - **`expose`** (`Optional[bool]`): Hide/show routes from MCP server - **`mcp_type`** (`Optional[MCPType]`): Classify as `"tool"`, `"resource"`, or `"resource_template"` - **`methods`** (`Optional[list[HTTPMethod]]`): Specify HTTP methods to expose 资料来源：[openbb_platform/extensions/mcp_server/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/mcp_server/README.md) ## Data Providers Providers are integrations that connect to external data sources. They can be installed as separate packages. ### Provider Installation Providers are installed via pip and then registered with the platform: ```bash pip install openbb-fmp pip install openbb-imf pip install openbb-us-government ``` After installation, rebuild Python static assets: ```bash openbb-build ``` 资料来源：[openbb_platform/providers/fmp/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/fmp/README.md), [openbb_platform/providers/imf/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/imf/README.md) ### Official Providers | Provider | Package | Description | |----------|---------|-------------| | Financial Modeling Prep | `openbb-fmp` | Company fundamentals, stock data, financial statements | | IMF | `openbb-imf` | International Monetary Fund data via SDMX API | | US Government | `openbb-us-government` | US Government data from data.gov | ### US Government Provider Coverage The US Government provider covers: - `obb.commodity.psd_report` - `obb.commodity.psd_data` - `obb.commodity.weather_bulletins` - `obb.fixed_income.government.treasury_auctions` - `obb.fixed_income.government.treasury_prices` All covered services require no registration. 资料来源：[openbb_platform/providers/government_us/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/government_us/README.md) ### IMF Provider Implementation The IMF provider uses SDMX API to access dataflows. Key implementation details: - User input validation via constraints API for each dimension - Cached metadata contains all potential parameter values - Network requests made when code lists are not included in cache 资料来源：[openbb_platform/providers/imf/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/imf/README.md) ## Integration with OpenBB Workspace OpenBB Workspace is an enterprise UI that complements the open-source data platform. The platform's architecture enables seamless integration between the two components. ### Data Flow ```mermaid graph LR A[OpenBB Platform] -->|Custom Backend| B[OpenBB Workspace] B -->|Visualization| C[Analyst Dashboard] A -->|REST API| D[Third-party Applications] ``` ### Connecting Platform to Workspace 1. Start the API server with `openbb-api` (starts FastAPI on localhost port 6900) 2. Add the server to OpenBB Workspace 3. Access widgets and data exploration tools through the dashboard 资料来源：[openbb_platform/providers/imf/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/imf/README.md) ## CLI Integration The OpenBB Platform can be accessed via the command-line interface: ```bash pip install openbb-cli openbb ``` 资料来源：[cli/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/cli/README.md) ## Development with Cookiecutter For developers creating new extensions or providers, the OpenBB Cookiecutter template provides a standardized project structure: ```bash pip install openbb-cookiecutter openbb-cookiecutter ``` Development workflow: 1. Generate project from template 2. Create Python environment for the project 3. Install with `pip install -e .` 4. Trigger static file generation with `openbb-build` 5. Import package or start API 资料来源：[cookiecutter/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/cookiecutter/README.md) ## Getting Help and Contributing ### Documentation Complete documentation is available at [https://docs.openbb.co](https://docs.openbb.co): - [Platform Documentation](https://docs.openbb.co/platform) - [API Reference](https://docs.openbb.co/python/reference) - [Developer Guide](https://docs.openbb.co/platform/developer_guide/contributing) ### Community and Support | Channel | Link | |---------|------| | Discord | [openbb.co/discord](https://openbb.co/discord) | | GitHub Issues | [GitHub Issues](https://github.com/OpenBB-finance/OpenBB/issues) | | Social Media | [openbb.co/links](https://openbb.co/links) | ### Issue Templates - [Bug Report](https://github.com/OpenBB-finance/OpenBB/issues/new?assignees=&labels=bug&template=bug_report.md) - [Improvement Suggestion](https://github.com/OpenBB-finance/OpenBB/issues/new?assignees=&labels=enhancement&template=enhancement.md) - [Feature Request](https://github.com/OpenBB-finance/OpenBB/issues/new?assignees=&labels=new+feature&template=feature_request.md) ## License and Disclaimer The OpenBB Platform is distributed under the **AGPLv3 License**. **Disclaimer**: Trading in financial instruments involves high risks including the risk of losing some, or all, of your investment amount. The data contained in the Open Data Platform is not necessarily accurate. OpenBB and any provider of data will not accept liability for any loss or damage as a result of trading or reliance on the information displayed. 资料来源：[README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/README.md) --- ## Installation Guide ### 相关页面 相关主题：[Introduction to OpenBB Platform](#page-introduction), [Command Line Interface](#page-cli)
相关源码文件 以下源码文件用于生成本页说明： - [openbb_platform/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/README.md) - [cli/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/cli/README.md) - [openbb_platform/extensions/news/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/news/README.md) - [openbb_platform/extensions/commodity/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/commodity/README.md) - [openbb_platform/extensions/mcp_server/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/mcp_server/README.md) - [cookiecutter/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/cookiecutter/README.md) - [openbb_platform/providers/cftc/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/cftc/README.md) - [openbb_platform/providers/multpl/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/multpl/README.md)
# Installation Guide This guide provides comprehensive instructions for installing and configuring the OpenBB Platform ecosystem. The installation process supports multiple deployment methods including the Python Package (ODP), CLI interface, Platform extensions, and provider integrations. ## Overview The OpenBB Platform consists of several interconnected components that can be installed independently or together. The architecture supports modular installation, allowing users to install only the components they need for their specific use case. ```mermaid graph TD A[OpenBB Platform Core] --> B[CLI Interface] A --> C[Python API] A --> D[Extensions] A --> E[Providers] D --> D1[News Extension] D --> D2[Commodity Extension] D --> D3[MCP Server] E --> E1[CFTC Provider] E --> E2[Multpl Provider] E --> E3[Congress Gov Provider] ``` ## Python Package Installation The OpenBB Platform Python Package (ODP) serves as the core installation method for all components. ### Standard Installation via PyPI The recommended method for installing the OpenBB Platform is through PyPI using pip: ```bash pip install openbb ``` 资料来源：[README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/README.md) ### Platform Installation The Platform package includes the core libraries and dependencies required for data analysis and financial computations. After installation, the Platform can be accessed programmatically: ```python from openbb import obb # Example: Fetch S&P 500 multiples data data = obb.index.sp500_multiples() ``` 资料来源：[openbb_platform/providers/multpl/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/multpl/README.md) ## CLI Installation The OpenBB CLI provides a command-line interface for interacting with the Platform. ### Installation via PyPI ```bash pip install openbb-cli ``` 资料来源：[cli/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/cli/pyproject.toml) ### Deployment After installation, deploy the OpenBB Platform CLI by running: ```bash openbb ``` 资料来源：[cli/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/cli/README.md) ### Installation Verification A successful installation produces the following output: ![OpenBB CLI Interface](https://github.com/OpenBB-finance/OpenBB/assets/48914296/f606bb6e-fa00-4fc8-bad2-8269bb4fc38e) ## Extension Installation Extensions extend the core Platform functionality with specialized features. Each extension is distributed as a separate Python package installable via pip. ### News Extension The News Extension provides news aggregation capabilities for the OpenBB Platform. ```bash pip install openbb-news ``` 资料来源：[openbb_platform/extensions/news/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/news/README.md) ### Commodity Extension The Commodity Extension provides commands for commodity-related financial data. ```bash pip install openbb-commodity ``` 资料来源：[openbb_platform/extensions/commodity/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/commodity/README.md) ### MCP Server Extension The MCP Server Extension exposes OpenBB Platform endpoints as Model Context Protocol (MCP) tools, enabling AI assistant integration. ```bash pip install openbb-mcp-server ``` 资料来源：[openbb_platform/extensions/mcp_server/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/mcp_server/README.md) ### Extension Configuration via MCP The MCP Server extension supports inline configuration using the `MCPConfigModel`: ```python from openbb_mcp_server.models.mcp_config import MCPConfigModel ``` The configuration supports the following properties: | Property | Type | Description | |----------|------|-------------| | `expose` | `Optional[bool]` | Set to `False` to hide a route from the MCP server | | `mcp_type` | `Optional[MCPType]` | Classify as `"tool"`, `"resource"`, or `"resource_template"` | | `methods` | `Optional[list[HTTPMethod]]` | Specify HTTP methods to expose | 资料来源：[openbb_platform/extensions/mcp_server/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/mcp_server/README.md) ## Provider Installation Providers are data source integrations that supply financial and economic data to the Platform. ### Available Providers | Provider | Package | Command | |----------|---------|---------| | CFTC | openbb-cftc | `pip install openbb-cftc` | | Multpl | openbb-multpl | `pip install openbb-multpl` | | Congress Gov | openbb-congress-gov | Included in Platform core | 资料来源：[openbb_platform/providers/cftc/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/cftc/README.md) ### CFTC Provider Usage The CFTC provider provides Commitments of Traders (COT) data: ```python from openbb import obb # Search for commodities search_results = obb.cftc.cot_search(query="gold") print(search_results.to_df()) # Fetch specific report report = obb.cftc.cot(code="CFTC_088695", measure="percent_of_oi", limit=4) print(report.to_df().T) ``` 资料来源：[openbb_platform/providers/cftc/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/cftc/README.md) ### Multpl Provider Usage The Multpl provider provides S&P 500 data: ```python from openbb import obb data = obb.index.sp500_multiples() ``` 资料来源：[openbb_platform/providers/multpl/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/multpl/README.md) ### Congress Gov Provider Usage The Congress Gov provider provides US Congressional data: ```python from openbb import obb # Get recent bills bills = obb.uscongress.bills(limit=10) # Get bill details bill_info = obb.uscongress.bill_info(bill_url="119/hr/1") ``` 资料来源：[openbb_platform/providers/congress_gov/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/congress_gov/README.md) ## REST API Deployment The Platform can be deployed as a REST API for remote access and integration with other applications. ### Starting the API Server ```bash openbb-api ``` This starts the server over localhost, making the Platform accessible via HTTP endpoints. 资料来源：[openbb_platform/providers/cftc/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/cftc/README.md) ### Platform Connection To connect to the Platform from external applications: 1. Navigate to the "Apps" tab 2. Click on "Connect backend" 3. Fill in the connection form: - **Name:** Open Data Platform - **URL:** `http://127.0.0.1:6900` 4. Click "Test" to verify connectivity 5. Click "Add" to complete the connection 资料来源：[README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/README.md) ## Development Environment Setup For developers contributing to the OpenBB Platform, a cookiecutter template is available to scaffold new extensions and providers. ### Cookiecutter Template 1. Install the cookiecutter template: ```bash pip install openbb-cookiecutter ``` 2. Navigate to the desired output location and run: ```bash openbb-cookiecutter ``` 3. Create a new Python environment for the project. 4. Install the generated package: ```bash pip install -e . ``` 5. Generate Python static files: ```bash openbb-build ``` 6. Import the package or start the API. 资料来源：[cookiecutter/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/cookiecutter/README.md) ## Installation Workflow ```mermaid graph TD A[Start Installation] --> B{Select Installation Type} B -->|Python Package| C[pip install openbb] B -->|CLI| D[pip install openbb-cli] B -->|Extensions| E[Select Required Extensions] B -->|Providers| F[Select Required Providers] E --> G[pip install openbb-{extension}] F --> H[pip install openbb-{provider}] C --> I{Additional Components?} D --> I G --> J[Verify Installation] H --> J I -->|Yes| E I -->|No| J J --> K[Configure Environment] K --> L[Start Using OpenBB] ``` ## Installation Sources Reference | Component | Installation Source | Documentation | |-----------|---------------------|---------------| | Core Platform | PyPI (`pip install openbb`) | [docs.openbb.co](https://docs.openbb.co/python/installation) | | CLI | PyPI (`pip install openbb-cli`) | [docs.openbb.co/cli](https://docs.openbb.co/cli/installation) | | Platform Extensions | Individual PyPI packages | [docs.openbb.co/platform](https://docs.openbb.co/platform/developer_guide/contributing) | | Cookiecutter | PyPI (`pip install openbb-cookiecutter`) | [docs.openbb.co/python/developer](https://docs.openbb.co/python/developer) | ## Troubleshooting ### Common Installation Issues 1. **Dependency Conflicts**: Ensure Python 3.8+ is installed and consider using a virtual environment 2. **Permission Errors**: Use `--user` flag or virtual environments to avoid system-wide installations 3. **Network Issues**: Verify PyPI connectivity and consider using mirrors if necessary ### Verification Steps After installation, verify the setup by importing the core module: ```bash python -c "from openbb import obb; print(obb)" ``` For CLI verification: ```bash openbb --version ``` ## Additional Resources - **User Documentation**: [docs.openbb.co](https://docs.openbb.co) - **Developer Documentation**: [docs.openbb.co/python/developer](https://docs.openbb.co/python/developer) - **Platform Developer Guide**: [docs.openbb.co/platform/developer_guide/contributing](https://docs.openbb.co/platform/developer_guide/contributing) - **Support**: support@openbb.co - **General Inquiries**: hello@openbb.co --- ## System Architecture ### 相关页面 相关主题：[Core Concepts](#page-core-concepts), [OBBject System](#page-obbject-system)
相关源码文件 以下源码文件用于生成本页说明： - [openbb_platform/core/openbb_core/api/rest_api.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/api/rest_api.py) - [openbb_platform/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/README.md) - [openbb_platform/providers/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/README.md) - [openbb_platform/extensions/platform_api/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/platform_api/README.md) - [openbb_platform/extensions/mcp_server/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/mcp_server/README.md) - [cli/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/cli/README.md) - [desktop/src/routes/installation-progress.tsx](https://github.com/OpenBB-finance/OpenBB/blob/main/desktop/src/routes/installation-progress.tsx) - [desktop/src/routes/backends.tsx](https://github.com/OpenBB-finance/OpenBB/blob/main/desktop/src/routes/backends.tsx) - [desktop/src-tauri/src/tauri_handlers/credentials.rs](https://github.com/OpenBB-finance/OpenBB/blob/main/desktop/src-tauri/src/tauri_handlers/credentials.rs)
# System Architecture ## Overview The OpenBB Platform is a modular, extensible investment research platform designed to provide financial data and analytics through multiple interfaces. The system architecture follows a plugin-based design pattern that separates core functionality from data providers and interface implementations. 资料来源：[openbb_platform/README.md]() ## High-Level Architecture The OpenBB Platform consists of three primary deployment targets: | Layer | Component | Description | |-------|-----------|-------------| | **Core** | Platform Core | Shared libraries, data models, provider registry, and query execution engine | | **Interface** | CLI | Terminal-based interactive interface | | **Interface** | Desktop | Cross-platform desktop application (Tauri-based) | | **Interface** | REST API | FastAPI-based HTTP API server | | **Extension** | MCP Server | Model Context Protocol integration for AI tooling | | **Extension** | Platform API | Widgets and workspace applications | 资料来源：[cli/README.md](), [openbb_platform/README.md]() ## Architecture Diagram ```mermaid graph TD subgraph "Interface Layer" CLI[CLI
openbb command] DESKTOP[Desktop App
Tauri + React] API[REST API
FastAPI] end subgraph "Extension Layer" MCP[MCP Server
Model Context Protocol] PLATFORM_API[Platform API
Widgets & Apps] end subgraph "Core Layer" APP[App Module
openbb_core.app] REGISTRY[Provider Registry] EXECUTOR[Query Executor] end subgraph "Provider Layer" GOV_US[Government US Provider] CFTC[CFTC Provider] MULTPL[Multpl Provider] NEWS[News Extension] COMMODITY[Commodity Extension] CUSTOM[Custom Providers] end CLI --> APP DESKTOP --> APP API --> APP MCP --> APP PLATFORM_API --> APP APP --> REGISTRY APP --> EXECUTOR REGISTRY --> GOV_US REGISTRY --> CFTC REGISTRY --> MULTPL REGISTRY --> NEWS REGISTRY --> COMMODITY REGISTRY --> CUSTOM EXECUTOR --> REGISTRY ``` ## Component Details ### Platform Core The core module (`openbb_core`) contains the fundamental infrastructure for the entire platform: - **Data Models**: Standardized schemas for financial data - **Provider Registry**: Dynamic registration and discovery of data providers - **Query Executor**: Handles request routing and execution across providers - **Authentication**: API key management and credential handling 资料来源：[openbb_platform/README.md](), [openbb_platform/providers/README.md]() ### Provider System The provider architecture allows data sources to be implemented as pluggable extensions. Each provider follows a standardized structure: ``` openbb_platform/providers// ├── README.md ├── pyproject.toml ├── poetry.lock ├── tests/ └── openbb_/ ├── __init__.py ├── models/ │ └── .py └── utils/ └── .py ``` 资料来源：[openbb_platform/providers/README.md]() #### Supported Provider Categories | Category | Examples | Functionality | |----------|----------|---------------| | Government Data | `obb.fixed_income.government.treasury_auctions` | US Treasury and regulatory data | | Commodity | `obb.commodity.psd_report`, `obb.commodity.weather_bulletins` | Commodity market data | | Futures/COT | `obb.cftc.cot`, `obb.cftc.cot_search` | CFTC Commitments of Traders | | Market Indices | `obb.index.sp500_multiples` | Index and market multiples | | News | News Extension | Financial news aggregation | | Regulatory | Regulators Extension | Global market regulator data | 资料来源：[openbb_platform/providers/government_us/README.md](), [openbb_platform/providers/cftc/README.md](), [openbb_platform/providers/multpl/README.md]() ### REST API Architecture The FastAPI-based REST API provides programmatic access to all platform functionality: ```python app = FastAPI( title=system.api_settings.title, description=system.api_settings.description, version=system.api_settings.version, servers=[ {"url": s.url, "description": s.description} for s in system.api_settings.servers ], ) app.add_middleware( CORSMiddleware, allow_origins=system.api_settings.cors.allow_origins, allow_methods=system.api_settings.cors.allow_methods, allow_headers=system.api_settings.cors.allow_headers, ) ``` 资料来源：[openbb_platform/core/openbb_core/api/rest_api.py:38-70]() #### API Configuration Options The REST API supports configurable settings including: - `title`: API title - `description`: API description - `version`: API version - `terms_of_service`: Terms of service URL - `contact`: Contact information (name, URL, email) - `license_info`: License details (name, URL) - `servers`: Server configurations with URLs and descriptions - `cors`: Cross-Origin Resource Sharing settings Start the API server with: ```bash uvicorn openbb_core.api.rest_api:app --host 0.0.0.0 --port 8000 --reload ``` 资料来源：[openbb_platform/core/openbb_core/api/rest_api.py](), [openbb_platform/README.md]() ### MCP Server Extension The Model Context Protocol (MCP) server integration exposes OpenBB functionality as tools for AI assistants: ```json { "description": "Generate a brief summary of GDP for a country.", "messages": [ { "role": "user", "content": { "type": "text", "text": "Use the tool, economy_gdp, to perform the following task.\n\nProvide a concise summary of the GDP for Japan over the last 10 years." } } ] } ``` #### MCP Configuration Options | Property | Type | Description | |----------|------|-------------| | `expose` | `Optional[bool]` | Set to `False` to hide a route from MCP server | | `mcp_type` | `Optional[MCPType]` | Classify as `"tool"`, `"resource"`, or `"resource_template"` | | `methods` | `Optional[list[HTTPMethod]]` | Specify HTTP methods to expose | 资料来源：[openbb_platform/extensions/mcp_server/README.md]() ### Desktop Application Architecture The desktop application uses Tauri (Rust backend) with React frontend: ```mermaid graph LR subgraph "Desktop Frontend" UI[React Components] ROUTES[Routes: installation-progress, backends, api-keys, environments] end subgraph "Tauri Backend" HANDLERS[Tauri Handlers] CREDENTIALS[Credentials Handler] end UI --> HANDLERS HANDLERS --> CREDENTIALS ``` #### Desktop Installation Flow The desktop application manages installation through phases: 1. **Miniforge Setup**: Python environment manager installation 2. **Core Libraries**: OpenBB environment with dependencies 3. **Extensions**: User-selected extensions and PyPI packages 资料来源：[desktop/src/routes/installation-progress.tsx](), [desktop/src/routes/backends.tsx]() #### Credential Management The desktop application handles credential storage through platform-specific editors: | Platform | Editor | Configuration | |----------|--------|---------------| | Windows | Notepad | `.env`, `.condarc`, etc. | | macOS | TextEdit | Basic text editing | | Linux | gedit/kate/leafpad/mousepad/xed | Multiple fallback editors | 资料来源：[desktop/src-tauri/src/tauri_handlers/credentials.rs]() ### Platform API Extension The Platform API extension provides widget management and workspace functionality: | File | Default Location | Purpose | |------|------------------|---------| | `widgets.json` | `~/OpenBBUserData/widgets.json` | Widget configuration | | `workspace_apps.json` | `~/OpenBBUserData/workspace_apps.json` | Custom workspace apps | Configuration options: - `--editable`: Enable live editing without rebuild - `--no-build`: Serve file directly without build process - `--widgets-json`: Custom widgets file path - `--apps-json`: Custom apps file path 资料来源：[openbb_platform/extensions/platform_api/README.md]() ## Deployment Workflow ```mermaid graph TD A[User Installation] --> B{M Installation Target} B -->|CLI| C[pip install openbb-cli] B -->|Desktop| D[Download Desktop App] B -->|Platform| E[pip install openbb-platform] B -->|Extension| F[pip install openbb-] C --> G[openbb command] D --> H[Tauri Desktop App] E --> I[REST API Server] F --> J[Add-on Functionality] G --> K[Python Runtime + Providers] H --> K I --> K J --> K K --> L[Data Providers] ``` 资料来源：[cli/README.md](), [openbb_platform/README.md](), [openbb_platform/extensions/news/README.md](), [openbb_platform/extensions/commodity/README.md]() ## Local Development Setup For local development, the platform uses Poetry for dependency management: ```bash # 1. Clone repository git clone https://github.com/OpenBB-finance/OpenBB.git # 2. Navigate to platform directory cd openbb_platform # 3. Install in editable mode python dev_install.py -e ``` Requirements: - Git - Python 3.10 - 3.13 - Virtual Environment with Poetry installed 资料来源：[openbb_platform/README.md]() ## Security Architecture ### API Key Management API keys are managed through the `obb.user.credentials` interface: ```python from openbb import obb obb.user.credentials.fred_api_key = "REPLACE_ME" obb.user.credentials.polygon_api_key = "REPLACE_ME" ``` ### File-Based Credential Storage | File | Format | Purpose | |------|--------|---------| | `.env` | Environment variables | API keys and secrets | | `.condarc` | YAML | Conda configuration | | `config.py` | Python | User preferences | The desktop application provides UI for importing/exporting credentials as JSON or `.env` files. 资料来源：[openbb_platform/README.md](), [desktop/src/routes/api-keys.tsx]() ## Extension Discovery The OpenBB Hub provides a centralized location for discovering extensions: ```bash # Browse available extensions # https://my.openbb.co/app/platform/extensions ``` Available extension types: - Data Providers (e.g., `openbb-us-government`, `openbb-multpl`) - Data Services (e.g., `openbb-news`, `openbb-commodity`) - Integration Adapters (e.g., `openbb-mcp-server`, `openbb-regulators`) 资料来源：[cli/README.md](), [openbb_platform/providers/government_us/README.md](), [openbb_platform/providers/multpl/README.md]() ## Conclusion The OpenBB Platform architecture emphasizes modularity, extensibility, and multi-interface support. The core layer handles data abstraction and provider management, while the interface layer provides diverse ways to interact with the platform. The extension system enables third-party contributions while maintaining consistency across the ecosystem. --- ## Core Concepts ### 相关页面 相关主题：[System Architecture](#page-architecture), [OBBject System](#page-obbject-system), [Provider Interface](#page-provider-interface)
相关源码文件 以下源码文件用于生成本页说明： - [openbb_platform/core/openbb_core/app/model/obbject.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/app/model/obbject.py) - [openbb_platform/core/openbb_core/provider/abstract/provider.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/provider/abstract/provider.py) - [openbb_platform/core/openbb_core/provider/abstract/fetcher.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/provider/abstract/fetcher.py) - [openbb_platform/core/openbb_core/provider/abstract/data.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/provider/abstract/data.py) - [openbb_platform/providers/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/README.md) - [openbb_platform/extensions/news/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/news/README.md)
# Core Concepts The OpenBB Platform is a modular financial data infrastructure designed to provide unified access to diverse financial data sources. Built on Python with a FastAPI REST API layer, the platform abstracts data provider complexity behind a consistent interface, enabling developers and analysts to access market data, economic indicators, and financial analytics through a standardized workflow. This page documents the fundamental architectural concepts that underpin the OpenBB Platform, including the OBBject data model, the provider abstraction system, the fetcher pattern, and the extension mechanism. --- ## Architecture Overview The OpenBB Platform follows a layered architecture that separates concerns between data sources, data processing, and API delivery. At its core, the platform uses an abstraction layer that allows multiple data providers to be integrated without affecting the consumer API. ```mermaid graph TD subgraph "Client Layer" CLI[OpenBB CLI] REST[REST API] PY[Python SDK] end subgraph "Core Platform" ROUTER[Router / API Routes] OBB[OBBject Model] HUB[Extension Hub] end subgraph "Provider Abstraction" PROVIDER[Provider Base Class] FETCHER[Fetcher Abstract] DATA[Data Models] end subgraph "Providers" FRED[FRED Provider] POLYGON[Polygon Provider] FINVIZ[Finviz Provider] CFTC[CFTC Provider] CUSTOM[Custom Providers] end CLI --> ROUTER REST --> ROUTER PY --> OBB ROUTER --> OBB OBB --> PROVIDER PROVIDER --> FETCHER FETCHER --> DATA PROVIDER --> FRED PROVIDER --> POLYGON PROVIDER --> FINVIZ PROVIDER --> CFTC PROVIDER --> CUSTOM ``` 资料来源：[openbb_platform/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/README.md) --- ## OBBject Model The OBBject is the fundamental data container in the OpenBB Platform. Every data response returned by the platform is encapsulated within an OBBject, providing a consistent interface for accessing results, metadata, and utility methods. ### Purpose and Scope The OBBject serves multiple roles within the platform: - **Data Container**: Holds the actual results from data providers in a structured format - **Metadata Carrier**: Includes provider information, warnings, and pagination details - **Serialization Interface**: Supports conversion to various formats (DataFrame, CSV, JSON) - **Chainable Results**: Enables method chaining for data transformation 资料来源：[openbb_platform/core/openbb_core/app/model/obbject.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/app/model/obbject.py) ### OBBject Structure | Component | Type | Description | |-----------|------|-------------| | `results` | Any | The primary data returned by the query | | `provider` | str | Name of the data provider that supplied the data | | `params` | dict | Parameters used in the original request | | `metadata` | dict | Additional context about the response | | `warnings` | list | Any warnings generated during retrieval | | `chart` | object | Optional charting configuration | ### Usage Pattern ```python from openbb import obb # Standard query returning an OBBject result = obb.equity.price.historical(symbol="AAPL", provider="polygon") # Access results print(result.results) # Convert to DataFrame df = result.to_df() # Access metadata print(result.provider) print(result.params) ``` --- ## Provider System The provider system is the abstraction layer that enables the OpenBB Platform to integrate multiple data sources through a unified interface. Each provider implements a common interface while handling the specifics of its underlying data source. ### Provider Architecture ```mermaid classDiagram class Provider { <> +name: str +website: str +description: str +credentials: dict +repositories: list +models: dict +router: APIRouter +fetch_standard_data() +fetch_data() } class Model { <> +provider: Provider +name: str +query_params: BaseModel +data: BaseModel +transform() } Provider --> Model : contains class PolygonProvider { +name = "polygon" +credentials: [api_key] } class FREDProvider { +name = "fred" +credentials: [api_key] } class FinvizProvider { +name = "finviz" } PolygonProvider --|> Provider FREDProvider --|> Provider FinvizProvider --|> Provider ``` 资料来源：[openbb_platform/core/openbb_core/provider/abstract/provider.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/provider/abstract/provider.py) ### Provider Directory Structure Each provider follows a standardized directory structure: ``` openbb_platform └───providers └─── ├── README.md ├── pyproject.toml ├── poetry.lock ├── tests/ └── openbb_ ├── __init__.py ├── models/ │ ├── .py │ └── ... └── utils/ ├── .py └── ... ``` 资料来源：[openbb_platform/providers/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/README.md) ### Available Provider Categories | Category | Description | Example Endpoints | |----------|-------------|-------------------| | Market Data | Real-time and historical market prices | `obb.equity.price.historical` | | Economic | Economic indicators and datasets | `obb.economy.gdp`, `obb.economy.cpi` | | Government | US government financial data | `obb.fixed_income.government.treasury_auctions` | | Commodities | Commodity market data | `obb.commodity.psd_report` | | News | Financial news aggregation | News extension endpoints | | Technical | Technical analysis indicators | `obb.technical.indicators` | --- ## Fetcher Pattern The fetcher is the abstraction responsible for executing data retrieval requests against a specific provider. Fetchers handle the transformation of query parameters into API calls and normalize the response into the platform's standard data models. ### Fetcher Lifecycle ```mermaid sequenceDiagram participant Client as Client Request participant Fetcher as Fetcher participant Provider as Provider API participant Model as Data Model Client->>Fetcher: Execute query with parameters Fetcher->>Provider: Build and send API request Provider-->>Fetcher: Raw response data Fetcher->>Model: Parse and validate response Model-->>Fetcher: Normalized data object Fetcher-->>Client: OBBject with results ``` 资料来源：[openbb_platform/core/openbb_core/provider/abstract/fetcher.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/provider/abstract/fetcher.py) ### Fetcher Configuration | Parameter | Type | Description | |-----------|------|-------------| | `definitions` | dict | Mapping of endpoint names to definitions | | `credentials` | Credentials | Provider authentication credentials | | `param_fields` | list | Fields to include in query parameters | | `data_fields` | list | Fields to include in response data | | `optional_params` | list | Parameters that are optional | | `requires_credential` | list | Credentials required for this fetcher | ### Implementation Pattern Fetchers typically implement the following method signature: ```python def fetch_data( query: QueryParams, credentials: Credentials, **kwargs ) -> OBBject: """ Fetch data from the provider and return an OBBject. Args: query: Query parameters from the user request credentials: Provider credentials Returns: OBBject: The normalized response data """ ``` --- ## Data Models Data models in the OpenBB Platform define the structure of both request parameters and response data. They use Pydantic for validation and serialization, ensuring type safety throughout the platform. ### Data Model Hierarchy ```mermaid graph TD subgraph "Data Models" QUERY[QueryParams Model] RESPONSE[Response Model] FIELD[Field Definitions] end QUERY -->|validates| REQUEST[Incoming Request] RESPONSE -->|defines| RESULTS[Query Results] FIELD -->|composes| QUERY FIELD -->|composes| RESPONSE ``` 资料来源：[openbb_platform/core/openbb_core/provider/abstract/data.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/provider/abstract/data.py) ### Model Fields Configuration | Field Property | Type | Purpose | |---------------|------|---------| | `description` | str | Human-readable field description | | `alias` | str | Alternative name for the field | | `default` | Any | Default value if not provided | | `ge` / `le` | int | Greater than or less than constraints | | `pattern` | str | Regex pattern for validation | | `deprecated` | bool | Mark field as deprecated | ### Example Data Model ```python from openbb_core.provider.abstract.data import Data from pydantic import Field class HistoricalData(Data): date: str = Field(description="Date of the data point") open: float = Field(description="Opening price") high: float = Field(description="High price") low: float = Field(description="Low price") close: float = Field(description="Closing price") volume: int = Field(description="Trading volume") ``` --- ## Extension System The extension system allows the OpenBB Platform to be extended with additional functionality through modular packages. Extensions can add new endpoints, data sources, and features without modifying the core platform. ### Extension Types | Extension Type | Purpose | Example | |---------------|---------|---------| | Provider | Add new data source integration | `openbb-fred`, `openbb-finviz` | | Feature | Add new analytical capabilities | `openbb-technical` | | Utility | Add helper functions and tools | `openbb-mcp-server` | | UI | Add dashboard widgets and apps | Workspace custom apps | ### Extension Installation Extensions are installed as Python packages and automatically discovered by the platform: ```bash pip install openbb-news pip install openbb-commodity pip install openbb-technical pip install openbb-regulators ``` 资料来源：[openbb_platform/extensions/news/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/news/README.md) ### Extension Discovery Flow ```mermaid graph LR A[Platform Startup] --> B[Scan Extensions Directory] B --> C{Found Extension?} C -->|Yes| D[Load Extension Package] C -->|No| E[Continue] D --> F[Register Routes] F --> G[Register Providers] G --> H[Extension Available] E --> H ``` --- ## API Access Patterns ### REST API The OpenBB Platform includes a FastAPI-based REST API for programmatic access: ```bash uvicorn openbb_core.api.rest_api:app --host 0.0.0.0 --port 8000 --reload ``` API documentation is available at `/docs` endpoint when the server is running. 资料来源：[openbb_platform/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/README.md) ### Python SDK The Python SDK provides the most direct access to platform functionality: ```python from openbb import obb # Set credentials obb.user.credentials.fred_api_key = "REPLACE_ME" obb.user.credentials.polygon_api_key = "REPLACE_ME" # Query data result = obb.equity.price.historical(symbol="AAPL", provider="polygon") ``` ### CLI Access The command-line interface offers interactive access: ```bash openbb ``` --- ## Provider-Specific Endpoints ### CFTC Provider The Commodity Futures Trading Commission (CFTC) provider offers Commitments of Traders data: | Endpoint | Description | |----------|-------------| | `obb.cftc.cot` | Get Commitments of Traders report | | `obb.cftc.cot_search` | Search CFTC contract codes | ```python from openbb import obb search_results = obb.cftc.cot_search(query="gold") report = obb.cftc.cot(code="CFTC_088695", measure="percent_of_oi", limit=4) ``` ### Congress Provider The US Congress provider provides legislative tracking: | Endpoint | Description | |----------|-------------| | `obb.uscongress.bills` | Get recent bills | | `obb.uscongress.bill_info` | Get detailed bill information | ### Government US Provider Government data endpoints include: | Endpoint | Description | |----------|-------------| | `obb.commodity.psd_report` | PSD commodity reports | | `obb.commodity.psd_data` | PSD data tables | | `obb.fixed_income.government.treasury_auctions` | Treasury auction data | --- ## Next Steps - Review the [Installation Guide](../installation.md) for setting up the platform - Explore the [Provider Documentation](../providers/) for available data sources - Learn about [Extension Development](../developer_guide/contributing.md) to create custom extensions - Consult the [API Reference](../reference/) for detailed endpoint documentation --- ## OBBject System ### 相关页面 相关主题：[Core Concepts](#page-core-concepts), [Charting and Visualization](#page-charting) # OBBject System > **Note:** This wiki page is based on available documentation and README files in the repository. The core implementation files for the OBBject system (`openbb_platform/core/openbb_core/app/model/obbject.py`, `openbb_platform/core/openbb_core/app/model/abstract/results.py`, and `openbb_platform/core/integration/test_obbject.py`) were not available in the provided context for detailed analysis. The information below reflects the system's role and usage as observed across the platform. ## Overview The OBBject system is the core data structure framework within the OpenBB Platform that handles standardized return types from all data provider queries. Every function endpoint in the platform returns an OBBject, ensuring consistent response handling across the entire system. ## Architecture The OBBject serves as the universal wrapper for all platform outputs, providing: - **Standardized data formats** across all providers - **Metadata attachment** for query context - **Flexible conversion methods** between different data representations - **Results abstraction** through inheritance from `AbstractResults` ## Data Flow ```mermaid graph TD A[User Query via obb] --> B[OpenBB Core] B --> C[Provider Function Call] C --> D[Data Provider API] D --> E[Provider Response Parser] E --> F[OBBject Construction] F --> G[Results with Metadata] G --> H[User: .to_df, .to_dict, .to_chart] ``` ## Usage Patterns ### Basic Return Type All platform endpoints return OBBject instances: ```python from openbb import obb # Returns OBBject result = obb.cftc.cot_search(query="gold") print(result.to_df()) ``` ### Data Conversion Methods | Method | Description | |--------|-------------| | `to_df()` | Convert results to pandas DataFrame | | `to_dict()` | Convert results to dictionary format | | `to_chart()` | Generate chart-ready data structure | ## Integration Points The OBBject system integrates with: - **Provider System**: All data providers return standardized OBBject instances - **REST API**: Responses are automatically serialized from OBBject format - **CLI Interface**: Tabular display powered by OBBject conversion - **Workspace Widgets**: Data binding through OBBject metadata ## Test Coverage The `openbb_platform/core/integration/test_obbject.py` file contains integration tests verifying OBBject behavior across different provider scenarios and edge cases. ## Platform-Wide Consistency The OpenBB Platform enforces OBBject returns through the core framework, ensuring that whether accessing: - `obb.cftc.cot` - `obb.cftc.cot_search` - `obb.equity.screener(provider="finviz")` - `obb.economy.indicators` All responses follow the same structure and interface conventions. --- ## Provider Interface ### 相关页面 相关主题：[Core Concepts](#page-core-concepts), [Data Providers Overview](#page-providers-overview), [Developing Custom Providers](#page-provider-development)
相关源码文件 以下源码文件用于生成本页说明： - [openbb_platform/core/openbb_core/provider/abstract/query_params.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/provider/abstract/query_params.py) - [openbb_platform/core/openbb_core/provider/abstract/fetcher.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/provider/abstract/fetcher.py) - [openbb_platform/core/openbb_core/provider/abstract/provider.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/provider/abstract/provider.py) - [openbb_platform/core/openbb_core/provider/registry_map.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/provider/registry_map.py) - [openbb_platform/providers/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/README.md) - [openbb_platform/providers/fmp/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/fmp/README.md) - [openbb_platform/providers/government_us/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/government_us/README.md) - [openbb_platform/providers/cftc/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/cftc/README.md)
# Provider Interface ## Overview The Provider Interface is a core architectural component of the OpenBB Platform that abstracts data acquisition from various financial data sources. It provides a unified API for querying external data providers while maintaining provider-specific implementations behind a common interface. The Provider system enables OpenBB to integrate multiple data sources (FMP, Alpha Vantage, US Government data, CFTC, IMF, etc.) through a standardized abstraction layer, allowing users to query different providers using a consistent interface. ## Architecture ```mermaid graph TD A[OpenBB User/Application] --> B[Provider Interface] B --> C[Registry Map] C --> D[Provider: FMP] C --> E[Provider: Government US] C --> F[Provider: CFTC] C --> G[Provider: IMF] C --> H[Provider: Custom] D --> I[Models] E --> I F --> I G --> I I --> J[Query Params] I --> K[Response Models] J --> L[Fetchers] L --> M[External API] M --> N[Data Normalization] N --> O[Standardized Output] ``` ## Core Components ### 1. Provider Abstract Class The base `Provider` class defines the interface that all providers must implement. Each provider declares its available endpoints, authentication requirements, and routing information. | Property | Type | Description | |----------|------|-------------| | name | str | Unique identifier for the provider | | website | str | Provider's official website | | description | str | Brief description of the provider | | credentials | dict | Required API credentials/keys | | available_endpoints | list | Endpoints provided by this source | | url | str | Base URL for API requests | 资料来源：[openbb_platform/core/openbb_core/provider/abstract/provider.py]() ### 2. Query Params Query parameters define the input schema for each endpoint. They validate and serialize user requests before passing them to the fetcher. | Parameter | Type | Description | |-----------|------|-------------| | provider | Optional[str] | Override default provider for this query | | use_cache | bool | Enable/disable response caching | | chunk | bool | Split large responses into chunks | | date | Optional[date] | Filter data by specific date | | start_date | Optional[date] | Filter data from this date | | end_date | Optional[date] | Filter data until this date | | limit | Optional[int] | Maximum number of results | 资料来源：[openbb_platform/core/openbb_core/provider/abstract/query_params.py]() ### 3. Fetcher The `Fetcher` class handles the actual data retrieval from external APIs. It processes query parameters, makes HTTP requests, and normalizes responses. | Component | Description | |-----------|-------------| | transform | Method to normalize raw API response | | extract | Method to extract relevant fields from response | | validate | Method to validate response data | 资料来源：[openbb_platform/core/openbb_core/provider/abstract/fetcher.py]() ### 4. Registry Map The Registry Map maintains a centralized catalog of all registered providers and their endpoints, enabling dynamic discovery and routing. ```mermaid classDiagram class RegistryMap { +dict providers +dict routers +register_provider() +get_provider() +list_providers() +get_endpoint() } class Provider { +str name +list endpoints +register() } class Router { +str name +add_route() +get_routes() } RegistryMap --> Provider RegistryMap --> Router ``` 资料来源：[openbb_platform/core/openbb_core/provider/registry_map.py]() ## Provider Structure Providers in OpenBB follow a standardized directory structure: ``` openbb_platform/providers// ├── README.md ├── pyproject.toml ├── poetry.lock ├── tests/ │ └── ... └── openbb_/ ├── __init__.py ├── models/ │ ├── __init__.py │ └── .py └── utils/ ├── __init__.py └── .py ``` 资料来源：[openbb_platform/providers/README.md]() ## Creating a Custom Provider ### Step 1: Create Provider Directory Create a new directory under `openbb_platform/providers/` with your provider name. ### Step 2: Define Models Models define data structures for querying endpoints and storing responses: ```python from pydantic import BaseModel, Field from openbb_core.provider.abstract.query_params import QueryParams class CustomQuoteQueryParams(QueryParams): symbol: str = Field(description="Stock symbol to query") provider: Optional[str] = None ``` ### Step 3: Implement Fetcher ```python from openbb_core.provider.abstract.fetcher import Fetcher class CustomQuoteFetcher(Fetcher): @staticmethod def transform(params: dict, response: httpx.Response) -> BaseModel: # Transform and normalize response data return NormalizedQuote(**transformed_data) ``` ### Step 4: Register Provider ```python from openbb_core.provider.abstract.provider import Provider class CustomProvider(Provider): name = "custom_provider" website = "https://custom-api.example.com" @property def router(self): return CustomRouter() ``` ## Provider Examples ### Financial Modeling Prep (FMP) ```python from openbb import obb # Search for companies search_results = obb.company.search(query="Apple") print(search_results.to_df()) # Get financial statements balance_sheet = obb.company.balance(symbol="AAPL", provider="fmp") print(balance_sheet.to_df()) ``` 资料来源：[openbb_platform/providers/fmp/README.md]() ### US Government Data ```python from openbb import obb # Treasury auctions auctions = obb.fixed_income.government.treasury_auctions() print(auctions.to_df()) # Treasury prices prices = obb.fixed_income.government.treasury_prices() print(prices.to_df()) ``` 资料来源：[openbb_platform/providers/government_us/README.md]() ### CFTC Commitments of Traders ```python from openbb import obb # Search CFTC codes search_results = obb.cftc.cot_search(query="gold") print(search_results.to_df()) # Get report report = obb.cftc.cot(code="CFTC_088695", measure="percent_of_oi") print(report.to_df().T) ``` 资料来源：[openbb_platform/providers/cftc/README.md]() ## Integration with REST API The Provider system integrates seamlessly with the OpenBB Platform REST API: ```bash uvicorn openbb_core.api.rest_api:app --host 0.0.0.0 --port 8000 --reload ``` API documentation is available at `/docs` endpoint. 资料来源：[openbb_platform/core/openbb_core/api/rest_api.py]() ## Configuration ### API Keys Providers requiring authentication use the credentials system: ```python from openbb import obb obb.user.credentials.fmp_api_key = "YOUR_API_KEY" obb.user.credentials.polygon_api_key = "YOUR_API_KEY" ``` ### Provider Selection When multiple providers support an endpoint, specify the provider explicitly: ```python # Use specific provider result = obb.equity.quote(symbol="AAPL", provider="fmp") # Use default provider result = obb.equity.quote(symbol="AAPL") ``` ## Best Practices | Practice | Description | |----------|-------------| | Error Handling | Always wrap provider calls in try-except blocks | | Caching | Enable caching for frequently accessed data | | Rate Limiting | Respect provider rate limits | | Validation | Use query parameter validation | | Documentation | Document custom providers in README.md | ## Supported Providers | Provider | Category | Registration Required | |----------|----------|----------------------| | FMP | Financial Data | Yes | | Alpha Vantage | Financial Data | Yes | | US Government | Government Data | No | | CFTC | Commodities | No | | IMF | Economic Indicators | No | 资料来源：[openbb_platform/providers/README.md]() ## Conclusion The Provider Interface is fundamental to OpenBB's extensibility. By adhering to the abstract interfaces defined in the core module, developers can integrate new data sources while maintaining a consistent API experience for end users. The registry-based architecture enables dynamic provider discovery and seamless switching between data sources. --- ## Data Providers Overview ### 相关页面 相关主题：[Provider Interface](#page-provider-interface), [Developing Custom Providers](#page-provider-development)
相关源码文件 以下源码文件用于生成本页说明： - [openbb_platform/providers/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/README.md) - [openbb_platform/providers/fmp/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/fmp/README.md) - [openbb_platform/providers/government_us/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/government_us/README.md) - [openbb_platform/providers/tmx/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/tmx/README.md) - [openbb_platform/providers/multpl/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/multpl/README.md) - [openbb_platform/providers/imf/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/imf/README.md) - [openbb_platform/providers/finra/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/finra/README.md) - [openbb_platform/providers/famafrench/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/famafrench/README.md)
# Data Providers Overview Data Providers in the OpenBB Platform serve as extension modules that integrate external financial data sources into the unified OpenBB ecosystem. These providers enable users to access a wide variety of financial data including equity prices, economic indicators, commodity data, government reports, and more through a consistent API interface. ## Architecture Overview The OpenBB Platform uses a modular provider architecture where each data source is implemented as a separate Python package extension. Providers communicate with their respective external APIs, transform the responses into standardized data models, and expose endpoints through the unified OpenBB interface. ```mermaid graph TD A[OpenBB Platform Core] --> B[Provider Extensions] B --> C[Data Provider 1] B --> D[Data Provider 2] B --> N[Data Provider N] C --> E[External API 1] D --> F[External API 2] N --> G[External API N] E --> H[Standardized Data Models] F --> H G --> H ``` Providers follow a consistent structure that ensures maintainability and enables the platform to automatically discover and load endpoints. 资料来源：[openbb_platform/providers/README.md]() ## Provider Directory Structure Every provider follows a standardized directory layout to ensure consistency across the codebase. This structure separates concerns between data models, utilities, and tests. ``` openbb_platform └───providers └─── │ README.md │ pyproject.toml │ poetry.lock ├───tests └───openbb_ │ __init__.py ├───models │ ├───.py │ └───... └───utils ├───.py └───... ``` The `models` directory contains data structures that define both the request parameters for querying provider endpoints and the response data structures. The `utils` directory houses helper functions used internally by the provider. 资料来源：[openbb_platform/providers/README.md]() ## Available Data Providers The OpenBB Platform supports numerous data providers across various financial domains. Below is a comprehensive table of documented providers. | Provider | Package Name | Data Domain | Registration Required | |----------|-------------|-------------|----------------------| | Financial Modeling Prep | `openbb-fmp` | Equity, Fundamentals, Estimates | Yes | | US Government | `openbb-us-government` | Treasury, Commodity Reports | No | | TMX | `openbb-tmx` | Canadian Markets, Derivatives | Varies | | Multpl | `openbb-multpl` | S&P 500 Multiples, Index Data | No | | IMF | `openbb-imf` | Economic Indicators, CPI, Shipping | No | | FINRA | `openbb-finra` | Market Regulatory Data | Varies | | Fama-French | `openbb-famafrench` | Research Factors, Portfolios | No | | News | `openbb-news` | Financial News | Varies | | Regulators | `openbb-regulators` | Global Market Regulators | Varies | | Commodity | `openbb-commodity` | Commodity Data | Varies | ## Provider Installation Each provider is distributed as a separate Python package installable via pip. The general installation pattern follows a consistent command structure. ```bash pip install openbb- ``` ### Installation Examples **Financial Modeling Prep:** ```bash pip install openbb-fmp ``` 资料来源：[openbb_platform/providers/fmp/README.md]() **US Government:** ```bash pip install openbb-us-government ``` 资料来源：[openbb_platform/providers/government_us/README.md]() **TMX (Community Provider):** ```bash pip install openbb-tmx ``` Alternatively, install from local directory for development: ```bash pip install -e . ``` 资料来源：[openbb_platform/providers/tmx/README.md]() ## Endpoint Coverage Examples Different providers offer varying levels of endpoint coverage. Below are examples of what each provider exposes. ### US Government Provider The US Government provider covers endpoints with no registration requirement, making it ideal for accessing public data. | Endpoint | Description | |----------|-------------| | `obb.commodity.psd_report` | PSD Commodity Reports | | `obb.commodity.psd_data` | PSD Data Sets | | `obb.commodity.weather_bulletins` | Weather Bulletins | | `obb.commodity.weather_bulletins_download` | Download Bulletins | | `obb.fixed_income.government.treasury_auctions` | Treasury Auctions | | `obb.fixed_income.government.treasury_prices` | Treasury Prices | 资料来源：[openbb_platform/providers/government_us/README.md]() ### TMX Provider The TMX provider offers Canadian market data including derivatives and equity information. | Endpoint Category | Coverage | |-------------------|----------| | `.derivatives.options.chains` | Historical EOD chains from 2009 | | `.equity.calendar.earnings` | Earnings Calendars | | `.equity.estimates.consensus` | Consensus Estimates | | `.equity.discovery.gainers` | Best Performers | | `.equity.fundamental.dividends` | Dividend History | | `.equity.fundamental.filings` | SEC Filings | | `.equity.ownership.insider_trading` | Insider Trading (3/6/12 months) | | `.equity.price.quote` | Real-time Quotes | | `.equity.price.historical` | Daily/Weekly/Monthly/Intraday | | `.equity.search` | Symbol Search | 资料来源：[openbb_platform/providers/tmx/README.md]() ### IMF Provider The IMF provider provides extensive economic data including indicators and shipping information. **Primary Endpoints:** - `obb.economy.available_indicators` - `obb.economy.indicators` - `obb.economy.cpi` - `obb.economy.direction_of_trade` - `obb.economy.spi` (Shipping) **Utility Endpoints (for UI integrations):** - `obb.imf_utils.get_dataflow_dimensions` - `obb.imf_utils.list_dataflow_choices` - `obb.imf_utils.list_dataflows` - `obb.imf_utils.list_indicators_by_dataflow` - `obb.imf_utils.list_port_id_choices` - `obb.imf_utils.list_table_choices` - `obb.imf_utils.list_tables` - `obb.imf_utils.presentation_table` The "Choices" endpoints are specifically utilized by OpenBB Workspace to populate widget dropdown menus. 资料来源：[openbb_platform/providers/imf/README.md]() ### Multpl Provider The Multpl provider offers simple integration for S&P 500 related data. **Available Endpoints:** - `obb.index.sp500_multiples` 资料来源：[openbb_platform/providers/multpl/README.md]() ### Fama-French Provider The Fama-French provider integrates academic research factor data. It includes metadata about the data source and formation methodology. **Metadata Structure:** ```python factors.extra["results_metadata"] ``` Example metadata output: ```json { 'description': 'This file was created using the 202504 CRSP database...', 'frequency': 'monthly', 'formations': ['Mkt-RF', 'SMB', 'HML', 'RF'] } ``` The frequency and formations metadata fields indicate whether data is monthly, daily, or another frequency, and the specific factor formations available. 资料来源：[openbb_platform/providers/famafrench/README.md]() ## Provider Data Flow ```mermaid graph LR A[User Query] --> B[OpenBB Core API] B --> C[Provider Router] C --> D[Provider Models] D --> E[External API Request] E --> F[Response Parser] F --> G[Standard Model] G --> H[Platform Output] ``` ## Creating New Providers To create a new provider for the OpenBB Platform, follow these steps: 1. Create a new directory under `openbb_platform/providers//` 2. Implement the required directory structure (models, utils, tests) 3. Define data models for requests and responses 4. Implement the provider logic to communicate with external APIs 5. Add a `pyproject.toml` for package configuration 6. Create a `README.md` with installation and usage documentation 7. Publish to PyPI for distribution via `pip install openbb-` For detailed contribution guidelines, refer to the main CONTRIBUTING file in the repository. 资料来源：[openbb_platform/providers/README.md]() ## Extension Types Beyond standard data providers, the OpenBB Platform supports additional extension types that enhance functionality: | Extension Type | Purpose | |---------------|---------| | **Data Providers** | Fetch and transform external financial data | | **News Extension** | `openbb-news` - Provides news aggregation | | **Regulators Extension** | `openbb-regulators` - Global market regulator data | | **Commodity Extension** | `openbb-commodity` - Commodity-specific commands | | **MCP Server** | Model Context Protocol integration for AI tools | These extensions can be installed using `pip install openbb-` and are documented in the `openbb_platform/extensions/` directory. --- ## Developing Custom Providers ### 相关页面 相关主题：[Provider Interface](#page-provider-interface), [Data Providers Overview](#page-providers-overview), [Extensions System](#page-extensions)
相关源码文件 以下源码文件用于生成本页说明： - [openbb_platform/extensions/mcp_server/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/mcp_server/README.md) - [openbb_platform/core/openbb_core/api/rest_api.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/api/rest_api.py) - [cookiecutter/openbb_cookiecutter/template/{{cookiecutter.project_tag}}/{{cookiecutter.package_name}}/providers/{{cookiecutter.provider_name}}/models/example.py](https://github.com/OpenBB-finance/OpenBB/blob/main/cookiecutter/openbb_cookiecutter/template/{{cookiecutter.project_tag}}/{{cookiecutter.package_name}}/providers/{{cookiecutter.provider_name}}/models/example.py) - [cookiecutter/openbb_cookiecutter/template/{{cookiecutter.project_tag}}/{{cookiecutter.package_name}}/providers/{{cookiecutter.provider_name}}/utils/helpers.py](https://github.com/OpenBB-finance/OpenBB/blob/main/cookiecutter/openbb_cookiecutter/template/{{cookiecutter.project_tag}}/{{cookiecutter.package_name}}/providers/{{cookiecutter.provider_name}}/utils/helpers.py) - [openbb_platform/providers/fmp/openbb_fmp/utils/helpers.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/fmp/openbb_fmp/utils/helpers.py) - [desktop/src/components/InstallComponents.tsx](https://github.com/OpenBB-finance/OpenBB/blob/main/desktop/src/components/InstallComponents.tsx)
# Developing Custom Providers ## Overview Custom providers extend the OpenBB Platform by integrating new data sources for financial information. The platform uses a standardized architecture that allows developers to create providers following established patterns, enabling seamless integration with the existing OpenBB ecosystem including the REST API, MCP server, and desktop interface. The provider system is designed around modularity—each provider consists of data models, authentication handlers, and utility functions that work together to fetch, transform, and expose financial data through a unified interface. ## Architecture Overview ```mermaid graph TD A[Custom Provider] --> B[Data Models] A --> C[Authentication] A --> D[Utility Helpers] B --> E[REST API Router] C --> E D --> E E --> F[OpenBB Platform API] F --> G[MCP Server] F --> H[Desktop Interface] F --> I[Direct SDK Access] ``` ## Provider Structure Each custom provider follows a consistent directory structure: ``` {{cookiecutter.package_name}}/ └── providers/ └── {{cookiecutter.provider_name}}/ ├── models/ │ └── example.py # Data models ├── utils/ │ └── helpers.py # Utility functions └── __init__.py # Provider initialization ``` ### Data Models Data models define the schema for the financial data your provider will return. The OpenBB Platform uses standardized model classes that inherit from base types: ```python # cookiecutter template structure class ExampleModel: """Example data model for custom provider.""" symbol: str name: str price: float timestamp: datetime @field_validator('price') @classmethod def validate_price(cls, v): if v < 0: raise ValueError("Price must be non-negative") return v ``` 资料来源：[cookiecutter/.../models/example.py]() ### Utility Helpers Helper functions handle common operations like API requests, data transformation, and authentication: ```python import requests from typing import Optional, Dict, Any def get_data( url: str, params: Optional[Dict[str, Any]] = None, headers: Optional[Dict[str, str]] = None, timeout: int = 30 ) -> Dict[str, Any]: """Fetch data from the provider's API endpoint.""" response = requests.get(url, params=params, headers=headers, timeout=timeout) response.raise_for_status() return response.json() def transform_response(data: Dict[str, Any]) -> Dict[str, Any]: """Transform provider-specific response format to OpenBB standard format.""" return { "symbol": data.get("symbol", ""), "name": data.get("companyName", ""), "price": float(data.get("price", 0)), "timestamp": data.get("timestamp") } ``` 资料来源：[cookiecutter/.../utils/helpers.py]() 资料来源：[openbb_platform/providers/fmp/openbb_fmp/utils/helpers.py]() ## Provider Configuration ### MCP Server Integration Custom providers can be exposed through the Model Context Protocol (MCP) server, allowing AI assistants to interact with your data: ```python from openbb_mcp_server.models.mcp_config import MCPConfigModel # In your route definition openapi_extra = { "mcp_config": MCPConfigModel( expose=True, mcp_type="tool", methods=["GET"] ) } ``` **MCP Configuration Properties:** | Property | Type | Description | |----------|------|-------------| | `expose` | `Optional[bool]` | Set to `False` to hide from MCP server | | `mcp_type` | `Optional[MCPType]` | Type: `"tool"`, `"resource"`, or `"resource_template"` | | `methods` | `Optional[list[HTTPMethod]]` | HTTP methods to expose | 资料来源：[openbb_platform/extensions/mcp_server/README.md]() ### REST API Registration The OpenBB Platform uses FastAPI for its REST API. Providers register through the `AppLoader`: ```python from fastapi import FastAPI from openbb_core.api.rest_api import AppLoader # Providers are automatically loaded via the extension system # The router is added through the provider's __init__.py ``` The API server is configured with CORS middleware: ```python app.add_middleware( CORSMiddleware, allow_origins=system.api_settings.cors.allow_origins, allow_methods=system.api_settings.cors.allow_methods, allow_headers=system.api_settings.cors.allow_headers, ) ``` 资料来源：[openbb_platform/core/openbb_core/api/rest_api.py]() ## Creating a Provider from Template The OpenBB Cookiecutter template provides a starting point for new providers: ```bash cookiecutter gh:OpenBB-finance/OpenBB --directory cookiecutter ``` The generated template includes: - Pre-configured directory structure - Example model implementations - Utility function templates - Authentication patterns - Test scaffolding ## Extension Installation System The desktop interface provides a mechanism for users to discover and install provider extensions: ```typescript // Extensions are fetched from GitHub configuration const [providersRes, routersRes, obbjectsRes] = await Promise.all([ fetch("https://raw.githubusercontent.com/OpenBB-finance/OpenBB/main/assets/extensions/provider.json"), fetch("https://raw.githubusercontent.com/OpenBB-finance/OpenBB/main/assets/extensions/router.json"), fetch("https://raw.githubusercontent.com/OpenBB-finance/OpenBB/main/assets/extensions/obbject.json"), ]); ``` 资料来源：[desktop/src/components/InstallComponents.tsx]() ### Extension Categories | Category ID | Description | |-------------|-------------| | `providers` | Data source integrations | | `routers` | Custom API endpoints | | `obbjects` | Custom data object types | | `extras` | Additional PyPI packages | ## Workflow Diagram ```mermaid graph LR A[Create Provider] --> B[Define Models] B --> C[Implement Helpers] C --> D[Register Routes] D --> E[Add MCP Config] E --> F[Test Provider] F --> G[Publish Extension] G --> H[User Installs] H --> I[Available in Platform] ``` ## Best Practices ### Authentication Handling - Store API keys securely using environment variables - Implement token refresh logic for OAuth flows - Provide clear error messages for authentication failures ### Data Validation - Validate all incoming data against expected schemas - Use field validators for type checking and constraints - Handle missing or null values gracefully ### Error Handling - Implement retry logic for transient failures - Log errors with sufficient context for debugging - Return standardized error responses ### Performance Considerations - Cache frequently accessed data when appropriate - Use connection pooling for API requests - Implement request batching where the API supports it ## See Also - [OpenBB Platform Extensions](../extensions/index.md) - [MCP Server Documentation](../extensions/mcp_server/index.md) - [REST API Reference](../api-rest/index.md) - [Cookiecutter Template Repository](https://github.com/OpenBB-finance/OpenBB/tree/main/cookiecutter) --- ## Extensions System ### 相关页面 相关主题：[Core Concepts](#page-core-concepts), [Charting and Visualization](#page-charting)
相关源码文件 以下源码文件用于生成本页说明： - [openbb_platform/extensions/equity/openbb_equity/__init__.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/equity/openbb_equity/__init__.py) - [openbb_platform/extensions/crypto/openbb_crypto/__init__.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/crypto/openbb_crypto/__init__.py) - [openbb_platform/extensions/fixedincome/openbb_fixedincome/__init__.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/fixedincome/openbb_fixedincome/__init__.py) - [openbb_platform/core/openbb_core/app/extension_loader.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/app/extension_loader.py)
# Extensions System ## Overview The OpenBB Extensions System is a modular architecture that allows users to extend the core platform functionality through optional packages called "extensions." These extensions provide specialized data sources, additional features, and domain-specific tools for various financial market segments. Extensions in OpenBB serve as the primary mechanism for feature expansion, enabling users to install only the components they need while keeping the core platform lightweight. The system supports both official OpenBB extensions and third-party community extensions. ## Architecture ### Core Components The Extensions System consists of several interconnected components: | Component | Purpose | Location | |-----------|---------|----------| | Extension Loader | Discovers and loads extensions at runtime | `openbb_platform/core/openbb_core/app/extension_loader.py` | | Extension Package | Python package with specialized functionality | `openbb_platform/extensions//` | | Environment Manager | Manages extension installation in isolated environments | `desktop/src-tauri/src/tauri_handlers/environments.rs` | | UI Integration | Frontend component for extension management | `desktop/src/routes/environments.tsx` | ### Extension Types OpenBB extensions are categorized into several types based on their functionality: ```mermaid graph TD A[OpenBB Platform] --> B[Core Extensions] A --> C[Data Provider Extensions] A --> D[Feature Extensions] B --> B1[Equity] B --> B2[Economy] B --> B3[Crypto] B --> B4[Fixed Income] C --> C1[Government US] C --> C2[IMF] C --> C3[CFTC] C --> C4[Multpl] D --> D1[News] D --> D2[MCP Server] D --> D3[Regulators] ``` ## Extension Discovery and Loading ### Extension Loader Mechanism The extension loader (`extension_loader.py`) handles the discovery and loading of extensions. It performs the following operations: 1. **Package Discovery**: Scans installed Python packages for OpenBB extension markers 2. **Dependency Resolution**: Ensures all extension dependencies are available 3. **Router Registration**: Registers extension routers with the main application 4. **Initialization**: Calls extension `__init__.py` to set up routes and handlers ```mermaid graph LR A[Scan Packages] --> B[Identify Extensions] B --> C{Check Dependencies} C -->|Missing| D[Log Warning] C -->|Satisfied| E[Load Extension] E --> F[Register Router] F --> G[Ready for Use] ``` ### Loading Process Flow Extensions follow a specific loading sequence to ensure proper initialization order: 1. Core platform initializes first 2. Extension loader scans for available extensions 3. Each extension's dependencies are verified 4. Extensions are loaded in dependency order 5. Extension routers are registered with FastAPI 6. Extensions become available via `obb..` ## Extension Package Structure ### Standard Layout Each OpenBB extension follows a consistent directory structure: ``` openbb_platform/extensions// ├── README.md # Documentation ├── pyproject.toml # Package configuration ├── poetry.lock # Dependency lock file ├── openbb_/ │ ├── __init__.py # Router registration │ └── ... └── tests/ └── ... ``` ### Required Components | File | Purpose | |------|---------| | `__init__.py` | Contains router definition and extension metadata | | `pyproject.toml` | Package metadata, dependencies, and build configuration | | `README.md` | Installation instructions and feature documentation | ## Extension Categories ### 1. Core Extensions Core extensions provide essential market data functionality: #### Equity Extension The Equity extension (`openbb_equity`) provides equity market data tools including: - Historical price data - Fundamental analysis - Analyst estimates - Options data - Ownership information - Short interest data **Installation:** ```bash pip install openbb-equity ``` #### Fixed Income Extension The Fixed Income extension (`openbb_fixedincome`) offers fixed income market tools: - Government bond data - Treasury auctions - Treasury prices - Credit spreads #### Economy Extension Provides global macroeconomic data access including: - GDP indicators - CPI data - Trade statistics - Economic indicators #### Crypto Extension Cryptocurrency market data including: - Price data - Trading volumes - Market capitalization - Exchange data ### 2. Data Provider Extensions Data providers extend the platform's data sources: #### Government US (`openbb-us-government`) Provides US Government data from data.gov: | Endpoint | Function | |----------|----------| | `obb.commodity.psd_report` | PSD reports | | `obb.commodity.psd_data` | PSD data | | `obb.commodity.weather_bulletins` | Weather bulletins | | `obb.fixed_income.government.treasury_auctions` | Treasury auctions | | `obb.fixed_income.government.treasury_prices` | Treasury prices | **Installation:** ```bash pip install openbb-us-government ``` #### CFTC Provider Commitments of Traders (COT) data including: - `obb.cftc.cot` - COT reports - `obb.cftc.cot_search` - Search COT data #### IMF Provider International Monetary Fund data with endpoints: - `obb.economy.indicators` - `obb.economy.cpi` - `obb.economy.direction_of_trade` - `obb.economy.shipping.*` #### Multpl Provider S&P 500 valuation metrics: - `obb.index.sp500_multiples` ### 3. Feature Extensions #### News Extension Aggregates financial news from multiple sources. **Installation:** ```bash pip install openbb-news ``` #### MCP Server Extension Model Context Protocol server for AI integrations. Provides: - Tool exposure as MCP resources - FastAPI route exposure - Custom prompt definitions Configuration via `openapi_extra.mcp_config`: | Property | Type | Description | |----------|------|-------------| | `expose` | `Optional[bool]` | Hide/show route from MCP server | | `mcp_type` | `Optional[MCPType]` | Classification: `"tool"`, `"resource"`, or `"resource_template"` | | `methods` | `Optional[list[HTTPMethod]]` | HTTP methods to expose | #### Regulators Extension Provides structure for data from global market regulators. **Installation:** ```bash pip install openbb-regulators ``` ## Environment-Based Extension Management ### Concept Extensions can be installed within isolated Python environments, allowing users to: - Maintain separate extension sets for different use cases - Avoid dependency conflicts between extensions - Enable/disable extension groups easily ### Environment Handler Architecture The desktop application uses a Rust-based backend for environment management: ```mermaid graph TD A[Frontend Environment UI] --> B[Tauri Command] B --> C[environments.rs Handler] C --> D{Conda Environment?} D -->|base| E[System Conda Install] D -->|custom| F[Named Environment Install] E --> G[Install Extensions] F --> G G --> H[Refresh Extensions List] ``` ### Extension Installation in Environments The environment handler processes extensions with special prefixes: ```python # Prefix handling logic from environments.rs if extension.startswith("conda:"): # Add to conda package list conda_packages.push(extension.strip_prefix("conda:")) else: # Add to pip packages pip_packages.push(extension) ``` ### Caching Strategy The environment extensions list is cached locally: ```typescript // Cache structure in environments.tsx const cache = cachedData ? JSON.parse(cachedData) : {}; cache[env.name] = result.extensions; localStorage.setItem(ENV_EXTENSIONS_CACHE_KEY, JSON.stringify(cache)); ``` ## Installation and Setup ### Installation Phases The desktop installation process consists of three phases: ```mermaid graph TD A[Phase 1: Miniforge] --> B[Phase 2: Core Setup] B --> C[Phase 3: Extension Select] A --> |Miniforge + Conda| D[Python Environment] B --> |Core Libraries| D C --> |Optional Packages| D ``` ### Initial Installation Components When setting up a new environment, the following components are installed: | Component | Purpose | |-----------|---------| | Miniforge | Python environment manager | | Core libraries | OpenBB platform dependencies | | iPython | Interactive Python shell | | Jupyter Lab | Web-based development environment | ### Extension Selection UI The extension selection phase allows users to: 1. Select which extensions to install 2. Add additional PyPI packages 3. Configure environment-specific settings ## Error Handling ### Extension Loading Errors | Error Type | Cause | Resolution | |------------|-------|------------| | Missing Dependency | Extension requires unavailable package | Install missing package | | Import Failure | Extension module has errors | Check extension installation | | Router Conflict | Duplicate endpoint definitions | Review extension configuration | ### Installation Errors The system handles installation errors gracefully: ```typescript // Error display with retry option {createEnvironmentError && (

{extractStderr(createEnvironmentError)}

)} ``` ## API Reference ### Extension Loading API Extensions are accessed through the main `obb` object: ```python from openbb import obb # Access equity data result = obb.equity.price_history(symbol="AAPL") # Access fixed income data result = obb.fixed_income.government.treasury_auctions() # Access CFTC data result = obb.cftc.cot(code="CFTC_088695", measure="percent_of_oi") ``` ### Extension Router Pattern Extensions define routers for API endpoints: ```python # Example from extension __init__.py from openbb_core.provider.standard_routes import router @router.command() async def endpoint(params: Model): # Implementation pass ``` ## Best Practices ### Extension Development 1. Follow the standard directory structure 2. Define clear router endpoints 3. Use Pydantic models for request/response validation 4. Document all endpoints in README.md 5. Include comprehensive test coverage ### Extension Installation 1. Verify Python environment compatibility 2. Check dependency requirements 3. Use virtual environments for testing 4. Review extension permissions and data access ## See Also - [OpenBB Platform Documentation](https://docs.openbb.co/python/) - [Provider Development Guide](../CONTRIBUTING.md) - [MCP Server Extension](../extensions/mcp_server/README.md) - [Equity Extension](../extensions/equity/README.md) --- ## Charting and Visualization ### 相关页面 相关主题：[OBBject System](#page-obbject-system), [Extensions System](#page-extensions)
相关源码文件 以下源码文件用于生成本页说明： - [openbb_platform/obbject_extensions/charting/openbb_charting/charting.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/obbject_extensions/charting/openbb_charting/charting.py) - [openbb_platform/obbject_extensions/charting/openbb_charting/core/openbb_figure.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/obbject_extensions/charting/openbb_charting/core/openbb_figure.py) - [openbb_platform/obbject_extensions/charting/openbb_charting/core/plotly_ta/ta_class.py](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/obbject_extensions/charting/openbb_charting/core/plotly_ta/ta_class.py) - [openbb_platform/obbject_extensions/charting/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/obbject_extensions/charting/README.md)
# Charting and Visualization The OpenBB charting and visualization system provides an interactive charting library built on top of Plotly. It functions as an **OBBject extension**, meaning charting capabilities are automatically available on every command result returned by the OpenBB Platform. ## Overview The charting extension transforms raw financial data into interactive visualizations with support for: - **Technical Analysis Indicators** - SMA, EMA, MACD, RSI, Bollinger Bands, Stochastic Oscillator, ADX, and more - **Prebuilt Charts** - Dedicated visualizations for specific endpoints - **Custom Charts** - User-defined charts from DataFrames without Plotly knowledge - **OHLCV Time Series** - Specialized handling for candlestick and financial time series data 资料来源：[openbb_platform/obbject_extensions/charting/README.md:1-10]() ## Architecture ```mermaid graph TD A["OBBject
(Command Result)"] --> B["charting accessor"] B --> C["OpenBBFigure"] B --> D["Charting Methods"] B --> E["Technical Analysis"] C --> F["Plotly Figure"] C --> G["Raw Data Dict"] D --> H["create_3d_surface()"] D --> I["create_bar_chart()"] D --> J["create_line_chart()"] D --> K["create_correlation_matrix()"] D --> L["to_chart()"] E --> M["PlotlyTA Class"] M --> N["sma, ema, macd"] M --> O["rsi, adx, bbands"] M --> P["stoch, and more"] ``` ### Core Components | Component | File Path | Purpose | |-----------|-----------|---------| | `Charting` | `openbb_charting/charting.py` | Main extension class with `indicators()` and `functions()` methods | | `OpenBBFigure` | `openbb_charting/core/openbb_figure.py` | Wrapper for Plotly figures with data extraction | | `PlotlyTA` | `openbb_charting/core/plotly_ta/ta_class.py` | Technical analysis indicator engine | 资料来源：[openbb_platform/obbject_extensions/charting/README.md:50-60]() ## Installation ```bash # Base installation pip install openbb-charting # With native OS window support pip install "openbb-charting[pywry]" ``` ### Linux Dependencies | Distribution | Command | |-------------|---------| | Debian/Ubuntu/Mint | `sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev` | | Arch Linux/Manjaro | `sudo pacman -S webkit2gtk` | | Fedora | `sudo dnf install gtk3-devel webkit2gtk3-devel` | 资料来源：[openbb_platform/obbject_extensions/charting/README.md:15-35]() ## Basic Usage ### Enabling Charts on Command Results ```python from openbb import obb # Method 1: Set chart=True argument equity_data = obb.equity.price.historical(symbol="TSLA", chart=True) # Method 2: Access charting on existing result res = obb.equity.price.historical("AAPL") res.charting.show() ``` Both methods produce identical results. The `chart=True` parameter returns an OBBject with a `chart` attribute containing Plotly JSON data. 资料来源：[openbb_platform/obbject_extensions/charting/README.md:50-75]() ### Displaying Charts ```python # Get chart data equity_data = obb.equity.price.historical(symbol="TSLA", chart=True) # Display in native window equity_data.show() ``` ## Custom Charts from DataFrames Create visualizations directly from Pandas DataFrames without Plotly knowledge: ```python res = obb.equity.price.historical("AAPL", chart=True) # Available charting methods surface_3d = res.charting.create_3d_surface bar_chart = res.charting.create_bar_chart line_chart = res.charting.create_line_chart correlation_matrix = res.charting.create_correlation_matrix ``` The `data` parameter accepts either `OBBject.results` as a list or any Pandas DataFrame instance. 资料来源：[openbb_platform/obbject_extensions/charting/README.md:95-110]() ## Technical Analysis Integration ### Available Indicators ```python from openbb_charting import Charting # List all available indicators Charting.indicators() ``` | Indicator | Parameters | Description | |-----------|------------|-------------| | `sma` | `length` | Simple Moving Average | | `ema` | `length` (list supported) | Exponential Moving Average | | `macd` | `fast`, `slow`, `signal` | Moving Average Convergence Divergence | | `rsi` | `length` | Relative Strength Index | | `adx` | `length` | Average Directional Index | | `bbands` | `length`, `std` | Bollinger Bands | | `stoch` | `length` | Stochastic Oscillator | 资料来源：[openbb_platform/obbject_extensions/charting/README.md:30-45]() ### Using the `to_chart()` Method The `to_chart()` method is an advanced feature that passes `**kwargs` to the `PlotlyTA` class for custom visualizations with technical indicators. ```python from openbb import obb res = obb.equity.price.historical("AAPL") indicators = dict( sma=dict(length=[20, 30, 50]), adx=dict(length=14), rsi=dict(length=14), macd=dict(fast=12, slow=26, signal=9), bbands=dict(length=20, std=2), stoch=dict(length=14), ) res.charting.to_chart(**{"indicators": indicators}) ``` > **Note:** This method only works with standardized data and is designed for OHLCV time series. 资料来源：[openbb_platform/obbject_extensions/charting/README.md:55-80]() ### Discovering Supported Endpoints Not all endpoints have dedicated charts. To discover supported endpoints: ```python from openbb_charting import Charting Charting.functions() ``` This returns a list of endpoints that have prebuilt charting support. 资料来源：[openbb_platform/obbject_extensions/charting/README.md:95-100]() ## OpenBBFigure Class The `OpenBBFigure` class wraps Plotly figures with additional functionality: ```python from openbb_charting.core.openbb_figure import OpenBBFigure ``` ### Return Value Structure When using charting methods, the return type is: ```python Tuple[OpenBBFigure, Dict[str, Any]] ``` | Return Element | Type | Description | |---------------|------|-------------| | First | `OpenBBFigure` | Interactive Plotly figure | | Second | `Dict[str, Any]` | Raw data used by the API | ## Creating Custom Chart Extensions ### Poetry Plugin Configuration Add visualization to an existing Platform command via `pyproject.toml`: ```toml [tool.poetry.plugins."openbb_charting_extension"] my_extension = "openbb_my_extension.my_extension_views:MyExtensionViews" ``` The `openbb_charting_extension` entry point is **mandatory** for discovery. 资料来源：[openbb_platform/obbject_extensions/charting/README.md:100-115]() ### Extension Views Module ```python """Views for MyExtension.""" from typing import Any, Dict, Tuple from openbb_charting.charts.price_historical import price_historical from openbb_charting.core.openbb_figure import OpenBBFigure class MyExtensionViews: """MyExtension Views.""" @staticmethod def my_extension_price_historical( **kwargs, ) -> Tuple[OpenBBFigure, Dict[str, Any]]: """MyExtension Price Historical Chart.""" return price_historical(**kwargs) ``` After implementation, charts are accessible via: - Python interface: `obb.equity.price.historical("SYMBOL", chart=True)` - Direct access: `result.charting.show()` 资料来源：[openbb_platform/obbject_extensions/charting/README.md:115-135]() ## Workflow Summary ```mermaid graph LR A["obb.equity.price.historical()"] --> B{chart=True?} B -->|Yes| C["Returns OBBject
with chart data"] B -->|No| D["Returns OBBject
without chart data"] C --> E["result.charting.show()"] C --> F["result.charting.create_bar_chart()"] C --> G["result.charting.to_chart()"] D --> H["result.charting.to_chart()"] H --> I["Must have OHLCV data"] E --> J["Display visualization"] F --> K["Custom chart from data"] G --> L["TA indicators overlay"] ``` ## Summary Table: Charting Methods | Method | Input | Use Case | |--------|-------|----------| | `show()` | None | Display current chart in native window | | `to_chart(indicators={})` | Dict of indicator configs | Add TA indicators to time series | | `create_3d_surface(data=...)` | DataFrame or list | 3D surface visualization | | `create_bar_chart(data=...)` | DataFrame or list | Bar chart from any data | | `create_line_chart(data=...)` | DataFrame or list | Line chart from any data | | `create_correlation_matrix(data=...)` | DataFrame or list | Correlation heatmap | | `indicators()` | None | List available TA indicators | | `functions()` | None | List supported endpoint charts | --- ## Command Line Interface ### 相关页面 相关主题：[Installation Guide](#page-installation) The provided context does not include the CLI source files mentioned in the query (cli/openbb_cli/cli.py, cli/openbb_cli/controllers/cli_controller.py, cli/openbb_cli/argparse_translator/argparse_translator.py, cli/README.md). The context only contains files related to the desktop application UI, backend handlers, and platform extensions. To create an accurate technical wiki page about the Command Line Interface based on actual source code, I would need access to the CLI implementation files. Without these files, I cannot provide verified technical details about: - The CLI entry point and main command structure - The controller architecture and command handlers - The argparse translation system - Available commands and their parameters - The CLI's interaction with the OpenBB Platform Could you please provide the CLI source files from the repository so I can generate an accurate and well-sourced technical wiki page? --- ## Desktop Application ### 相关页面 相关主题：[Installation Guide](#page-installation)
Relevant Source Files 以下源码文件用于生成本页说明： - [desktop/src/routes/backends.tsx](https://github.com/OpenBB-finance/OpenBB/blob/main/desktop/src/routes/backends.tsx) - [desktop/src/routes/installation-progress.tsx](https://github.com/OpenBB-finance/OpenBB/blob/main/desktop/src/routes/installation-progress.tsx) - [desktop/src/components/AddExtensionSelector.tsx](https://github.com/OpenBB-finance/OpenBB/blob/main/desktop/src/components/AddExtensionSelector.tsx) - [desktop/src/components/InstallComponents.tsx](https://github.com/OpenBB-finance/OpenBB/blob/main/desktop/src/components/InstallComponents.tsx) - [desktop/src/components/Icon.tsx](https://github.com/OpenBB-finance/OpenBB/blob/main/desktop/src/components/Icon.tsx) - [desktop/src/routes/environments.tsx](https://github.com/OpenBB-finance/OpenBB/blob/main/desktop/src/routes/environments.tsx) - [desktop/src/routes/api-keys.tsx](https://github.com/OpenBB-finance/OpenBB/blob/main/desktop/src/routes/api-keys.tsx) - [openbb_platform/extensions/mcp_server/README.md](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/mcp_server/README.md)
# Desktop Application The OpenBB Desktop Application provides a comprehensive graphical interface for managing financial data workflows, Python environments, API keys, and backend services. Built with React and TypeScript for the frontend, the desktop app offers users a visual approach to configuring and operating the OpenBB platform without requiring command-line interaction. ## Architecture Overview The desktop application follows a client-side rendering architecture using React Router for navigation and Tauri as the desktop runtime. The frontend communicates with backend services through IPC (Inter-Process Communication) mechanisms provided by Tauri. ```mermaid graph TD subgraph Desktop["Desktop Application"] subgraph UI["React Frontend"] Routes["Routes/Pages"] Components["UI Components"] State["State Management"] end subgraph Tauri["Tauri Backend"] TauriHandlers["Tauri Handlers"] IPC["IPC Commands"] end end subgraph Services["External Services"] Python["Python Environments"] OpenBB["OpenBB Platform"] APIs["Third-party APIs"] end UI --> Tauri Tauri --> IPC IPC --> Services ``` ### Key Technologies | Component | Technology | Purpose | |-----------|------------|---------| | Frontend Framework | React 18+ | UI rendering and component management | | Routing | React Router (createFileRoute) | Page navigation and URL handling | | Desktop Runtime | Tauri | Native desktop functionality | | Styling | Tailwind CSS + Theme System | Visual design and theming | | State | React Hooks | Local and shared state management | ## Route Structure The desktop application defines several key routes for managing different aspects of the OpenBB platform. ### Route Hierarchy | Route Path | Component | Purpose | |------------|-----------|---------| | `/backends` | BackendsPage | Manage backend services and configurations | | `/environments` | EnvironmentsPage | Create and manage Python environments | | `/installation-progress` | InstallationProgressPage | Track installation workflow progress | | `/api-keys` | APIKeysPage | Manage third-party API credentials | 资料来源：[desktop/src/routes/environments.tsx](desktop/src/routes/environments.tsx) (route definition) ## Backend Management The `/backends` route provides functionality for managing OpenBB backend services, including starting, stopping, and configuring backend processes. ### Backend Configuration Panel ```mermaid graph LR A[User Action] --> B{Backend Running?} B -->|Yes| C[Show Process ID] B -->|No| D[Start Backend] D --> E[Wait for Initialization] E --> F[Confirm Service URL] F --> G[Display Backend Panel] ``` ### Key Features - **Process Management**: Monitor and control backend process lifecycle - **Working Directory Selection**: Configure the directory from which the backend executable runs (defaults to `{installation_directory}/backends`) - **Command Configuration**: Customize the backend startup command (default: `openbb-api`) - **Service Initialization**: Display loading state while waiting for service to initialize - **Process ID Tracking**: Show the PID of running backend processes 资料来源：[desktop/src/routes/backends.tsx](desktop/src/routes/backends.tsx) ### Backend Configuration Parameters | Parameter | Type | Description | Default | |-----------|------|-------------|---------| | `command` | string | Backend startup command | `openbb-api` | | `workingDir` | string | Execution directory | `{install_dir}/backends` | | `extractedPid` | number | Process identifier | - | | `urlConfirmed` | boolean | Service URL verified | false | ## Environment Management The `/environments` route enables users to create, manage, and configure Python virtual environments using Miniforge. ### Environment Creation Workflow ```mermaid graph TD A[Start Create Environment] --> B[Step 1: Name] B --> C{Valid Name?} C -->|No| B C -->|Yes| D[Step 2: Python Version] D --> E[Select Python] E --> F[Step 3: Extensions] F --> G[Select Extensions] G --> H[Create Environment] H --> I{Success?} I -->|No| J[Show Error + Retry] I -->|Yes| K[Environment Ready] ``` ### Environment Name Validation Environment names must follow specific conventions for compatibility with Conda: ``` Pattern: /^[a-z0-9-]+$/ Allowed: lowercase letters, numbers, hyphens Forbidden: uppercase, spaces, special characters ``` 资料来源：[desktop/src/routes/environments.tsx](desktop/src/routes/environments.tsx) ### Environment States | State | Description | UI Treatment | |-------|-------------|---------------| | `loading` | Fetching environment list | Spinner + loading text | | `creating` | Environment creation in progress | Progress indicator | | `error` | Operation failed | Red error panel with retry option | | `complete` | Operation successful | Success message | ## Installation Progress The installation workflow guides users through the complete setup process in sequential phases. ### Installation Phases ```mermaid graph LR A[phase: version_select] --> B[phase: extension_select] B --> C[phase: installing] C --> D{Result} D -->|Success| E[Complete] D -->|Failure| F[Error State] D -->|Cancelled| G[phase: cancelled] ``` ### Phase Breakdown | Phase | Step Indicator | Description | |-------|----------------|-------------| | `version_select` | STEP 1 OF 3 | Select Python version via Miniforge | | `extension_select` | STEP 3 OF 3 | Choose OpenBB extensions and additional packages | | `installing` | N/A | Installation in progress | | `cancelled` | N/A | User cancelled installation | | `error` | N/A | Installation failed | ### Initial Installation Components The base installation includes: - **Miniforge**: Python environment manager - **OpenBB Environment**: Core libraries and dependencies - **iPython & Jupyter Lab**: Interactive computing tools 资料来源：[desktop/src/routes/installation-progress.tsx](desktop/src/routes/installation-progress.tsx) ## Extension Management Extensions extend the functionality of the OpenBB platform by providing additional data sources, analytical tools, and integrations. ### Extension Selector Component The `AddExtensionSelector` component provides a user interface for browsing and selecting extensions. ```mermaid graph TD A[AddExtensionSelector] --> B[Extension List] A --> C[Conda Packages] A --> D[Custom PyPI Packages] A --> E[OpenBB Extensions] B --> F[Search/Filter] C --> G[Package Counter] D --> G E --> G G --> H[Install Button] ``` ### Extension Selection States | Selection Type | Counter Display | Example | |----------------|-----------------|---------| | Conda packages | `{n} Conda` | `2 Conda` | | PyPI packages | `{n} PyPI` | `3 PyPI` | | OpenBB extensions | `{n} OpenBB extensions` | `5 OpenBB extensions` | 资料来源：[desktop/src/components/AddExtensionSelector.tsx](desktop/src/components/AddExtensionSelector.tsx) ### Extension Display Features Extensions are displayed with setup instructions rendered via `ReactMarkdown`: - **Images**: Max height 300px, lazy loading - **Links**: Open in new tab with `rel="noreferrer noopener"` - **Code blocks**: Themed with `bg-theme-tertiary` - **Paragraphs**: Styled with `text-theme-secondary` 资料来源：[desktop/src/components/InstallComponents.tsx](desktop/src/components/InstallComponents.tsx) ## API Key Management The `/api-keys` route provides secure storage and management for third-party API credentials. ### API Key Operations | Operation | Description | UI Element | |-----------|-------------|------------| | Add | Add new API key via modal | "Add API Key" button | | Edit | Modify existing key | Edit icon button | | Delete | Remove key from storage | Delete action | | Copy | Copy key value to clipboard | Copy icon button | | Import | Import keys from JSON/ENV file | "Import Keys" button | ### Modal Modes The API key modal operates in two modes: | Mode | Header Text | Purpose | |------|-------------|---------| | `add` | Add API Key | Create new credential entry | | `edit` | Edit API Key | Modify existing credential | ### File Import Support The import functionality accepts: - `.json` format - `.env` format 资料来源：[desktop/src/routes/api-keys.tsx](desktop/src/routes/api-keys.tsx) ## UI Components Library ### Icon System The application uses a centralized icon system defined in `Icon.tsx`. ```tsx // OpenBB Logo Component export const FileIcon = (props: React.ComponentProps<"svg">) => ( {/* SVG path data */} ); ``` Icons are integrated using the `CustomIcon` component with named identifiers. ### Button Variants | Variant | Class | Usage | |---------|-------|-------| | `primary` | `button-primary` | Main actions | | `secondary` | `button-secondary` | Secondary actions | | `outline` | `button-outline` | Alternative actions | | `ghost` | `button-ghost` | Subtle actions | | `danger` | `button-danger` | Destructive actions | ### Tooltip System Tooltips provide contextual help using the `Tooltip` component: ```tsx ``` ## Theme System The desktop application implements a comprehensive theme system with CSS custom properties. ### Theme Color Classes | Class | Usage | Example | |-------|-------|---------| | `bg-theme-primary` | Main background | Cards, panels | | `bg-theme-secondary` | Secondary background | Modals, dialogs | | `bg-theme-tertiary` | Tertiary background | Input fields, wells | | `text-theme-primary` | Primary text | Headings, labels | | `text-theme-secondary` | Secondary text | Body content | | `text-theme-muted` | Muted text | Hints, placeholders | | `border-theme` | Border color | Input borders | | `border-theme-accent` | Accent borders | Focus states | ### Status Colors | Status | Color | Usage | |--------|-------|-------| | Success | `green-500` | Completed actions | | Error | `red-500` | Failed operations | | Warning | `yellow-500` | Warnings | | Info | `accent-color` | Loading, progress | ## State Management Patterns ### Form State Handling Input validation follows a consistent pattern: ```typescript // Name validation regex const isValidName = (name: string): boolean => { return /^[a-z0-9-]+$/.test(name); }; ``` ### Loading States | State Variable | Component | Indicator | |----------------|-----------|-----------| | `creationLoading` | Environment creation | Spinner + "This may take several minutes" | | `extensionsLoading` | Extension list | Loading indicator | | `isInstalling` | Extension installation | "Installing..." button text | ### Error Handling Errors are displayed in styled containers: ```tsx {error && (

{error}

)} ``` ## MCP Server Integration The desktop application can expose backend functionality through the Model Context Protocol (MCP), allowing integration with AI assistants and external tools. ### MCP Configuration Options | Property | Type | Description | |----------|------|-------------| | `expose` | `Optional[bool]` | Hide/show route from MCP | | `mcp_type` | `Optional[MCPType]` | Classification: tool, resource, resource_template | | `methods` | `Optional[list[HTTPMethod]]` | HTTP methods to expose | 资料来源：[openbb_platform/extensions/mcp_server/README.md](openbb_platform/extensions/mcp_server/README.md) ## Navigation and Route Validation Routes use search parameter validation: ```typescript export const Route = createFileRoute("/environments")({ component: EnvironmentsPage, validateSearch: (search: Record) => { return { directory: search.directory as string | undefined, userDataDir: search.userDataDir as string | undefined, }; }, }); ``` ### Route Search Parameters | Parameter | Type | Source | |-----------|------|--------| | `directory` | `string \| undefined` | Installation directory path | | `userDataDir` | `string \| undefined` | User data directory path | --- --- ## Doramagic Pitfall Log Project: OpenBB-finance/OpenBB Summary: Found 29 potential pitfall items; 4 are high/blocking. Highest priority: security_permissions - 来源证据：[FR] Add Bank of Canada Valet API as a new provider extension. ## 1. security_permissions · 来源证据：[FR] Add Bank of Canada Valet API as a new provider extension - Severity: high - Evidence strength: source_linked - Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FR] Add Bank of Canada Valet API as a new provider extension - User impact: 可能影响授权、密钥配置或安全边界。 - Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - Evidence: community_evidence:github | cevd_a8349d4112564c48b29615f3530e81e4 | https://github.com/OpenBB-finance/OpenBB/issues/7490 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。 ## 2. security_permissions · 来源证据：[FR] Add Real-time Cryptocurrency Data Provider Integration - Severity: high - Evidence strength: source_linked - Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FR] Add Real-time Cryptocurrency Data Provider Integration - User impact: 可能影响授权、密钥配置或安全边界。 - Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - Evidence: community_evidence:github | cevd_e1bb7e5c7c0a4dc2bea2a256ed74a0b0 | https://github.com/OpenBB-finance/OpenBB/issues/7177 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。 ## 3. security_permissions · 来源证据：[FR] Signed audit receipts for MCP server tool calls (regulatory compliance) - Severity: high - Evidence strength: source_linked - Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FR] Signed audit receipts for MCP server tool calls (regulatory compliance) - User impact: 可能影响授权、密钥配置或安全边界。 - Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - Evidence: community_evidence:github | cevd_01ea12beef924e199679c6d2d1b91c73 | https://github.com/OpenBB-finance/OpenBB/issues/7455 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。 ## 4. security_permissions · 涉及密钥、隐私或敏感领域 - Severity: high - Evidence strength: source_linked - Finding: 项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。 - User impact: 金融、交易、隐私和密钥场景必须比普通工具更保守。 - Suggested check: 补敏感数据流、密钥存储和权限边界审查。 - Guardrail action: 敏感领域或密钥场景必须保守推荐并要求人工复核。 - Evidence: packet_text.keyword_scan | github_repo:323048702 | https://github.com/OpenBB-finance/OpenBB | matched secret / private key / privacy / trading / finance keyword ## 5. installation · 失败模式：installation: OpenBB Platform v4.5.0 - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: OpenBB Platform v4.5.0 - User impact: Upgrade or migration may change expected behavior: OpenBB Platform v4.5.0 - Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: OpenBB Platform v4.5.0. Context: Observed when using python - Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction. - Evidence: failure_mode_cluster:github_release | fmev_3acb4d0463ffb0d96b55088fc42477e1 | https://github.com/OpenBB-finance/OpenBB/releases/tag/v4.5.0 | OpenBB Platform v4.5.0 ## 6. installation · 失败模式：installation: OpenBB Platform v4.6.0 - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: OpenBB Platform v4.6.0 - User impact: Upgrade or migration may change expected behavior: OpenBB Platform v4.6.0 - Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: OpenBB Platform v4.6.0. Context: Observed when using python - Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction. - Evidence: failure_mode_cluster:github_release | fmev_c32f0b655c075b88a71f35f893ae1f90 | https://github.com/OpenBB-finance/OpenBB/releases/tag/v4.6.0 | OpenBB Platform v4.6.0 ## 7. installation · 失败模式：installation: [Bug] Openbb 4.5.0 cannot import name 'OBBject_EquityInfo' from 'openbb_core.app.provider_int... - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: [Bug] Openbb 4.5.0 cannot import name 'OBBject_EquityInfo' from 'openbb_core.app.provider_interface' - User impact: Developers may fail before the first successful local run: [Bug] Openbb 4.5.0 cannot import name 'OBBject_EquityInfo' from 'openbb_core.app.provider_interface' - Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug] Openbb 4.5.0 cannot import name 'OBBject_EquityInfo' from 'openbb_core.app.provider_interface'. Context: Observed when using python, docker - Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction. - Evidence: failure_mode_cluster:github_issue | fmev_a7115ea0142ee2b52fad8606fc7d47ec | https://github.com/OpenBB-finance/OpenBB/issues/7279 | [Bug] Openbb 4.5.0 cannot import name 'OBBject_EquityInfo' from 'openbb_core.app.provider_interface' ## 8. installation · 失败模式：installation: [Bug] PyWry WebView Fails to Launch on Ubuntu 24.04 - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: [Bug] PyWry WebView Fails to Launch on Ubuntu 24.04 - User impact: Developers may fail before the first successful local run: [Bug] PyWry WebView Fails to Launch on Ubuntu 24.04 - Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug] PyWry WebView Fails to Launch on Ubuntu 24.04. Context: Observed when using python, linux - Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction. - Evidence: failure_mode_cluster:github_issue | fmev_c48a7161974013fd9895ea98894b35bd | https://github.com/OpenBB-finance/OpenBB/issues/7148 | [Bug] PyWry WebView Fails to Launch on Ubuntu 24.04 ## 9. installation · 失败模式：installation: [FR] Add Bank of Canada Valet API as a new provider extension - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: [FR] Add Bank of Canada Valet API as a new provider extension - User impact: Developers may fail before the first successful local run: [FR] Add Bank of Canada Valet API as a new provider extension - Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [FR] Add Bank of Canada Valet API as a new provider extension. Context: Observed when using python - Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction. - Evidence: failure_mode_cluster:github_issue | fmev_3ee0b5efd611f4c6c49174e1a6ba1006 | https://github.com/OpenBB-finance/OpenBB/issues/7490 | [FR] Add Bank of Canada Valet API as a new provider extension ## 10. installation · 来源证据：[Bug] PyWry WebView Fails to Launch on Ubuntu 24.04 - Severity: medium - Evidence strength: source_linked - Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] PyWry WebView Fails to Launch on Ubuntu 24.04 - User impact: 可能阻塞安装或首次运行。 - Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - Evidence: community_evidence:github | cevd_c068fa0d9cac4fb7b74d875b22d312d7 | https://github.com/OpenBB-finance/OpenBB/issues/7148 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 11. installation · 来源证据：[Bug] Widgets not saving their position and size after refresh - Severity: medium - Evidence strength: source_linked - Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] Widgets not saving their position and size after refresh - User impact: 可能增加新用户试用和生产接入成本。 - Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - Evidence: community_evidence:github | cevd_b7792ca1efe649c085e18a8a6be37d49 | https://github.com/OpenBB-finance/OpenBB/issues/7479 | 来源类型 github_issue 暴露的待验证使用条件。 ## 12. configuration · 失败模式：configuration: [FR] Add Real-time Cryptocurrency Data Provider Integration - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: [FR] Add Real-time Cryptocurrency Data Provider Integration - User impact: Developers may misconfigure credentials, environment, or host setup: [FR] Add Real-time Cryptocurrency Data Provider Integration - Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [FR] Add Real-time Cryptocurrency Data Provider Integration. Context: Source discussion did not expose a precise runtime context. - Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction. - Evidence: failure_mode_cluster:github_issue | fmev_45a17b16742dbd042ef1b9e8d373939d | https://github.com/OpenBB-finance/OpenBB/issues/7177 | [FR] Add Real-time Cryptocurrency Data Provider Integration ## 13. configuration · 失败模式：configuration: [FR] Signed audit receipts for MCP server tool calls (regulatory compliance) - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: [FR] Signed audit receipts for MCP server tool calls (regulatory compliance) - User impact: Developers may misconfigure credentials, environment, or host setup: [FR] Signed audit receipts for MCP server tool calls (regulatory compliance) - Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [FR] Signed audit receipts for MCP server tool calls (regulatory compliance). Context: Observed when using node - Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction. - Evidence: failure_mode_cluster:github_issue | fmev_3b139ec9599d5d33e68020e4e802c7e6 | https://github.com/OpenBB-finance/OpenBB/issues/7455 | [FR] Signed audit receipts for MCP server tool calls (regulatory compliance), failure_mode_cluster:github_issue | fmev_cc0ef568cdbda130dfa0c7df4a8f4021 | https://github.com/OpenBB-finance/OpenBB/issues/7455 | [FR] Signed audit receipts for MCP server tool calls (regulatory compliance) ## 14. capability · 能力判断依赖假设 - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: 假设不成立时，用户拿不到承诺的能力。 - Suggested check: 将假设转成下游验证清单。 - Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。 - Evidence: capability.assumptions | github_repo:323048702 | https://github.com/OpenBB-finance/OpenBB | README/documentation is current enough for a first validation pass. ## 15. runtime · 来源证据：ODP Desktop v1.0.2 - Severity: medium - Evidence strength: source_linked - Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：ODP Desktop v1.0.2 - User impact: 可能增加新用户试用和生产接入成本。 - Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - Evidence: community_evidence:github | cevd_cf07c5d467e44c168f2650a3c4404f46 | https://github.com/OpenBB-finance/OpenBB/releases/tag/Open-Data-Platform-v1.0.2 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。 ## 16. maintenance · 失败模式：migration: OpenBB V4.7.0 - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this migration risk before relying on the project: OpenBB V4.7.0 - User impact: Upgrade or migration may change expected behavior: OpenBB V4.7.0 - Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: OpenBB V4.7.0. Context: Observed when using python - Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction. - Evidence: failure_mode_cluster:github_release | fmev_d2f3cd7047c12b8378dbba16461be269 | https://github.com/OpenBB-finance/OpenBB/releases/tag/v4.7.0 | OpenBB V4.7.0 ## 17. maintenance · 维护活跃度未知 - Severity: medium - Evidence strength: source_linked - Finding: 未记录 last_activity_observed。 - User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。 - Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。 - Evidence: evidence.maintainer_signals | github_repo:323048702 | https://github.com/OpenBB-finance/OpenBB | last_activity_observed missing ## 18. security_permissions · 下游验证发现风险项 - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: 下游已经要求复核，不能在页面中弱化。 - Suggested check: 进入安全/权限治理复核队列。 - Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。 - Evidence: downstream_validation.risk_items | github_repo:323048702 | https://github.com/OpenBB-finance/OpenBB | no_demo; severity=medium ## 19. security_permissions · 存在评分风险 - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: 风险会影响是否适合普通用户安装。 - Suggested check: 把风险写入边界卡，并确认是否需要人工复核。 - Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。 - Evidence: risks.scoring_risks | github_repo:323048702 | https://github.com/OpenBB-finance/OpenBB | no_demo; severity=medium ## 20. security_permissions · 来源证据：ODP Desktop v1.0.1 - Severity: medium - Evidence strength: source_linked - Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ODP Desktop v1.0.1 - User impact: 可能增加新用户试用和生产接入成本。 - Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - Evidence: community_evidence:github | cevd_b5b0cf96b9b1456e8192a80e8c9fbcfd | https://github.com/OpenBB-finance/OpenBB/releases/tag/Open-Data-Platform-v1.0.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。 ## 21. security_permissions · 来源证据：OpenBB Platform v4.5.0 - Severity: medium - Evidence strength: source_linked - Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OpenBB Platform v4.5.0 - User impact: 可能影响升级、迁移或版本选择。 - Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - Evidence: community_evidence:github | cevd_ff4708f0690c485c9453a90b7b1f926a | https://github.com/OpenBB-finance/OpenBB/releases/tag/v4.5.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 22. security_permissions · 来源证据：OpenBB Platform v4.6.0 - Severity: medium - Evidence strength: source_linked - Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OpenBB Platform v4.6.0 - User impact: 可能影响升级、迁移或版本选择。 - Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - Evidence: community_evidence:github | cevd_58ecf0b5c49441d7818b4f384f522024 | https://github.com/OpenBB-finance/OpenBB/releases/tag/v4.6.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 23. security_permissions · 来源证据：OpenBB V4.7.0 - Severity: medium - Evidence strength: source_linked - Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OpenBB V4.7.0 - User impact: 可能影响升级、迁移或版本选择。 - Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - Evidence: community_evidence:github | cevd_487435c8c60a497092f647438af74f89 | https://github.com/OpenBB-finance/OpenBB/releases/tag/v4.7.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 24. security_permissions · 来源证据：[Bug] Openbb 4.5.0 cannot import name 'OBBject_EquityInfo' from 'openbb_core.app.provider_interface' - Severity: medium - Evidence strength: source_linked - Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] Openbb 4.5.0 cannot import name 'OBBject_EquityInfo' from 'openbb_core.app.provider_interface' - User impact: 可能影响授权、密钥配置或安全边界。 - Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - Evidence: community_evidence:github | cevd_95461e0340ed4ee5a724d3d6966b0bcf | https://github.com/OpenBB-finance/OpenBB/issues/7279 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 25. capability · 失败模式：capability: [Bug] Widgets not saving their position and size after refresh - Severity: low - Evidence strength: source_linked - Finding: Developers should check this capability risk before relying on the project: [Bug] Widgets not saving their position and size after refresh - User impact: Developers may hit a documented source-backed failure mode: [Bug] Widgets not saving their position and size after refresh - Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug] Widgets not saving their position and size after refresh. Context: Source discussion did not expose a precise runtime context. - Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction. - Evidence: failure_mode_cluster:github_issue | fmev_033f4288382da3f950cd941ddba1d67b | https://github.com/OpenBB-finance/OpenBB/issues/7479 | [Bug] Widgets not saving their position and size after refresh ## 26. runtime · 失败模式：performance: ODP Desktop v1.0.1 - Severity: low - Evidence strength: source_linked - Finding: Developers should check this performance risk before relying on the project: ODP Desktop v1.0.1 - User impact: Upgrade or migration may change expected behavior: ODP Desktop v1.0.1 - Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: ODP Desktop v1.0.1. Context: Observed when using windows, macos - Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction. - Evidence: failure_mode_cluster:github_release | fmev_7f6699c43b69d6dddb40e92afc05c849 | https://github.com/OpenBB-finance/OpenBB/releases/tag/Open-Data-Platform-v1.0.1 | ODP Desktop v1.0.1 ## 27. maintenance · issue/PR 响应质量未知 - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: 用户无法判断遇到问题后是否有人维护。 - Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。 - Guardrail action: issue/PR 响应未知时，必须提示维护风险。 - Evidence: evidence.maintainer_signals | github_repo:323048702 | https://github.com/OpenBB-finance/OpenBB | issue_or_pr_quality=unknown ## 28. maintenance · 发布节奏不明确 - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。 - Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。 - Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。 - Evidence: evidence.maintainer_signals | github_repo:323048702 | https://github.com/OpenBB-finance/OpenBB | release_recency=unknown ## 29. maintenance · 失败模式：maintenance: ODP Desktop v1.0.2 - Severity: low - Evidence strength: source_linked - Finding: Developers should check this maintenance risk before relying on the project: ODP Desktop v1.0.2 - User impact: Upgrade or migration may change expected behavior: ODP Desktop v1.0.2 - Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: ODP Desktop v1.0.2. Context: Observed when using windows - Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction. - Evidence: failure_mode_cluster:github_release | fmev_c611176eed42d564fe51eebbd73c3402 | https://github.com/OpenBB-finance/OpenBB/releases/tag/Open-Data-Platform-v1.0.2 | ODP Desktop v1.0.2