Skip to content

AGENTS.md

Latest commit

 

History

History
41 lines (32 loc) · 3.62 KB

AGENTS.md

File metadata and controls

41 lines (32 loc) · 3.62 KB

XAlpha Agent Platform Guidelines

Welcome to xalpha. This document defines the operational rules for AI agents and contributors.

Core Identity: xalpha is not just a quantitative finance Python library—it is an AI Agent Platform. Agents are expected to use natural language instructions to automatically write xalpha code, perform financial data mining, backtest strategies, and generate analytical reports.

1. The Agentic Workflow

When a user asks for financial analysis or data mining via natural language:

  • Understand the Domain: Use xalpha.universal, xalpha.fundinfo, and xalpha.policy as your primary tools.
  • Write Scripts: Do not just explain how to do it; write and execute Python scripts utilizing xalpha to fetch real data, compute metrics (e.g., XIRR, volatility, correlation), and save results.
  • Be Proactive: If a data source (like Investing.com or Xueqiu) throws an error or requires an ID mapping, autonomously debug and ask the user for the fix plan.
  • Synthesize: Present the final financial analysis clearly to the user, backed by the data you mined.

2. Core Compatibility Contracts

Code written or modified by agents MUST be broadly compatible across the scientific Python ecosystem:

  • Pandas 1.x up to 3.x: Handle frequency format changes ("M" vs "ME"). Always wrap HTML strings in io.StringIO() before pd.read_html(). Use explicitly strict type casting (.astype(float)) to avoid LossySetitemError.
  • Numpy 1.x through 2.x: Avoid deprecated aliases like np.float. Use float or np.float64.

3. Data Scraping & API Resilience

xalpha heavily relies on web scraping (beautifulsoup4) and API endpoints.

  • Robust Parsing: Upstream HTML changes frequently. Avoid fragile exact string matches soup.find(string="text"). Use iterative tag searching and get_text(strip=True).
  • Graceful Fallbacks: If an endpoint fails (e.g., anti-scraping on Investing.com), agents should implement or utilize fallback logic (e.g., JSON APIs vs HTML parsing) and use the rget decorator for network resilience.
  • Never Break the DataFrame: Ensure that any updated scraping logic exactly restores the original DataFrame schema expected by xalpha.

4. Local Caching

xalpha uses local caching (CSV/SQL) for performance.

  • When expanding data classes (e.g., adding a new attribute to fundinfo), agents MUST update both _save_csv/_sql and _fetch_csv/_sql.
  • Handle legacy caches defensively using .get("new_key", "default").

5. Dashboards & Visualization

When generating HTML reports or dashboards (e.g., QDII prediction pages):

  • Rich Aesthetics: Use modern, light-themed layouts, DataTables, and CSS variables. Keep Python focused on data; offload rendering logic to JS/CSS.

6. Code Quality & CI/CD

  • Testing: Ensure tests pass using pytest. Use pytest.importorskip for optional dependencies.
  • Linting: Enforce black formatting and strict adherence to a 10.00/10 Pylint score for the xalpha/ directory.

7. Development Mindset

  1. Atomic & Precise Changes: When fixing bugs in the library itself, make the smallest possible change. Avoid unnecessary refactoring of legacy code.
  2. Data-Driven: When asked to analyze, write the code, run it, and let the data speak.
  3. Self-Healing & Fail-Fast: If you encounter a KeyError or NoneType during data fetching, investigate the upstream response and patch the parsers or input normalizers autonomously. Avoid over-protective code (e.g., blanket try-except or returning empty DataFrames) that swallows original errors. Let it fail naturally so the root cause is visible, then fix it at the source.