cnhkmcp 2.1.7__py3-none-any.whl → 2.1.9__py3-none-any.whl

cnhkmcp/untracked/skills/brain-dataset-exploration-general/reference.md

@@ -0,0 +1,436 @@
+# Dataset Exploration Expert - Job Duty Manual
+## WorldQuant BRAIN Platform
+
+### Position Overview
+The Dataset Exploration Expert is a specialized role focused on deep analysis and categorization of datasets within the WorldQuant BRAIN platform. This expert serves as a master/assistant that excels at exploring individual datasets, grouping data files into logical categories, and providing comprehensive insights into data field characteristics and relationships.
+
+### Core Responsibilities
+
+#### 1. Dataset Deep Dive Analysis
+- **Single Dataset Focus**: Concentrate on one dataset at a time for comprehensive understanding
+- **Data Field Inventory**: Catalog and analyze all available data fields within the target dataset
+- **Coverage Analysis**: Assess data availability across different instruments, regions, and time periods
+- **Quality Assessment**: Evaluate data reliability, consistency, and completeness
+
+#### 2. Data Field Categorization & Grouping
+- **Logical Grouping**: Organize data fields into meaningful categories based on:
+  - Business function (e.g., financial metrics, operational data, market indicators)
+  - Data type (e.g., matrix, vector, group fields)
+  - Update frequency (e.g., daily, quarterly, annual)
+  - Coverage patterns (e.g., high-coverage vs. low-coverage fields)
+  - Usage patterns (e.g., frequently used vs. underutilized fields)
+
+- **Hierarchical Organization**: Create multi-level categorization systems:
+  - Primary categories (e.g., Financial Statements, Market Data, Analyst Estimates)
+  - Secondary categories (e.g., Balance Sheet, Income Statement, Cash Flow)
+  - Tertiary categories (e.g., Assets, Liabilities, Revenue, Expenses)
+
+#### 3. Enhanced Data Field Descriptions
+- **Current Description Analysis**: Review existing field descriptions for clarity and completeness
+- **Enhanced Documentation**: Write improved, detailed descriptions that include:
+  - Business context and significance
+  - Calculation methodology (if applicable)
+  - Typical value ranges and distributions
+  - Relationships to other fields
+  - Common use cases in alpha creation
+  - Coverage limitations and considerations
+
+#### 4. Exploratory Data Analysis
+- **Statistical Profiling**: Analyze data field characteristics including:
+  - Value distributions and ranges
+  - Temporal patterns and seasonality
+  - Cross-sectional relationships
+  - Missing data patterns
+  - Outlier identification
+
+- **Feature Engineering Insights**: Identify potential derived features and combinations
+- **Alpha Creation Opportunities**: Discover patterns that could lead to profitable trading strategies
+
+#### 5. Cross-Platform Research & Integration
+- **BRAIN Platform Exploration**: Leverage all available platform tools:
+  - Data Explorer for field discovery
+  - Simulation capabilities for data testing
+  - Research papers and documentation
+  - User community insights and best practices
+
+- **Forum & Community Engagement**: Research and integrate knowledge from:
+  - BRAIN support forum discussions
+  - User-generated content and tutorials
+  - Expert insights and case studies
+  - Platform updates and new features
+
+### Technical Skills Required
+
+#### 1. BRAIN Platform Proficiency
+- **Data Explorer Mastery**: Expert use of BRAIN's AI-powered data discovery tools
+- **Simulation Tools**: Ability to run test simulations to understand data behavior
+- **API Knowledge**: Understanding of BRAIN API for automated data exploration
+- **Documentation Navigation**: Efficient use of platform documentation and resources
+
+#### 2. Data Analysis Capabilities
+- **Statistical Analysis**: Understanding of descriptive statistics, distributions, and relationships
+- **Financial Knowledge**: Familiarity with financial statements, ratios, and market data
+- **Pattern Recognition**: Ability to identify meaningful patterns in complex datasets
+- **Data Quality Assessment**: Skills in evaluating data reliability and consistency
+
+#### 3. Documentation & Communication
+- **Technical Writing**: Ability to create clear, comprehensive field descriptions
+- **Visual Organization**: Skills in creating logical categorization systems
+- **Knowledge Management**: Ability to organize and present complex information clearly
+
+### Workflow & Methodology
+
+#### Phase 1: Dataset Selection & Initial Assessment
+1. **Dataset Identification**: Select target dataset based on:
+   - Strategic importance
+   - Current usage levels
+   - Data quality scores
+   - User community needs
+
+2. **Initial Exploration**: Use MCP to:
+   - Review dataset overview and description
+   - Identify total field count and coverage
+   - Assess value scores and pyramid multipliers
+   - Review research papers and documentation
+
+**MCP Tool Calls for Phase 1:**
+- **`mcp_brain-api_get_datasets`**: Discover available datasets with coverage filters
+- **`mcp_brain-api_get_datafields`**: Get field count and coverage statistics for selected dataset
+- **`mcp_brain-api_get_documentations`**: Access platform documentation and research papers
+- **`mcp_brain-api_get_documentation_page`**: Read specific documentation pages for dataset context
+
+#### Phase 2: Comprehensive Field Analysis
+1. **Field Inventory**: Catalog all data fields with:
+   - Field ID and name
+   - Current description
+   - Data type (matrix/vector/group), please note, different data types have different characteristics and usage patterns; you should use mcp to check how to handle different data types by reading the related documents.
+   - Coverage statistics
+   - Usage metrics (user count, alpha count)
+
+2. **Preliminary Categorization**: Group fields by:
+   - Business function
+   - Data characteristics
+   - Update patterns
+   - Coverage levels
+
+**MCP Tool Calls for Phase 2:**
+- **`mcp_brain-api_get_datafields`**: Retrieve complete field inventory with metadata
+- **`mcp_brain-api_get_documentation_page`**: Read data type handling documentation (e.g., "vector-datafields", "group-data-fields")
+- **`mcp_brain-api_get_operators`**: Understand available operators for different data types
+- **`mcp_brain-api_get_documentations`**: Access data handling best practices and examples
+
+#### Phase 3: Initial Data Exploration
+1. **Statistical Profiling Using BRAIN 6-Tips Methodology**: Run systematic exploratory simulations following the proven BRAIN platform approach. This methodology provides a comprehensive framework for understanding new datafields efficiently. **Critical Settings for All Tests**:
+   - **Neutralization**: "None" (to see raw data behavior without masking important patterns)
+   - **Decay**: 0 (to preserve actual data values and avoid smoothing out variations)
+   - **Test Period**: P0Y0M (for focused analysis)
+   - **Focus**: Long Count and Short Count in IS Summary section for insights
+
+   **A. Basic Coverage Analysis**
+   - **Expression**: `datafield` (for matrix data type) or `vector_operator(datafield)` (for vector data type)
+   - **Purpose**: Determine % coverage = (Long Count + Short Count) / Universe Size
+   - **Insight**: Understand basic data availability across instruments
+   - **What it tells you**: How many instruments have data for this field on average
+   - **Implementation**: Start with this test to establish baseline coverage understanding
+
+   **B. Non-Zero Value Coverage**
+   - **Expression**: `datafield != 0 ? 1 : 0` (for matrix) or `vector_operator(datafield) != 0 ? 1 : 0` (for vector)
+   - **Purpose**: Distinguish between missing data and actual zero values
+   - **Insight**: Long Count indicates average non-zero values on a daily basis
+   - **What it tells you**: Whether the field has meaningful data vs. just coverage gaps
+   - **Implementation**: Run after basic coverage to understand data quality vs. availability
+
+   **C. Data Update Frequency Analysis**
+   - **Expression**: `ts_std_dev(datafield,N) != 0 ? 1 : 0` (for matrix) or `ts_std_dev(vector_operator(datafield),N) != 0 ? 1 : 0` (for vector)
+   - **Purpose**: Understand how often data actually changes vs. being backfilled
+   - **Insight**: Frequency of unique data updates (daily, weekly, monthly, quarterly)
+   - **Key Testing Strategy**:
+     - **N = 5 (weekly)**: Long Count + Short Count will be lowest (approx. 1/5th of coverage)
+     - **N = 22 (monthly)**: Long Count + Short Count will be lower (approx. 1/3rd of coverage)
+     - **N = 66 (quarterly)**: Long Count + Short Count will be closest to actual coverage
+   - **What it tells you**: Data freshness patterns and whether data is actively updated or backfilled
+   - **Implementation**: Test with various N values to identify the actual update frequency
+
+   **D. Data Bounds Analysis**
+   - **Expression**: `abs(datafield) > X` (for matrix) or `abs(vector_operator(datafield)) > X` (for vector)
+   - **Purpose**: Understand data range, scale, and normalization
+   - **Insight**: Bounds of the datafield values
+   - **Testing Strategy**: Vary X values systematically:
+     - **X = 1**: Test if data is normalized to values between -1 and +1
+     - **X = 0.1, 0.5, 1, 5, 10**: Test various thresholds to understand value distribution
+   - **What it tells you**: Whether data is normalized, typical value ranges, and data scale
+   - **Implementation**: Start with X = 1, then adjust based on results to map the full value range
+
+   **E. Central Tendency Analysis**
+   - **Expression**: `ts_median(datafield, 1000) > X` (for matrix) or `ts_median(vector_operator(datafield), 1000) > X` (for vector)
+   - **Purpose**: Understand typical values and central tendency over 5 years
+   - **Insight**: Median of the datafield over extended period
+   - **Testing Strategy**: Vary X values to understand value distribution:
+     - **X = 0**: Test if median is positive
+     - **X = 0.1, 0.5, 1, 5, 10**: Test various thresholds to map central tendency
+   - **What it tells you**: Whether data is skewed, what typical values look like, and data characteristics
+   - **Alternative**: Can also use `ts_mean(datafield, 1000) > X` for mean-based analysis
+   - **Implementation**: Test with increasing X values until Long Count approaches zero
+
+   **F. Data Distribution Analysis**
+   - **Expression**: `X < scale_down(datafield) && scale_down(datafield) < Y` (for matrix) or `X < scale_down(vector_operator(datafield)) && scale_down(vector_operator(datafield)) < Y` (for vector)
+   - **Purpose**: Understand how data distributes across its range
+   - **Insight**: Distribution characteristics and patterns
+   - **Key Understanding**: `scale_down` acts as a MinMaxScaler that preserves original distribution
+   - **Testing Strategy**: Vary X and Y between 0 and 1 to test different distribution segments:
+     - **X = 0, Y = 0.25**: Test bottom quartile distribution
+     - **X = 0.25, Y = 0.5**: Test second quartile distribution
+     - **X = 0.5, Y = 0.75**: Test third quartile distribution
+     - **X = 0.75, Y = 1**: Test top quartile distribution
+   - **What it tells you**: Whether data is evenly distributed, clustered, or has specific patterns
+   - **Implementation**: Test quartile ranges first, then adjust for finer granularity
+
+   **Data Type Considerations**:
+   - **Matrix Data Type**: Use expressions directly as shown above
+   - **Vector Data Type**: Must use appropriate vector operators (found via MCP) to convert to matrix format
+   - **Group Data Type**: Requires special handling - consult MCP documentation for group field operators
+   - **Critical**: Always verify data type before testing and use appropriate operators accordingly
+
+   **Implementation Workflow for BRAIN 6-Tips**:
+   1. **Setup Phase**: Configure simulation with "None" neutralization, decay 0, and P0Y0M test period
+   2. **Sequential Testing**: Run tests A through F in order for systematic understanding
+   3. **Iterative Refinement**: Adjust thresholds based on initial results for deeper insights
+   4. **Documentation**: Record Long Count and Short Count for each test to build comprehensive profile
+   5. **Validation**: Cross-reference results across different N values and thresholds for consistency
+
+   **Expected Results Interpretation**:
+   - **Coverage Tests (A & B)**: Should show Long Count + Short Count ≤ Universe Size
+   - **Frequency Tests (C)**: Lower N values should show proportionally lower counts
+   - **Bounds Tests (D)**: Should reveal data normalization and typical ranges
+   - **Tendency Tests (E)**: Should show data skewness and central value characteristics
+   - **Distribution Tests (F)**: Should reveal clustering, patterns, and data spread
+
+   **Common Patterns to Watch For**:
+   - **Normalized Data**: Values consistently between -1 and +1
+   - **Quarterly Updates**: Significant count differences between N=22 and N=66
+   - **Sparse Data**: High coverage but low non-zero counts
+   - **Skewed Distributions**: Uneven quartile distributions in scale_down tests
+   - **Data Quality Issues**: Inconsistent results across different test parameters
+
+   **Practical Example - Closing Price Analysis**:
+   **Test A (Basic Coverage)**: `close` → High Long Count + Short Count indicates universal coverage
+   **Test B (Non-Zero)**: `close != 0 ? 1 : 0` → Should show same high counts (prices are never zero)
+   **Test C (Frequency)**: `ts_std_dev(close,5) != 0 ? 1 : 0` → High counts indicate daily price changes
+   **Test D (Bounds)**: `abs(close) > 1` → Should show high counts (prices typically > $1)
+   **Test E (Tendency)**: `ts_median(close,1000) > 0` → Should show high counts (median prices are positive)
+   **Test F (Distribution)**: `0 < scale_down(close) && scale_down(close) < 0.25` → Tests bottom quartile distribution
+
+   **What This Example Demonstrates**:
+   - **Validation**: Confirms expected behavior (prices are positive, change daily, have good coverage)
+   - **Pattern Recognition**: Shows how to identify normal vs. abnormal data characteristics
+   - **Quality Assessment**: Reveals data consistency and reliability
+   - **Alpha Creation Insights**: Understanding price behavior helps in strategy development
+
+   **Troubleshooting Common Issues**:
+   - **Zero Counts**: Check if datafield name is correct and data type is appropriate
+   - **Unexpected Results**: Verify neutralization is "None" and decay is 0
+   - **Vector Field Errors**: Ensure proper vector operator is used for vector data types
+   - **Inconsistent Patterns**: Test with different N values and thresholds for validation
+   - **Low Coverage**: Consider universe size and data availability in selected region/timeframe
+
+   **Best Practices for Efficient Exploration**:
+   - **Start Simple**: Begin with basic coverage tests before complex analysis
+   - **Document Everything**: Record all test parameters and results systematically
+   - **Iterate Intelligently**: Use initial results to guide subsequent test parameters
+   - **Cross-Validate**: Compare results across different test methods for consistency
+   - **Focus on Insights**: Prioritize understanding data behavior over exhaustive testing
+
+2. **Advanced Statistical Analysis**:
+   - Value distributions and ranges
+   - Temporal patterns and seasonality
+   - Cross-sectional relationships
+   - Missing data patterns
+   - Outlier identification
+   - Data quality consistency over time
+
+**MCP Tool Calls for Phase 3:**
+- **`mcp_brain-api_create_multi_regularAlpha_simulation`**: Execute BRAIN 6-tips methodology simulations
+- **`mcp_brain-api_get_platform_setting_options`**: Validate simulation settings and parameters
+- **`mcp_brain-api_get_operators`**: Access time series operators (ts_std_dev, ts_median, scale_down)
+- **`mcp_brain-api_get_documentation_page`**: Read simulation settings documentation ("simulation-settings")
+- **`mcp_brain-api_get_documentation_page`**: Access data analysis best practices ("data")
+
+3. **Relationship Mapping**: Identify:
+   - Field interdependencies and correlations
+   - Logical groupings and hierarchies
+   - Potential derived features and combinations
+   - Alpha creation opportunities
+   - Risk factors and limitations
+
+#### Phase 4: Enhanced Documentation
+1. **Description Enhancement**: Improve field descriptions with:
+   - Business context
+   - Calculation details and data unit
+   - Usage examples
+   - Limitations and considerations
+
+2. **Categorization Refinement**: Finalize logical groupings with:
+   - Clear category names
+   - Hierarchical structure
+   - Cross-references
+   - Usage guidelines
+
+**MCP Tool Calls for Phase 4:**
+- **`mcp_brain-api_get_documentation_page`**: Access field description best practices ("data")
+- **`mcp_brain-api_get_documentations`**: Review documentation structure and organization
+- **`mcp_brain-api_get_alpha_examples`**: Find usage examples in documentation ("19-alpha-examples")
+- **`mcp_brain-api_get_documentation_page`**: Access categorization guidelines ("how-use-data-explorer")
+
+#### Phase 5: Knowledge Integration & Validation
+1. **Community Research**: Review forum discussions and user insights, search and read related documents or related guidanline.
+2. **Best Practice Integration**: Incorporate platform-specific knowledge by looking into related documents or related competitions' guidanline.
+3. **Validation**: Test categorization with sample use cases
+4. **Documentation**: Create final comprehensive dataset guide
+
+**MCP Tool Calls for Phase 5:**
+- **`mcp_brain-forum_search_forum_posts`**: Search community discussions and user insights
+- **`mcp_brain-forum_read_full_forum_post`**: Read detailed forum discussions and best practices
+- **`mcp_brain-api_get_events`**: Access competition guidelines and rules
+- **`mcp_brain-api_get_competition_details`**: Review specific competition requirements
+- **`mcp_brain-api_get_documentation_page`**: Access platform best practices and guidelines
+- **`mcp_brain-api_get_alpha_examples`**: Review alpha strategy examples for validation
+
+### Deliverables
+
+#### 1. Dataset Field Catalog
+- Complete inventory of all data fields
+- Enhanced descriptions for each field
+- Coverage and usage statistics
+- Quality indicators and limitations
+
+#### 2. Logical Categorization System
+- Hierarchical field grouping
+- Category descriptions and rationale
+- Cross-reference system
+- Usage guidelines and examples
+
+#### 3. Data Initial Exploration Report
+- Coverage analysis by instrument and time
+- Data consistency evaluation
+- Missing data patterns
+- Quality improvement recommendations
+
+#### 4. Alpha Creation Insights
+- Identified patterns and relationships
+- Potential strategy opportunities
+- Risk considerations
+- Implementation guidelines
+
+#### 5. Comprehensive Dataset Guide
+- Executive summary
+- Detailed field documentation
+- Categorization system
+- Best practices and examples
+- Troubleshooting guide
+
+### Success Metrics
+
+#### 1. Documentation Quality
+- **Completeness**: All fields documented with enhanced descriptions
+- **Clarity**: Descriptions are clear and actionable
+- **Organization**: Logical, intuitive categorization system
+- **Accuracy**: Information is current and correct
+
+#### 2. User Experience Improvement
+- **Discovery**: Users can quickly find relevant fields
+- **Understanding**: Clear comprehension of field purpose and usage
+- **Efficiency**: Reduced time to identify appropriate data
+- **Confidence**: Users trust the information provided
+
+#### 3. Platform Knowledge Enhancement
+- **Coverage**: Comprehensive understanding of dataset capabilities
+- **Insights**: Discovery of new patterns and opportunities
+- **Integration**: Knowledge connects to broader platform understanding
+- **Innovation**: Identification of new use cases and applications
+
+### Tools & Resources
+
+#### 1. BRAIN Platform Tools
+- **Data Explorer**: Primary field discovery and analysis tool
+- **Simulation Engine**: Data behavior testing and validation
+- **Documentation System**: Platform knowledge and best practices
+- **API Access**: Automated data exploration and analysis
+- **BRAIN 6-Tips Methodology**: Proven systematic approach to datafield exploration
+
+**MCP Tool Integration for Platform Tools:**
+- **Data Explorer**: Use `mcp_brain-api_get_datasets` and `mcp_brain-api_get_datafields`
+- **Simulation Engine**: Use `mcp_brain-api_create_simulation` with proper settings
+- **Documentation System**: Use `mcp_brain-api_get_documentations` and `mcp_brain-api_get_documentation_page`
+- **API Access**: All MCP tools provide automated API access
+- **BRAIN 6-Tips**: Implemented through `mcp_brain-api_create_simulation` calls
+
+#### 2. External Resources
+- **Financial Databases**: Additional context for financial fields
+- **Industry Publications**: Market knowledge and trends
+- **Academic Research**: Statistical methods and best practices
+- **Community Forums**: User insights and experiences
+
+#### 3. Analysis Tools
+- **Statistical Software**: Data analysis and visualization
+- **Documentation Tools**: Knowledge management and organization
+- **Collaboration Platforms**: Team coordination and knowledge sharing
+
+**MCP-Enhanced Analysis Capabilities:**
+- **Statistical Analysis**: Use `mcp_brain-api_create_simulation` for data behavior testing
+- **Data Quality Assessment**: Use `mcp_brain-api_get_platform_setting_options` for validation
+- **Pattern Recognition**: Use `mcp_brain-api_get_operators` for available analysis functions
+- **Documentation Management**: Use `mcp_brain-api_get_documentations` for comprehensive knowledge access
+- **Community Integration**: Use `mcp_brain-forum_*` tools for collaborative insights
+
+### Professional Development
+
+#### 1. Continuous Learning
+- **Platform Updates**: Stay current with BRAIN platform developments
+- **Industry Trends**: Monitor financial data and technology advances
+- **Best Practices**: Learn from community and expert insights
+- **Skill Enhancement**: Develop additional technical and analytical capabilities
+
+#### 2. Knowledge Sharing
+- **Team Training**: Share expertise with colleagues
+- **Community Contribution**: Contribute to BRAIN community knowledge
+- **Documentation Updates**: Maintain current and accurate information
+- **Best Practice Development**: Create and refine methodologies
+
+### Conclusion
+
+The Dataset Exploration Expert role is critical for maximizing the value of WorldQuant BRAIN's extensive data resources. By providing deep insights, logical organization, and comprehensive documentation, this expert enables users to discover new opportunities, create more effective alphas, and leverage the platform's full potential.
+
+Success in this role requires a combination of technical expertise, analytical thinking, and communication skills, along with a deep understanding of both financial markets and data science principles. The expert serves as a bridge between raw data and actionable insights, transforming complex datasets into accessible, well-organized knowledge resources that drive innovation and success on the BRAIN platform.
+
+---
+
+## 🔧 **MCP Tool Reference Guide**
+
+### **Core Data Exploration Tools**
+- **`mcp_brain-api_get_datasets`**: Discover and filter available datasets
+- **`mcp_brain-api_get_datafields`**: Retrieve field inventory and metadata
+- **`mcp_brain-api_create_simulation`**: Execute data analysis simulations
+- **`mcp_brain-api_get_platform_setting_options`**: Validate simulation parameters
+
+### **Documentation & Knowledge Tools**
+- **`mcp_brain-api_get_documentations`**: Access platform documentation structure
+- **`mcp_brain-api_get_documentation_page`**: Read specific documentation content
+- **`mcp_brain-api_get_operators`**: Discover available analysis operators
+- **`mcp_brain-api_get_alpha_examples`**: Access strategy examples and templates
+
+### **Community & Forum Tools**
+- **`mcp_brain-forum_search_forum_posts`**: Search community discussions
+- **`mcp_brain-forum_read_full_forum_post`**: Read detailed forum content
+- **`mcp_brain-forum_get_glossary_terms`**: Access community terminology
+
+### **Competition & Event Tools**
+- **`mcp_brain-api_get_events`**: Discover available competitions
+- **`mcp_brain-api_get_competition_details`**: Get competition guidelines
+- **`mcp_brain-api_get_competition_agreement`**: Access competition rules
+
+### **Best Practices for MCP Tool Usage**
+1. **Always authenticate first** using `mcp_brain-api_authenticate`
+2. **Validate parameters** using `mcp_brain-api_get_platform_setting_options`
+3. **Handle errors gracefully** and retry with corrected parameters
+4. **Use appropriate delays** between API calls to avoid rate limiting
+5. **Document tool usage** in your exploration reports for reproducibility

cnhkmcp/untracked/skills/brain-explain-alphas/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: brain-explain-alphas
+description: >-
+  Provides a step-by-step workflow for analyzing and explaining WorldQuant BRAIN alpha expressions.
+  Use this when the user asks to explain a specific alpha expression, what a datafield does, or how operators work together.
+  Includes steps for data field lookup, operator analysis, and external research.
+---
+
+# Alpha Explanation Workflow
+
+This manual provides a workflow for analyzing and explaining a WorldQuant BRAIN alpha expression.
+For the full detailed workflow and examples, see [reference.md](reference.md).
+
+## Step 1: Deconstruct the Alpha Expression
+Break down the alpha expression into its fundamental components: data fields and operators.
+*Example:* `quantile(ts_regression(oth423_find,group_mean(oth423_find,vec_max(shrt3_bar),country),90))`
+- **Data Fields**: `oth423_find`, `shrt3_bar`
+- **Operators**: `quantile`, `ts_regression`, `group_mean`, `vec_max`
+
+## Step 2: Analyze Data Fields
+Use the `get_datafields` tool to get details about each data field.
+- Identify: Instrument Type, Region, Delay, Universe, Data Type (Matrix/Vector).
+- Note: Vector data requires aggregation (e.g., `vec_max`).
+
+## Step 3: Understand the Operators
+Use the `get_operators` tool to understand what each operator does.
+
+## Step 4: Consult Official Documentation
+Use `get_documentations` and `read_specific_documentation` for deep dives into concepts (e.g., vector data handling).
+
+## Step 5: Synthesize and Explain
+Structure the explanation:
+1.  **Idea**: High-level summary of the strategy.
+2.  **Rationale for data**: Why these fields? What do they represent?
+3.  **Rationale for operators**: How do they transform the data?
+4.  **Further Inspiration**: Potential improvements.
+
+## Appendix: Vector Data
+Vector data records multiple events per day per instrument (e.g., news). It requires aggregation (like `vec_mean`, `vec_sum`) to become a matrix value usable by other operators.

cnhkmcp/untracked/skills/brain-explain-alphas/reference.md

@@ -0,0 +1,56 @@
+Alpha Explanation Workflow
+This manual provides a step-by-step workflow for analyzing and explaining a WorldQuant BRAIN alpha expression. By following this guide, you can efficiently gather the necessary information to understand the logic and potential strategy behind any alpha.
+
+Step 1: Deconstruct the Alpha Expression
+The first step is to break down the alpha expression into its fundamental components: data fields and operators.
+
+For example, given the expression quantile(ts_regression(oth423_find,group_mean(oth423_find,vec_max(shrt3_bar),country),90)):
+
+Data Fields: oth423_find, shrt3_bar
+Operators: quantile, ts_regression, group_mean, vec_max
+Step 2: Analyze Data Fields
+Use the brain-platform-mcp tool get_datafields to get detailed information about each data field.
+
+Tool Usage: xml <use_mcp_tool> <server_name>brain-platform-mcp</server_name> <tool_name>get_datafields</tool_name> <arguments> { "instrument_type": "EQUITY", "region": "ASI", "delay": 1, "universe": "MINVOL1M", "data_type": "VECTOR", "search": "shrt3_bar" } </arguments> </use_mcp_tool>
+
+Tips for effective searching:
+
+Specify Parameters: Always provide as much information as you know, including instrument_type, region, delay, universe, and data_type (MATRIX or VECTOR).
+Iterate: If you don't find the data field on your first try, try different combinations of parameters. The ASI region, for example, has two universes: MINVOL1M and ILLIQUID_MINVOL1M.
+Check Data Type: Be sure to check if the data is a MATRIX (one value per stock per day) or a VECTOR (multiple values per stock per day). This is crucial for understanding how the data is used.
+Example Data Field Information:
+
+oth423_find: A matrix data field from the "Fundamental Income and Dividend Model" dataset in the ASI region. It represents a "Find score," likely indicating fundamental attractiveness.
+shrt3_bar: A vector data field from the "Securities Lending Files Data" dataset in the ASI region. It provides a vector of ratings (1-10) indicating the demand to borrow a stock, which is a proxy for short-selling interest.
+Step 3: Understand the Operators
+Use the brain-platform-mcp tool get_operators to get a list of all available operators and their descriptions.
+
+Tool Usage: xml <use_mcp_tool> <server_name>brain-platform-mcp</server_name> <tool_name>get_operators</tool_name> <arguments> {} </arguments> </use_mcp_tool> The output of this command contains a wealth of information. For your convenience, a table of the most common operators is included in the Appendix of this manual.
+
+Step 4: Consult Official Documentation
+For more complex topics, the official BRAIN documentation is an invaluable resource. Use the get_documentations tool to see a list of available documents, and get_documentation_page to read a specific page.
+
+Example: To understand vector data fields better, I consulted the "Vector Data Fields 🥉" document (vector-datafields). This revealed that vector data contains multiple values per instrument per day and must be aggregated by a vector operator before being used with other operators.
+
+Step 5: Broaden Understanding with External Research (Must Call the arxiv_api.py script to get the latest research papers)
+For cutting-edge ideas and inspiration, you can search for academic papers on arXiv using the provided arxiv_api.py script.
+
+Workflow:
+
+Identify Keywords: Based on your analysis of the alpha, identify relevant keywords. For our example, these were: "short interest", "fundamental analysis", "relative value", and "news sentiment".
+Run the Script: Use the with-wrappers script to avoid SSL errors.
+
+python arxiv_api.py "your keywords here" -n 10
+Step 6: Synthesize and Explain
+Once you have gathered all the necessary information, structure your explanation in a clear and concise format. The following template is recommended:
+
+Idea: A high-level summary of the alpha's strategy.
+Rationale for data used: An explanation of why each data field was chosen and what it represents.
+Rationale for operators used: A step-by-step explanation of how the operators transform the data to generate the final signal.
+Further Inspiration: Ideas for new alphas based on your research.
+Troubleshooting
+SSL Errors: If you encounter a CERTIFICATE_VERIFY_FAILED error when running python scripts that access the internet, use the AI to help you change or make script to execute your command.
+Appendix A: Understanding Vector Data
+Vector Data is a distinct type of data field where the number of events recorded per day, per instrument, can vary. This is in contrast to standard matrix data, which has a single value for each instrument per day.
+
+For example, news sentiment data is often a vector because a stock can have multiple news articles on a single day. To use this data in most BRAIN operators, it must first be aggregated into a single value using a vector operator.

cnhkmcp/untracked/skills/brain-how-to-pass-AlphaTest/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: brain-how-to-pass-AlphaTest
+description: >-
+  Provides detailed requirements, thresholds, and improvement tips for WorldQuant BRAIN Alpha submission tests.
+  Covers Fitness, Sharpe, Turnover, Weight, Sub-universe, and Self-Correlation tests.
+  Use this when the user asks about alpha submission failures, how to improve alpha metrics, or test requirements.
+---
+
+# BRAIN Alpha Submission Tests: Requirements and Improvement Tips
+
+This skill provides key requirements and expert tips for passing alpha submission tests.
+For comprehensive details, thresholds, and community-sourced strategies, please read [reference.md](reference.md).
+
+## Overview
+
+Alphas must pass a series of pre-submission checks to ensure they meet quality thresholds.
+
+## 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)).
+
+### Tips to Improve
+- Increase Sharpe/Returns and reduce Turnover.
+- Use group operators (e.g., with pv13) to boost fitness.
+- Check with `check_submission` tool.
+
+## 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).
+
+### Tips to Improve
+- Focus on consistent PnL with low volatility.
+- Decay signals separately for liquid/non-liquid stocks.
+- If Sharpe is negative (e.g., -1 to -2), try flipping the sign: `-original_expression`.
+
+## 3. Turnover
+### Requirements
+- 1% < Turnover < 70%.
+
+### Tips to Improve
+- Use decay functions (`ts_decay_linear`) to smooth signals.
+
+## 4. Weight Test
+### Requirements
+- Max weight in any stock <10%.
+
+### Tips to Improve
+- Use neutralization (e.g., `neutralize(x, "MARKET")`) to distribute weights.
+
+## 5. Sub-universe Test
+### Requirements
+- Sub-universe Sharpe >= 0.75 * sqrt(subuniverse_size / alpha_universe_size) * alpha_sharpe.
+
+### Tips to Improve
+- Avoid size-related multipliers.
+- Decay liquid/non-liquid parts separately.
+
+## 6. Self-Correlation
+### Requirements
+- <0.7 PnL correlation with own submitted alphas.
+
+### Tips to Improve
+- Submit diverse ideas.
+- Use `check_correlation` tool.
+- Transform negatively correlated alphas.
+
+## General Guidance
+- **Start Simple**: Use basic operators like `ts_rank` first.
+- **Optimize Settings**: Choose universes like TOP3000 (USA, D1).
+- **ATOM Principle**: Avoid mixing datasets to benefit from relaxed "ATOM" submission criteria (Last 2Y Sharpe).