cnhkmcp 1.2.9__tar.gz → 1.3.0__tar.gz

{cnhkmcp-1.2.9/cnhkmcp.egg-info → cnhkmcp-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cnhkmcp
-Version: 1.2.9
+Version: 1.3.0
 Summary: A comprehensive Model Context Protocol (MCP) server for quantitative trading platform integration
 Home-page: https://github.com/cnhk/cnhkmcp
 Author: CNHK

{cnhkmcp-1.2.9 → cnhkmcp-1.3.0}/cnhkmcp/__init__.py

@@ -50,7 +50,7 @@ from .untracked.forum_functions import (
     read_full_forum_post
 )
 
-__version__ = "1.2.9"
+__version__ = "1.3.0"
 __author__ = "CNHK"
 __email__ = "cnhk@example.com"
 

cnhkmcp-1.3.0/cnhkmcp/untracked/BRAIN_Alpha_Test_Requirements_and_Tips.md

@@ -0,0 +1,202 @@
+# BRAIN Alpha Submission Tests: Requirements and Improvement Tips
+
+This document compiles the key requirements for passing alpha submission tests on the WorldQuant BRAIN platform, based on official documentation and community experiences from the forum. I've focused on the main tests (Fitness, Sharpe, Turnover, Weight, Sub-universe, and Self-Correlation). For each, I'll outline the thresholds, explanations, and strategies to improve or pass them, drawing from doc pages like "Clear these tests before submitting an Alpha" and forum searches on specific topics.
+
+## Overview
+## What is an Alpha?
+An alpha is a mathematical model or signal designed to predict the future movements of financial instruments (e.g., stocks). On BRAIN, alphas are expressed using the platform's FASTEXPR language and simulated against historical data to evaluate performance. Successful alphas can earn payments and contribute to production strategies.
+
+## What Are Alpha Tests?
+Alphas must pass a series of pre-submission checks (e.g., via the `get_submission_check` tool) to ensure they meet quality thresholds. Key tests include:
+- **Fitness and Sharpe Ratio**: Measures risk-adjusted returns. Must be above cutoffs (e.g., IS Sharpe > 1.25 for some universes).
+- **Correlation Checks**: Against self-alphas and production alphas (threshold ~0.7) to avoid redundancy.
+- **Turnover and Drawdown**: Ensures stability (e.g., low turnover < 250%).
+- **Regional/Universe-Specific**: Vary by settings like USA TOP3000 (D1) or GLB TOP3000.
+- **Other Metrics**: PnL, yearly stats, and risk-neutralized metrics (e.g., RAM, Crowding Risk-Neutralized).
+
+Failing tests result in errors like "Sub-universe Sharpe NaN is not above cutoff" or low fitness.
+
+## General Guidance on Passing Tests
+- **Start Simple**: Use basic operators like `ts_rank`, `ts_corr`, or `neutralize` on price-volume data.
+- **Optimize Settings**: Choose universes like TOP3000 (USA, D1) for easier testing. Neutralize against MARKET or SUBINDUSTRY to reduce correlation.
+- **Improve Metrics**: Apply `ts_decay_linear` for stability, `scale` for normalization, and check with `check_correlation`.
+- **Common Pitfalls**: Avoid high correlation (use `check_correlation`), ensure non-NaN data (e.g., via `ts_backfill`), and target high IR/Fitness.
+- **Resources**: Review operators (e.g., 102 available like `ts_zscore`), documentation (e.g., "Interpret Results" section), and forum posts.
+
+Alphas must pass these in-sample (IS) performance tests to be submitted for out-of-sample (OS) testing. Only submitted alphas contribute to scoring and payments. Tests are run in sequence, and failure messages guide improvements (e.g., "Improve fitness" or "Reduce max correlation").
+
+## Generating and Improving Alpha Ideas: The Conceptual Foundation
+Before diving into metrics and optimizations, strong alphas start with solid ideas rooted in financial theory, market behaviors, or data insights. Improving from an "idea angle" means iterating on the core concept rather than just tweaking parameters—this often leads to more robust alphas that pass tests naturally. Use resources like BRAIN's "Alpha Examples for Beginners" (from Discover BRAIN category) or forum-shared ideas.
+
+### Key Principles
+- **Idea Sources**: Draw from academic papers, economic indicators, or datasets (e.g., sentiment, earnings surprises). Validate ideas with backtests to ensure they generalize.
+- **Iteration**: Start simple, then refine: Add neutralization for correlation, decay for stability, or grouping for diversification.
+- **Avoid Overfitting**: Test ideas across universes/regions; use train/test splits.
+- **Tools**: Explore datasets via Data Explorer; use operators like `ts_rank` for signals.
+
+### Using arXiv for Idea Discovery
+A powerful way to source fresh ideas is through academic papers on arXiv. Use the provided `arxiv_api.py` script (detailed in `arXiv_API_Tool_Manual.md`) to search and download relevant research.
+
+- **Search Example**: Run `python arxiv_api.py "quantitative finance momentum strategies"` to find papers on momentum ideas. Download top results for detailed study.
+- **Integration Tip**: Extract concepts like "earnings surprises" from abstracts, then implement in BRAIN (e.g., using sentiment datasets). This helps generate diverse alphas that pass correlation tests.
+- **Why It Helps**: Papers often provide theoretical backing, reducing overfitting risks when adapting to BRAIN simulations.
+
+Refer to the manual for interactive mode and advanced queries to streamline your research workflow.
+
+### Avoid Mixing Datasets: The ATOM Principle
+When improving an alpha, prioritize modifications that stay within the same dataset as the original. ATOM (Atomic) alphas are those built from a single dataset (excluding permitted grouping fields like country, sector, etc.), which qualify for relaxed submission criteria—focusing on last 2Y Sharpe instead of full IS Ladder tests.
+
+**Why It's Important**:
+- **Robustness**: Mixing datasets can introduce conflicting signals, leading to overfitting and poor out-of-sample performance (forum insights on ATOM alphas).
+- **Submission Benefits**: Single-dataset alphas have easier thresholds (e.g., Delay-1: >1 for last 2Y Sharpe in USA) and may align with themes offering multipliers (up to x1.1 for low-utilization pyramids).
+- **Correlation Control**: ATOM alphas often have lower self-correlation, helping pass tests and diversify your portfolio.
+
+**How to Apply**:
+- Check the alpha's data fields via simulation results or code.
+- Search for improvements in the same dataset first (use Data Explorer).
+- If mixing is needed, verify it doesn't disqualify ATOM status and retest thoroughly.
+
+This principle, highlighted in BRAIN docs and forums, ensures alphas remain "atomic" and competitive.
+
+### Understanding Datafields Before Improvements
+Before optimizing alphas, thoroughly evaluate the datafields involved to address potential issues like unit mismatches or update frequencies. This prevents common pitfalls in tests (e.g., NaN errors, poor sub-universe performance) and ensures appropriate operators are used. Use these 6 methods from the BRAIN exploration guide (adapted for quick simulation in "None" neutralization, decay 0, test_period P0Y0M):
+
+1. **Basic Coverage**: For example, Simulate `datafield` (or `vec_op(datafield)` for vectors). Insight: % coverage = (Long + Short Count) / Universe Size.
+2. **Non-Zero Coverage**: For example, Simulate `datafield != 0 ? 1 : 0`. Insight: Actual meaningful data points.
+3. **Update Frequency**: For example, Simulate `ts_std_dev(datafield, N) != 0 ? 1 : 0` (vary N=5,22,66). Insight: Daily/weekly/monthly/quarterly updates.
+4. **Data Bounds**: For example, Simulate `abs(datafield) > X` (vary X). Insight: Value ranges and normalization.
+5. **Central Tendency**: For example, Simulate `ts_median(datafield, 1000) > X` (vary X). Insight: Typical values over time.
+6. **Distribution**: Simulate `X < scale_down(datafield) && scale_down(datafield) < Y` (vary X/Y between 0-1). Insight: Data spread patterns.
+
+Apply insights to choose operators (e.g., ts_backfill for sparse data, scale for unit issues) and fix problems before improvements.
+
+### Examples from Community and Docs (From Alpha Template Sharing Post)
+These examples are sourced from the forum post on sharing unique alpha ideas and implementations, emphasizing templates that generate robust signals for passing submission tests.
+
+- **Multi-Smoothing Ranking Signal** (User: JB71859): For earnings data, apply double smoothing with ranking and statistical ops. Example: `ts_mean(ts_rank(earnings_field, decay1), decay2)`. First ts_rank normalizes values over time (pre-processing), then ts_mean smooths for stable signals (main signal). Helps improve fitness and reduce turnover by lowering noise; produced 3 ATOM alphas after 2000 simulations.
+- **Momentum Divergence Factor** (User: YK49234): Capture divergence between short and long-term momentum on the same field. Example: `ts_delta(ts_zscore(field, short_window), short_window) - ts_delta(ts_zscore(field, long_window), long_window)`. Processes data with z-scoring for normalization, then delta/mean for change detection (main signal). Boosts Sharpe by highlighting momentum shifts; yielded 4 submitable alphas from 20k tests with ~5% signal rate.
+- **Network Factor Difference Momentum** (User: JR23144): Compute differences in oth455 PCA factors for 'imbalance' signals, then apply time series ops. Example: `ts_sum(oth455_fact2 - oth455_fact1, 240)`. Math op creates difference (pre-processing), ts op captures persistence (main signal). Enhances correlation passing via unique network insights; effective in EUR for low-fitness but high-margin alphas.
+
+These community-shared templates promote diverse, ATOM-friendly ideas that align with test requirements like low correlation and high robustness.
+
+### Official BRAIN Examples
+Draw from BRAIN's structured tutorials for foundational ideas:
+
+- **Beginner Level** ([19 Alpha Examples](https://platform.worldquantbrain.com/learn/documentation/create-alphas/19-alpha-examples)): Start with simple price-based signals. Example: `ts_rank(close, 20)` – Ranks closing prices over 20 days to capture momentum. Improve by adding neutralization: `neutralize(ts_rank(close, 20), "MARKET")` to reduce market bias and pass correlation tests.
+  
+- **Bronze Level** ([Sample Alpha Concepts](https://platform.worldquantbrain.com/learn/documentation/create-alphas/sample-alpha-concepts)): Incorporate multiple data fields. Example: `ts_corr(close, volume, 10)` – Correlation between price and volume over 10 days. Enhance fitness by decaying: `ts_decay_linear(ts_corr(close, volume, 10), 5)` for smoother signals.
+
+- **Silver Level** ([Example Expression Alphas](https://platform.worldquantbrain.com/learn/documentation/create-alphas/example-expression-alphas)): Advanced combinations. Example: `scale(ts_rank(ts_delay(vwap, 1) / vwap, 252))` – Normalized 1-year price change. Iterate by adding groups: `group_zscore(scale(ts_rank(ts_delay(vwap, 1) / vwap, 252)), "INDUSTRY")` to improve sub-universe robustness.
+
+These examples show how starting with a core idea (e.g., momentum) and layering improvements (e.g., neutralization, decay) can help pass tests like fitness and sub-universe.
+
+## 1. Fitness
+### Requirements
+- At least "Average": Greater than 1.3 for Delay-0 or Greater than 1 for Delay-1.
+- Fitness = Sharpe * sqrt(abs(Returns) / max(Turnover, 0.125)).
+- Ratings: Spectacular (>2.5 Delay-1 or >3.25 Delay-0), Excellent (>2 or >2.6), etc.
+
+### Explanation
+Fitness balances Sharpe, Returns, and Turnover. High fitness indicates a robust alpha. It's a key metric for alpha quality.
+
+### Tips to Improve
+- **From Docs**: Increase Sharpe/Returns and reduce Turnover. Optimize by balancing these—improving one may hurt another. Aim for upward PnL trends with minimal drawdown.
+- **Forum Experiences** (from searches on "increase fitness alpha"):
+  - Use group operators (e.g., with pv13) to boost fitness without overcomplicating expressions.
+  - Screen alphas with author_fitness >=2 or similar in competitions like Super Alpha.
+  - Manage alphas via databases or tags; query for high-fitness ones (e.g., via API with fitness filters).
+  - In hand-crafting alphas, iteratively add operators like left_tail and group to push fitness over thresholds, but watch for overfitting.
+  - Community shares: High-fitness alphas (e.g., >2) often come from multi-factor fusions or careful data field selection.
+
+## 2. Sharpe Ratio
+### Requirements
+- Greater than 2 for Delay-0 or Greater than 1.25 for Delay-1.
+- Sharpe = sqrt(252) * IR, where IR = mean(PnL) / stdev(PnL).
+
+### Explanation
+Measures risk-adjusted returns. Higher Sharpe means more consistent performance. For GLB alphas, additional sub-geography Sharpes (>=1 for AMER, APAC, EMEA).
+
+### Tips to Improve
+- **From Docs**: Focus on consistent PnL with low volatility. Use visualization to ensure upward trends. For sub-geography, incorporate region-specific signals (e.g., earnings for AMER, microstructure for APAC).
+- **Forum Experiences** (from searches on "improve Sharpe ratio alpha"):
+  - Decay signals separately for liquid/non-liquid stocks (e.g., ts_decay_linear with rank(volume*close)).
+  - Avoid size-related multipliers (e.g., rank(-assets)) that shift weights to illiquid stocks.
+  - Check yearly Sharpe data via API and store in databases for analysis.
+  - In templates like CCI-based, combine with z-score and delay to stabilize Sharpe.
+  - Community tip: Prune low-Sharpe alphas in pools using weighted methods to retain high-Sharpe ones.
+  - **Flipping Negative Sharpe**: For non-CHN regions, if an alpha shows negative Sharpe (e.g., -1 to -2), add a minus sign to the expression (e.g., `-original_expression`) to flip it positive. This preserves the signal while improving metrics; verify it doesn't introduce correlation issues.
+
+## 3. Turnover
+### Requirements
+- 1% < Turnover < 70%.
+- Turnover = Dollar trading volume / Book size.
+
+### Explanation
+Indicates trading frequency. Low turnover reduces costs; extremes fail submission.
+
+### Tips to Improve
+- **From Docs**: Aim for balanced trading—too low means inactive, too high means over-trading.
+- **Forum Experiences**: (Note: Specific turnover searches weren't direct, but tied to fitness/Sharpe improvements)
+  - Use decay functions to smooth signals, reducing unnecessary trades.
+  - In multi-alpha simulations, filter by turnover thresholds in code to pre-select candidates.
+
+## 4. Weight Test
+### Requirements
+- Max weight in any stock <10%.
+- Sufficient instruments assigned weight (varies by universe, e.g., TOP3000).
+
+### Explanation
+Ensures diversification; fails if concentrated or too few stocks weighted.
+
+### Tips to Improve
+- **From Docs**: Avoid expressions that overly concentrate weights. Assign weights broadly after simulation start.
+- **Forum Experiences**: (Limited direct posts; inferred from general submission tips)
+  - Use neutralization (e.g., market) to distribute weights evenly.
+  - Check via simulation stats; adjust with rank or scale operators.
+
+## 5. Sub-universe Test
+### Requirements
+- Sub-universe Sharpe >= 0.75 * sqrt(subuniverse_size / alpha_universe_size) * alpha_sharpe.
+- Ensures robustness in more liquid sub-universes (e.g., TOP1000 for TOP3000).
+
+### Explanation
+Tests if alpha performs in liquid stocks, avoiding over-reliance on illiquid ones.
+
+### Tips to Improve
+- **From Docs**: Avoid size-related multipliers. Decay liquid/non-liquid parts separately (e.g., ts_decay_linear(signal,5)*rank(volume*close) + ts_decay_linear(signal,10)*(1-rank(volume*close))). From this example, we can see that the signal can be inflated by different weights for different parts of an datafield.
+  - Step-by-step improvements; discard non-robust signals.
+- **Forum Experiences**: (From "how to pass submission tests")
+  - Improve overall Sharpe first, as it scales the threshold.
+  - Use pasteurize to handle NaNs and ensure even distribution.
+
+## 6. Self-Correlation
+### Requirements
+- <0.7 PnL correlation with own submitted alphas.
+- Or Sharpe at least 10% greater than correlated alphas.
+
+### Explanation
+Promotes diversity; based on 4-year PnL window. Allows improvements if new alpha is significantly better.
+
+### Tips to Improve
+- **From Docs**: Submit diverse ideas. Use correlation table in results to identify issues.
+- **Forum Experiences** (from searches on "reduce correlation self alphas"):
+  - Local computation of self-correlation (e.g., via PnL matrices) to pre-filter before submission.
+  - Code optimizations: Prune high-correlation alphas, use clustering or weighted pruning (e.g., Sharpe-weighted) to retain diverse sets.
+  - Handle negatives: Transform negatively correlated alphas (e.g., in China market) by inversion or adjustments.
+  - Scripts for batch checking: Use machine_lib modifications to print correlations and pyramid info.
+  - Community shares: Differences between local and platform calculations (e.g., due to NaN handling); align by using full PnL data.
+
+### Evaluating Whole Alpha Quality
+Before final submission, perform these checks on simulation results:
+
+- **Yearly Stats Quality Check**: Review yearly statistics. If records are missing for >5 years, it indicates low data quality (e.g., sparse coverage). Fix with ts_backfill, data selection, or alternative fields to ensure robust performance across tests.
+
+This complements per-test improvements by validating overall alpha reliability.
+
+## General Advice
+- Start with broad simulations, narrow based on stats.
+- Use tools like check_submission API for pre-checks.
+- Forum consensus: Automate with Python scripts for efficiency (e.g., threading for simulates, databases for alpha management).
+- Risks: Overfitting in manual tweaks; validate with train/test splits.
+
+This guide is based on tool-gathered data. For updates, check BRAIN docs or forum.

cnhkmcp-1.3.0/cnhkmcp/untracked/arXiv_API_Tool_Manual.md

@@ -0,0 +1,490 @@
+# 🔍 arXiv Paper Search & Download Tool
+
+A comprehensive Python tool for searching, analyzing, and downloading research papers from arXiv using their public API. Perfect for researchers, students, and anyone interested in academic papers.
+
+## 📋 Table of Contents
+
+- [Features](#-features)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Usage Modes](#-usage-modes)
+- [API Functions](#-api-functions)
+- [Examples](#-examples)
+- [Advanced Usage](#-advanced-usage)
+- [Troubleshooting](#-troubleshooting)
+
+## ✨ Features
+
+- **🔍 Smart Search**: Search arXiv papers by title, author, abstract, or any keyword
+- **📥 Smart Download**: Download PDFs with automatic filename renaming to paper titles
+- **📊 Result Parsing**: Automatically extract structured information (title, authors, abstract, ID)
+- **🖥️ Interactive Mode**: Command-line interface for easy searching and downloading
+- **⚡ Batch Operations**: Search multiple papers and download in sequence
+- **📈 Academic Research**: Perfect for literature reviews and research discovery
+- **🔄 Auto-Rename**: Downloaded files are automatically named using paper titles instead of cryptic IDs
+
+## 🚀 Installation
+
+### Prerequisites
+- Python 3.6 or higher
+- Internet connection for API access
+
+### Install Dependencies
+```bash
+pip install requests
+```
+
+### Download the Script
+```bash
+# Clone or download arxiv_api.py to your working directory
+```
+
+## 🎯 Quick Start
+
+### Basic Search
+```bash
+python arxiv_api.py "machine learning"
+```
+
+### Search with Custom Results
+```bash
+python arxiv_api.py "quantum computing" -n 10
+```
+
+### Search and Download First Result
+```bash
+python arxiv_api.py "deep learning" -d
+```
+
+### Interactive Mode
+```bash
+python arxiv_api.py -i
+```
+
+### Download Paper by ID (with auto-rename)
+```bash
+# In interactive mode:
+# 📚 arxiv> download 2502.05218v1
+# This will automatically rename the file to the paper's title
+```
+
+## 🎮 Usage Modes
+
+### 1. Command Line Mode
+Direct search queries from the command line.
+
+**Syntax:**
+```bash
+python arxiv_api.py [query] [options]
+```
+
+**Options:**
+- `-n, --max_results`: Maximum number of results (default: 5)
+- `-d, --download`: Download the first result automatically
+- `-i, --interactive`: Start interactive mode
+- `-h, --help`: Show help message
+
+### 2. Interactive Mode
+Interactive command-line interface for multiple operations.
+
+**Commands:**
+- `search <query> [max_results]`: Search for papers
+- `download <paper_id>`: Download a specific paper (with auto-rename)
+- `help`: Show available commands
+- `quit/exit`: Exit the program
+
+## 🔧 API Functions
+
+### Core Functions
+
+#### `search_arxiv(query, max_results=10)`
+Searches arXiv for papers using the public API.
+
+**Parameters:**
+- `query` (str): Search query string
+- `max_results` (int): Maximum number of results (default: 10)
+
+**Returns:**
+- `str`: XML response from arXiv API
+
+**Example:**
+```python
+from arxiv_api import search_arxiv
+
+results = search_arxiv("artificial intelligence", max_results=5)
+```
+
+#### `get_paper_metadata(paper_id)`
+Fetches paper metadata directly from arXiv API using paper ID.
+
+**Parameters:**
+- `paper_id` (str): arXiv paper ID (e.g., "2502.05218v1")
+
+**Returns:**
+- `dict`: Paper information dictionary, or `None` if not found
+
+**Example:**
+```python
+from arxiv_api import get_paper_metadata
+
+paper_info = get_paper_metadata("2502.05218v1")
+if paper_info:
+    print(f"Title: {paper_info['title']}")
+    print(f"Authors: {', '.join(paper_info['authors'])}")
+```
+
+#### `download_paper(paper_id, output_dir=".", paper_title=None)`
+Downloads a specific paper by its arXiv ID and automatically renames it to the paper title.
+
+**Parameters:**
+- `paper_id` (str): arXiv paper ID (e.g., "2502.05218v1")
+- `output_dir` (str): Output directory (default: current directory)
+- `paper_title` (str): Paper title for filename (optional, will be fetched automatically if not provided)
+
+**Returns:**
+- `str`: File path of downloaded PDF, or `None` if failed
+
+**Features:**
+- **Auto-rename**: Automatically renames downloaded files to paper titles
+- **Smart cleaning**: Removes special characters and limits filename length
+- **Fallback**: Uses paper ID if title is unavailable
+
+**Example:**
+```python
+from arxiv_api import download_paper
+
+# Download with automatic title fetching and renaming
+filepath = download_paper("2502.05218v1")
+
+# Download with custom title
+filepath = download_paper("2502.05218v1", paper_title="My Custom Title")
+```
+
+#### `parse_search_results(xml_content)`
+Parses XML search results and extracts structured paper information.
+
+**Parameters:**
+- `xml_content` (str): XML response from arXiv API
+
+**Returns:**
+- `list`: List of dictionaries containing paper information
+
+**Paper Information Structure:**
+```python
+{
+    'title': 'Paper Title',
+    'authors': ['Author 1', 'Author 2'],
+    'abstract': 'Paper abstract...',
+    'paper_id': '2502.05218v1',
+    'published': '2025-02-05T12:37:15Z'
+}
+```
+
+#### `search_and_download(query, max_results=5, download_first=False)`
+Combined function that searches for papers and optionally downloads the first result.
+
+**Parameters:**
+- `query` (str): Search query string
+- `max_results` (int): Maximum number of results (default: 5)
+- `download_first` (bool): Whether to download first result (default: False)
+
+**Example:**
+```python
+from arxiv_api import search_and_download
+
+# Search and display results only
+search_and_download("machine learning", max_results=3)
+
+# Search and download first result (with auto-rename)
+search_and_download("deep learning", max_results=5, download_first=True)
+```
+
+### Interactive Mode Functions
+
+#### `interactive_mode()`
+Starts the interactive command-line interface.
+
+**Features:**
+- Command history
+- Error handling
+- User-friendly prompts
+- Multiple search sessions
+- **Smart download with auto-rename**
+
+## 📚 Examples
+
+### Example 1: Basic Paper Search
+```bash
+# Search for machine learning papers
+python arxiv_api.py "machine learning"
+
+# Output:
+# Searching arXiv for: 'machine learning'
+# --------------------------------------------------
+# Found 5 papers:
+# 
+# 1. Title: Introduction to Machine Learning
+#    Authors: John Doe, Jane Smith
+#    Paper ID: 2103.12345
+#    Published: 2021-03-15T10:30:00Z
+#    Abstract: This paper introduces...
+```
+
+### Example 2: Search with Custom Results
+```bash
+# Get 10 results for quantum computing
+python arxiv_api.py "quantum computing" -n 10
+```
+
+### Example 3: Search and Download (with auto-rename)
+```bash
+# Search for papers and download the first one
+python arxiv_api.py "artificial intelligence" -d
+# Downloaded file will be automatically renamed to the paper title
+```
+
+### Example 4: Interactive Mode with Smart Download
+```bash
+python arxiv_api.py -i
+
+# 📚 arxiv> search blockchain finance 5
+# 📚 arxiv> download 2502.05218v1
+# Fetching paper information for 2502.05218v1...
+# Found paper: FactorGCL: A Hypergraph-Based Factor Model...
+# Downloaded: .\FactorGCL_A_Hypergraph-Based_Factor_Model...pdf
+# 📚 arxiv> help
+# 📚 arxiv> quit
+```
+
+### Example 5: Python Script Integration
+```python
+from arxiv_api import search_and_download, download_paper, get_paper_metadata
+
+# Search for papers on a specific topic
+search_and_download("quantitative finance China", max_results=3)
+
+# Download a specific paper with auto-rename
+download_paper("2502.05218v1")
+
+# Get paper metadata
+paper_info = get_paper_metadata("2502.05218v1")
+if paper_info:
+    print(f"Title: {paper_info['title']}")
+```
+
+## 🔍 Advanced Usage
+
+### Smart Download Features
+
+#### Automatic Filename Generation
+```python
+from arxiv_api import download_paper
+
+# The tool automatically:
+# 1. Fetches paper metadata
+# 2. Extracts the title
+# 3. Cleans the title for filename use
+# 4. Downloads and renames the file
+
+# Example output filename:
+# "FactorGCL_A_Hypergraph-Based_Factor_Model_with_Temporal_Residual_Contrastive_Learning_for_Stock_Returns_Prediction.pdf"
+```
+
+#### Custom Search Queries
+
+##### Field-Specific Searches
+```bash
+# Search by author
+python arxiv_api.py "au:Yann LeCun"
+
+# Search by title
+python arxiv_api.py "ti:deep learning"
+
+# Search by abstract
+python arxiv_api.py "abs:neural networks"
+
+# Search by category
+python arxiv_api.py "cat:cs.AI"
+```
+
+##### Complex Queries
+```bash
+# Multiple terms
+python arxiv_api.py "machine learning AND neural networks"
+
+# Exclude terms
+python arxiv_api.py "deep learning NOT reinforcement"
+
+# Date range
+python arxiv_api.py "machine learning AND submittedDate:[20230101 TO 20231231]"
+```
+
+### Batch Operations
+
+#### Download Multiple Papers with Auto-Rename
+```python
+from arxiv_api import search_arxiv, parse_search_results, download_paper
+
+# Search for papers
+query = "quantum computing"
+results = search_arxiv(query, max_results=10)
+papers = parse_search_results(results)
+
+# Download all papers (each will be automatically renamed)
+for paper in papers:
+    paper_id = paper.get('paper_id')
+    if paper_id:
+        download_paper(paper_id, output_dir="./quantum_papers")
+```
+
+#### Custom Output Formatting
+```python
+from arxiv_api import search_and_download
+
+# Custom display function
+def custom_display(papers):
+    for i, paper in enumerate(papers, 1):
+        print(f"📄 Paper {i}: {paper['title']}")
+        print(f"👥 Authors: {', '.join(paper['authors'])}")
+        print(f"🆔 ID: {paper['paper_id']}")
+        print(f"📅 Date: {paper['published']}")
+        print(f"📝 Abstract: {paper['abstract'][:150]}...")
+        print("-" * 80)
+
+# Use custom display
+search_and_download("blockchain", max_results=3)
+```
+
+## 🛠️ Troubleshooting
+
+### Common Issues
+
+#### 1. No Results Found
+**Problem:** Search returns no papers
+**Solution:** 
+- Check spelling and use broader terms
+- Try different keyword combinations
+- Verify internet connection
+
+#### 2. Download Failed
+**Problem:** Paper download fails
+**Solution:**
+- Verify paper ID is correct
+- Check if paper exists on arXiv
+- Ensure write permissions in output directory
+
+#### 3. API Rate Limiting
+**Problem:** Too many requests
+**Solution:**
+- Wait between requests
+- Reduce batch size
+- Use interactive mode for multiple searches
+
+#### 4. XML Parsing Errors
+**Problem:** Error parsing search results
+**Solution:**
+- Check internet connection
+- Verify API response format
+- Update the script if needed
+
+#### 5. Filename Too Long
+**Problem:** Generated filename exceeds system limits
+**Solution:**
+- The tool automatically limits filenames to 100 characters
+- Special characters are automatically cleaned
+- Fallback to paper ID if title is unavailable
+
+### Error Messages
+
+```
+Error: Failed to download paper 2502.05218v1
+```
+- Paper ID may not exist
+- Network connection issue
+- arXiv server problem
+
+```
+Error parsing XML: ...
+```
+- Malformed API response
+- Network interruption
+- API format change
+
+```
+Could not find paper information for 2502.05218v1
+```
+- Paper ID may be invalid
+- arXiv API issue
+- Network connectivity problem
+
+## 📖 API Reference
+
+### arXiv API Endpoints
+- **Search API**: `http://export.arxiv.org/api/query`
+- **Metadata API**: `http://export.arxiv.org/api/query?id_list={paper_id}`
+- **Documentation**: https://arxiv.org/help/api
+- **Rate Limits**: Be respectful, avoid excessive requests
+
+### Data Fields Available
+- **Title**: Paper title
+- **Authors**: List of author names
+- **Abstract**: Paper abstract
+- **Paper ID**: Unique arXiv identifier
+- **Published Date**: Publication timestamp
+- **Categories**: arXiv subject categories
+
+### Paper ID Format
+- **Format**: `YYMM.NNNNNvN`
+- **Example**: `2502.05218v1`
+- **Download URL**: `https://arxiv.org/pdf/{paper_id}.pdf`
+
+### Smart Download Features
+- **Automatic Metadata Fetching**: Gets paper information before download
+- **Intelligent Filename Generation**: Converts paper titles to valid filenames
+- **Character Cleaning**: Removes special characters and spaces
+- **Length Limiting**: Ensures filenames don't exceed system limits
+- **Fallback Naming**: Uses paper ID if title is unavailable
+
+## 🤝 Contributing
+
+### Adding New Features
+1. Fork the repository
+2. Create a feature branch
+3. Implement your changes
+4. Add tests and documentation
+5. Submit a pull request
+
+### Reporting Issues
+- Check existing issues first
+- Provide detailed error messages
+- Include system information
+- Describe steps to reproduce
+
+## 📄 License
+
+This project is open source and available under the MIT License.
+
+## 🙏 Acknowledgments
+
+- **arXiv**: For providing the public API
+- **Python Community**: For excellent libraries and tools
+- **Researchers**: For contributing to open science
+
+## 📞 Support
+
+### Getting Help
+- Check this documentation first
+- Review the examples section
+- Search existing issues
+- Create a new issue for bugs
+
+### Useful Links
+- [arXiv Official Site](https://arxiv.org/)
+- [arXiv API Documentation](https://arxiv.org/help/api)
+- [Python Requests Library](https://requests.readthedocs.io/)
+
+---
+
+**Happy Researching! 🎓📚**
+
+*This tool makes academic research more accessible and efficient. Use it responsibly and respect arXiv's terms of service.*

cnhkmcp-1.3.0/cnhkmcp/untracked/arxiv_api.py

@@ -0,0 +1,229 @@
+import requests
+import xml.etree.ElementTree as ET
+import os
+import sys
+import argparse
+
+def search_arxiv(query, max_results=10):
+    """Search arXiv for papers"""
+    base_url = "http://export.arxiv.org/api/query"
+    params = {
+        'search_query': query,
+        'start': 0,
+        'max_results': max_results
+    }
+    
+    response = requests.get(base_url, params=params)
+    return response.text
+
+def get_paper_metadata(paper_id):
+    """Get paper metadata directly from arXiv API"""
+    try:
+        # Use the arXiv API to get paper metadata
+        metadata_url = f"http://export.arxiv.org/api/query?id_list={paper_id}"
+        response = requests.get(metadata_url)
+        
+        if response.status_code == 200:
+            papers = parse_search_results(response.text)
+            if papers and len(papers) > 0:
+                return papers[0]
+        return None
+    except Exception as e:
+        print(f"Error fetching paper metadata: {e}")
+        return None
+
+def download_paper(paper_id, output_dir=".", paper_title=None):
+    """Download a paper by its ID and rename it to the paper title"""
+    pdf_url = f"https://arxiv.org/pdf/{paper_id}.pdf"
+    response = requests.get(pdf_url)
+    
+    if response.status_code == 200:
+        # Create filename from paper title if available, otherwise use paper ID
+        if paper_title:
+            # Clean the title for filename (remove special characters, limit length)
+            clean_title = "".join(c for c in paper_title if c.isalnum() or c in (' ', '-', '_')).rstrip()
+            clean_title = clean_title.replace(' ', '_')[:100]  # Limit length to 100 chars
+            filename = f"{clean_title}.pdf"
+        else:
+            filename = f"{paper_id}.pdf"
+        
+        filepath = os.path.join(output_dir, filename)
+        
+        with open(filepath, 'wb') as f:
+            f.write(response.content)
+        print(f"Downloaded: {filepath}")
+        return filepath
+    else:
+        print(f"Failed to download paper {paper_id}")
+        return None
+
+def parse_search_results(xml_content):
+    """Parse XML search results and extract paper information"""
+    try:
+        root = ET.fromstring(xml_content)
+        papers = []
+        
+        # Find all entry elements
+        for entry in root.findall('.//{http://www.w3.org/2005/Atom}entry'):
+            paper_info = {}
+            
+            # Extract title
+            title_elem = entry.find('.//{http://www.w3.org/2005/Atom}title')
+            if title_elem is not None:
+                paper_info['title'] = title_elem.text.strip()
+            
+            # Extract authors
+            authors = []
+            for author in entry.findall('.//{http://www.w3.org/2005/Atom}author'):
+                name_elem = author.find('.//{http://www.w3.org/2005/Atom}name')
+                if name_elem is not None:
+                    authors.append(name_elem.text.strip())
+            paper_info['authors'] = authors
+            
+            # Extract abstract
+            summary_elem = entry.find('.//{http://www.w3.org/2005/Atom}summary')
+            if summary_elem is not None:
+                paper_info['abstract'] = summary_elem.text.strip()
+            
+            # Extract paper ID from the id field
+            id_elem = entry.find('.//{http://www.w3.org/2005/Atom}id')
+            if id_elem is not None:
+                # Extract ID from URL like "http://arxiv.org/abs/2103.12345"
+                paper_id = id_elem.text.split('/')[-1]
+                paper_info['paper_id'] = paper_id
+            
+            # Extract published date
+            published_elem = entry.find('.//{http://www.w3.org/2005/Atom}published')
+            if published_elem is not None:
+                paper_info['published'] = published_elem.text.strip()
+            
+            papers.append(paper_info)
+        
+        return papers
+    except ET.ParseError as e:
+        print(f"Error parsing XML: {e}")
+        return []
+
+def search_and_download(query, max_results=5, download_first=False):
+    """Search for papers and optionally download the first result"""
+    print(f"Searching arXiv for: '{query}'")
+    print("-" * 50)
+    
+    # Search for papers
+    results = search_arxiv(query, max_results)
+    papers = parse_search_results(results)
+    
+    if not papers:
+        print("No papers found.")
+        return
+    
+    # Display search results
+    print(f"Found {len(papers)} papers:\n")
+    for i, paper in enumerate(papers, 1):
+        print(f"{i}. Title: {paper.get('title', 'N/A')}")
+        print(f"   Authors: {', '.join(paper.get('authors', ['N/A']))}")
+        print(f"   Paper ID: {paper.get('paper_id', 'N/A')}")
+        print(f"   Published: {paper.get('published', 'N/A')}")
+        print(f"   Abstract: {paper.get('abstract', 'N/A')[:200]}...")
+        print()
+    
+    # Optionally download first paper
+    if download_first and papers:
+        first_paper = papers[0]
+        paper_id = first_paper.get('paper_id')
+        paper_title = first_paper.get('title')
+        if paper_id:
+            print(f"Downloading first paper: {paper_id}")
+            download_paper(paper_id, paper_title=paper_title)
+        else:
+            print("Could not extract paper ID for download")
+
+def interactive_mode():
+    """Interactive mode for searching arXiv"""
+    print("🔍 arXiv Paper Search Tool")
+    print("=" * 40)
+    print("Commands:")
+    print("  search <query> [max_results] - Search for papers")
+    print("  download <paper_id> - Download a specific paper")
+    print("  help - Show this help message")
+    print("  quit/exit - Exit the program")
+    print()
+    
+    while True:
+        try:
+            command = input("📚 arxiv> ").strip()
+            
+            if not command:
+                continue
+                
+            parts = command.split()
+            cmd = parts[0].lower()
+            
+            if cmd in ['quit', 'exit', 'q']:
+                print("Goodbye! 👋")
+                break
+                
+            elif cmd == 'help':
+                print("Commands:")
+                print("  search <query> [max_results] - Search for papers")
+                print("  download <paper_id> - Download a specific paper")
+                print("  help - Show this help message")
+                print("  quit/exit - Exit the program")
+                print()
+                
+            elif cmd == 'search':
+                if len(parts) < 2:
+                    print("Usage: search <query> [max_results]")
+                    continue
+                    
+                query = ' '.join(parts[1:-1]) if len(parts) > 2 else parts[1]
+                max_results = int(parts[-1]) if len(parts) > 2 and parts[-1].isdigit() else 5
+                
+                search_and_download(query, max_results, download_first=False)
+                
+            elif cmd == 'download':
+                if len(parts) < 2:
+                    print("Usage: download <paper_id>")
+                    continue
+                    
+                paper_id = parts[1]
+                # Get paper metadata first
+                print(f"Fetching paper information for {paper_id}...")
+                paper_info = get_paper_metadata(paper_id)
+                
+                if paper_info and paper_info.get('title'):
+                    paper_title = paper_info['title']
+                    print(f"Found paper: {paper_title}")
+                    download_paper(paper_id, paper_title=paper_title)
+                else:
+                    print(f"Could not find paper information for {paper_id}")
+                    print("Downloading with paper ID as filename...")
+                    download_paper(paper_id)
+                
+            else:
+                print(f"Unknown command: {cmd}")
+                print("Type 'help' for available commands")
+                
+        except KeyboardInterrupt:
+            print("\nGoodbye! 👋")
+            break
+        except Exception as e:
+            print(f"Error: {e}")
+
+# Example usage
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description='Search and download papers from arXiv')
+    parser.add_argument('query', nargs='?', help='Search query')
+    parser.add_argument('-n', '--max_results', type=int, default=5, help='Maximum number of results (default: 5)')
+    parser.add_argument('-d', '--download', action='store_true', help='Download the first result')
+    parser.add_argument('-i', '--interactive', action='store_true', help='Start interactive mode')
+    
+    args = parser.parse_args()
+    
+    if args.interactive:
+        interactive_mode()
+    elif args.query:
+        search_and_download(args.query, args.max_results, args.download)
+    else:
+        # Default behavior - start interactive mode
+        interactive_mode()

{cnhkmcp-1.2.9 → cnhkmcp-1.3.0/cnhkmcp.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cnhkmcp
-Version: 1.2.9
+Version: 1.3.0
 Summary: A comprehensive Model Context Protocol (MCP) server for quantitative trading platform integration
 Home-page: https://github.com/cnhk/cnhkmcp
 Author: CNHK

{cnhkmcp-1.2.9 → cnhkmcp-1.3.0}/cnhkmcp.egg-info/SOURCES.txt

@@ -12,7 +12,10 @@ cnhkmcp.egg-info/not-zip-safe
 cnhkmcp.egg-info/requires.txt
 cnhkmcp.egg-info/top_level.txt
 cnhkmcp/untracked/BRAIN_6_Tips_Datafield_Exploration_Guide.md
+cnhkmcp/untracked/BRAIN_Alpha_Test_Requirements_and_Tips.md
 cnhkmcp/untracked/Dataset_Exploration_Expert_Manual.md
+cnhkmcp/untracked/arXiv_API_Tool_Manual.md
+cnhkmcp/untracked/arxiv_api.py
 cnhkmcp/untracked/daily_report_workflow.md
 cnhkmcp/untracked/forum_functions.py
 cnhkmcp/untracked/platform_functions.py

{cnhkmcp-1.2.9 → cnhkmcp-1.3.0}/setup.py

@@ -13,7 +13,7 @@ def read_requirements():
 
 setup(
     name="cnhkmcp",
-    version="1.2.9",
+    version="1.3.0",
     author="CNHK",
     author_email="cnhk@example.com",
     description="A comprehensive Model Context Protocol (MCP) server for quantitative trading platform integration",