# Pantheon Legends
A Python framework for implementing financial market analysis "legends" (methodologies), converted from C# contracts to idiomatic Python using dataclasses and type hints.
## Overview
Pantheon Legends provides a framework for implementing and orchestrating multiple financial analysis methodologies such as Dow Theory, Wyckoff Method, Elliott Wave, etc. The framework includes example implementations to demonstrate the structure, but **does not include actual legend implementations**.
## Features
- **Async/Await Support**: All analysis operations are asynchronous for better performance
- **Type Safety**: Full type hints using Python's typing system
- **Progress Reporting**: Real-time progress updates during analysis
- **Quality Metadata**: Comprehensive data quality metrics for each analysis
- **Extensible Design**: Easy to add new legend engines
- **Orchestration**: Run multiple legend engines concurrently
- **Example Implementations**: Demo engines showing the framework structure
## Installation
```bash
# Install from PyPI
pip install pantheon-legends
# Test installation
python -c "import legends; legends.test_installation()"
# Or install from source
git clone https://github.com/SpartanDigitalDotNet/pantheon-legends
cd pantheon-legends
pip install -e .
```
## Important Note
**This package provides a framework for implementing financial analysis legend engines, not the legend implementations themselves.**
The included `DowLegendEngine` and `WyckoffLegendEngine` are **demonstration engines only** that generate sample data to show the framework structure. They do not perform actual Dow Theory or Wyckoff Method analysis.
To use this framework for real analysis, you need to:
1. **Implement actual legend logic** in your custom engines
2. **Connect to real market data sources**
3. **Apply the specific methodology algorithms** (Dow Theory, Wyckoff, etc.)
4. **Replace the demo data** with real analysis results
## Converting Your Scanner to a Legend
If you have an existing market scanner, you can easily convert it to a Pantheon Legend:
```bash
# Interactive scanner conversion tool
python -m legends create
```
This will guide you through:
- **Scanner characteristics** (signals, timeframes, data needs)
- **Generate a template** with your scanner structure
- **Provide clear TODO markers** where to integrate your code
- **Include test functions** to verify your legend works
Example workflow:
```
📊 What's the name of your scanner? ResonanceBreakout
🔍 What signals does it detect? breakout, volume_spike, momentum
📈 What timeframes does it work with? 1m, 5m
📊 What data does it need? price, volume, moving_averages
🎉 Success! Created resonancebreakoutlegend.py
```
## Quick Start
### Basic Usage
```python
import asyncio
from datetime import datetime
from legends import Pantheon, LegendRequest
async def main():
# Create Pantheon with default engines
pantheon = Pantheon.create_default()
# Create an analysis request
request = LegendRequest(
symbol="AAPL",
timeframe="1d",
as_of=datetime.now()
)
# Run all legend engines
results = await pantheon.run_all_legends_async(request)
# Display results
for result in results:
print(f"{result.legend}: {result.facts}")
asyncio.run(main())
```
### Using Individual Engines
```python
import asyncio
from datetime import datetime
from legends import DowLegendEngine, LegendRequest
async def main():
# Create a demo legend engine (not actual Dow Theory implementation)
dow_engine = DowLegendEngine()
request = LegendRequest(
symbol="MSFT",
timeframe="4h",
as_of=datetime.now()
)
# Run the demo analysis
result = await dow_engine.run_async(request)
print(f"Demo Result: {result.facts['primary_trend']}")
print(f"Confidence: {result.facts['confidence_score']}")
asyncio.run(main())
```
### Progress Monitoring
```python
import asyncio
from legends import LegendProgress
async def progress_handler(progress: LegendProgress):
print(f"[{progress.legend}] {progress.stage}: {progress.percent:.1f}%")
# Use with any engine
result = await engine.run_async(request, progress_handler)
```
## Core Components
### Data Models
- **`LegendRequest`**: Analysis request with symbol, timeframe, and timestamp
- **`LegendProgress`**: Progress updates during analysis execution
- **`LegendEnvelope`**: Complete analysis results with metadata
- **`QualityMeta`**: Data quality metrics (sample size, freshness, completeness)
### Engines
- **`DowLegendEngine`**: Demo implementation showing Dow Theory structure
- **`WyckoffLegendEngine`**: Demo implementation showing Wyckoff Method structure
- **Custom Engines**: Implement `ILegendEngine` protocol for real analysis
### Orchestration
- **`Pantheon`**: Manages multiple engines and provides unified interface
- **Progress Callbacks**: Real-time progress reporting
- **Concurrent Execution**: Run multiple engines simultaneously
## Creating Custom Legend Engines
```python
from legends.contracts import ILegendEngine, LegendRequest, LegendEnvelope
class MyCustomLegend:
@property
def name(self) -> str:
return "MyLegend"
async def run_async(self, request: LegendRequest, progress_callback=None):
# Your analysis logic here
facts = {"signal": "bullish", "strength": 0.85}
quality = QualityMeta(100.0, 30.0, 1.0)
return LegendEnvelope(
legend=self.name,
at=request.as_of,
tf=request.timeframe,
facts=facts,
quality=quality
)
# Register with Pantheon
pantheon = Pantheon()
pantheon.register_engine(MyCustomLegend())
```
## Development
### Setup Development Environment
```bash
# Clone the repository
git clone https://github.com/SpartanDigitalDotNet/pantheon-legends
cd pantheon-legends
# Install in development mode with dev dependencies
pip install -e ".[dev]"
```
### Running Tests
```bash
pytest
```
### Code Formatting
```bash
black legends/
isort legends/
```
### Type Checking
```bash
mypy legends/
```
## API Reference
### LegendRequest
```python
@dataclass(frozen=True)
class LegendRequest:
symbol: str # Financial instrument symbol
timeframe: str # Time interval (e.g., "1d", "4h", "1m")
as_of: datetime # Analysis timestamp
```
### LegendEnvelope
```python
@dataclass(frozen=True)
class LegendEnvelope:
legend: str # Engine name
at: datetime # Analysis time
tf: str # Timeframe
facts: Dict[str, Any] # Analysis results
quality: QualityMeta # Quality metrics
```
### ILegendEngine Protocol
```python
class ILegendEngine(Protocol):
@property
def name(self) -> str: ...
async def run_async(
self,
request: LegendRequest,
progress_callback: Optional[ProgressCallback] = None
) -> LegendEnvelope: ...
```
## Examples
See `examples.py` for comprehensive usage examples including:
- Single engine execution
- Multi-engine orchestration
- Custom engine implementation
- Progress monitoring
- Error handling
## License
MIT License - see LICENSE file for details.
## Contributing Your Legend
Have a working legend? Share it with the community!
### **Quick Start:**
1. **Convert your scanner**: `python -m legends create`
2. **Implement your logic** in the generated template
3. **Test thoroughly** with real market data
4. **Submit a pull request** to share with others
### **Community Guidelines:**
- **Clear documentation** of what your legend detects
- **Example usage** with sample outputs
- **Performance characteristics** (speed, accuracy, etc.)
- **Data requirements** and dependencies
### **Legend Naming:**
- Use descriptive names: `BreakoutDetector`, `VolumeSpike`, `MomentumShift`
- Include version if iterating: `BreakoutDetectorV2`
- Mention methodology: `WyckoffAccumulation`, `DowTrendConfirmation`
## Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request
## Roadmap
- [ ] Additional built-in legend engines
- [ ] Data source integrations
- [ ] Performance optimizations
- [ ] Advanced orchestration features
- [ ] Web API interface
- [ ] Real-time streaming support
Raw data
{
"_id": null,
"home_page": null,
"name": "pantheon-legends",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "finance, trading, technical-analysis, market-analysis, legends",
"author": null,
"author_email": "SpartanDigital <spartandigital@icloud.com>",
"download_url": "https://files.pythonhosted.org/packages/49/51/a6aadcd5a9b93ff477f32675d832c0c09631d9fdacb0b7f3ffc47a1615a2/pantheon_legends-0.2.0.tar.gz",
"platform": null,
"description": "# Pantheon Legends\r\n\r\nA Python framework for implementing financial market analysis \"legends\" (methodologies), converted from C# contracts to idiomatic Python using dataclasses and type hints.\r\n\r\n## Overview\r\n\r\nPantheon Legends provides a framework for implementing and orchestrating multiple financial analysis methodologies such as Dow Theory, Wyckoff Method, Elliott Wave, etc. The framework includes example implementations to demonstrate the structure, but **does not include actual legend implementations**.\r\n\r\n## Features\r\n\r\n- **Async/Await Support**: All analysis operations are asynchronous for better performance\r\n- **Type Safety**: Full type hints using Python's typing system\r\n- **Progress Reporting**: Real-time progress updates during analysis\r\n- **Quality Metadata**: Comprehensive data quality metrics for each analysis\r\n- **Extensible Design**: Easy to add new legend engines\r\n- **Orchestration**: Run multiple legend engines concurrently\r\n- **Example Implementations**: Demo engines showing the framework structure\r\n\r\n## Installation\r\n\r\n```bash\r\n# Install from PyPI\r\npip install pantheon-legends\r\n\r\n# Test installation\r\npython -c \"import legends; legends.test_installation()\"\r\n\r\n# Or install from source\r\ngit clone https://github.com/SpartanDigitalDotNet/pantheon-legends\r\ncd pantheon-legends\r\npip install -e .\r\n```\r\n\r\n## Important Note\r\n\r\n**This package provides a framework for implementing financial analysis legend engines, not the legend implementations themselves.**\r\n\r\nThe included `DowLegendEngine` and `WyckoffLegendEngine` are **demonstration engines only** that generate sample data to show the framework structure. They do not perform actual Dow Theory or Wyckoff Method analysis.\r\n\r\nTo use this framework for real analysis, you need to:\r\n\r\n1. **Implement actual legend logic** in your custom engines\r\n2. **Connect to real market data sources** \r\n3. **Apply the specific methodology algorithms** (Dow Theory, Wyckoff, etc.)\r\n4. **Replace the demo data** with real analysis results\r\n\r\n## Converting Your Scanner to a Legend\r\n\r\nIf you have an existing market scanner, you can easily convert it to a Pantheon Legend:\r\n\r\n```bash\r\n# Interactive scanner conversion tool\r\npython -m legends create\r\n```\r\n\r\nThis will guide you through:\r\n- **Scanner characteristics** (signals, timeframes, data needs)\r\n- **Generate a template** with your scanner structure\r\n- **Provide clear TODO markers** where to integrate your code\r\n- **Include test functions** to verify your legend works\r\n\r\nExample workflow:\r\n```\r\n\ud83d\udcca What's the name of your scanner? ResonanceBreakout\r\n\ud83d\udd0d What signals does it detect? breakout, volume_spike, momentum \r\n\ud83d\udcc8 What timeframes does it work with? 1m, 5m\r\n\ud83d\udcca What data does it need? price, volume, moving_averages\r\n\r\n\ud83c\udf89 Success! Created resonancebreakoutlegend.py\r\n```\r\n\r\n## Quick Start\r\n\r\n### Basic Usage\r\n\r\n```python\r\nimport asyncio\r\nfrom datetime import datetime\r\nfrom legends import Pantheon, LegendRequest\r\n\r\nasync def main():\r\n # Create Pantheon with default engines\r\n pantheon = Pantheon.create_default()\r\n \r\n # Create an analysis request\r\n request = LegendRequest(\r\n symbol=\"AAPL\",\r\n timeframe=\"1d\", \r\n as_of=datetime.now()\r\n )\r\n \r\n # Run all legend engines\r\n results = await pantheon.run_all_legends_async(request)\r\n \r\n # Display results\r\n for result in results:\r\n print(f\"{result.legend}: {result.facts}\")\r\n\r\nasyncio.run(main())\r\n```\r\n\r\n### Using Individual Engines\r\n\r\n```python\r\nimport asyncio\r\nfrom datetime import datetime\r\nfrom legends import DowLegendEngine, LegendRequest\r\n\r\nasync def main():\r\n # Create a demo legend engine (not actual Dow Theory implementation)\r\n dow_engine = DowLegendEngine()\r\n \r\n request = LegendRequest(\r\n symbol=\"MSFT\",\r\n timeframe=\"4h\",\r\n as_of=datetime.now()\r\n )\r\n \r\n # Run the demo analysis\r\n result = await dow_engine.run_async(request)\r\n \r\n print(f\"Demo Result: {result.facts['primary_trend']}\")\r\n print(f\"Confidence: {result.facts['confidence_score']}\")\r\n\r\nasyncio.run(main())\r\n```\r\n\r\n### Progress Monitoring\r\n\r\n```python\r\nimport asyncio\r\nfrom legends import LegendProgress\r\n\r\nasync def progress_handler(progress: LegendProgress):\r\n print(f\"[{progress.legend}] {progress.stage}: {progress.percent:.1f}%\")\r\n\r\n# Use with any engine\r\nresult = await engine.run_async(request, progress_handler)\r\n```\r\n\r\n## Core Components\r\n\r\n### Data Models\r\n\r\n- **`LegendRequest`**: Analysis request with symbol, timeframe, and timestamp\r\n- **`LegendProgress`**: Progress updates during analysis execution \r\n- **`LegendEnvelope`**: Complete analysis results with metadata\r\n- **`QualityMeta`**: Data quality metrics (sample size, freshness, completeness)\r\n\r\n### Engines\r\n\r\n- **`DowLegendEngine`**: Demo implementation showing Dow Theory structure\r\n- **`WyckoffLegendEngine`**: Demo implementation showing Wyckoff Method structure\r\n- **Custom Engines**: Implement `ILegendEngine` protocol for real analysis\r\n\r\n### Orchestration\r\n\r\n- **`Pantheon`**: Manages multiple engines and provides unified interface\r\n- **Progress Callbacks**: Real-time progress reporting\r\n- **Concurrent Execution**: Run multiple engines simultaneously\r\n\r\n## Creating Custom Legend Engines\r\n\r\n```python\r\nfrom legends.contracts import ILegendEngine, LegendRequest, LegendEnvelope\r\n\r\nclass MyCustomLegend:\r\n @property\r\n def name(self) -> str:\r\n return \"MyLegend\"\r\n \r\n async def run_async(self, request: LegendRequest, progress_callback=None):\r\n # Your analysis logic here\r\n facts = {\"signal\": \"bullish\", \"strength\": 0.85}\r\n quality = QualityMeta(100.0, 30.0, 1.0)\r\n \r\n return LegendEnvelope(\r\n legend=self.name,\r\n at=request.as_of, \r\n tf=request.timeframe,\r\n facts=facts,\r\n quality=quality\r\n )\r\n\r\n# Register with Pantheon\r\npantheon = Pantheon()\r\npantheon.register_engine(MyCustomLegend())\r\n```\r\n\r\n## Development\r\n\r\n### Setup Development Environment\r\n\r\n```bash\r\n# Clone the repository\r\ngit clone https://github.com/SpartanDigitalDotNet/pantheon-legends\r\ncd pantheon-legends\r\n\r\n# Install in development mode with dev dependencies\r\npip install -e \".[dev]\"\r\n```\r\n\r\n### Running Tests\r\n\r\n```bash\r\npytest\r\n```\r\n\r\n### Code Formatting\r\n\r\n```bash\r\nblack legends/\r\nisort legends/\r\n```\r\n\r\n### Type Checking\r\n\r\n```bash\r\nmypy legends/\r\n```\r\n\r\n## API Reference\r\n\r\n### LegendRequest\r\n\r\n```python\r\n@dataclass(frozen=True)\r\nclass LegendRequest:\r\n symbol: str # Financial instrument symbol\r\n timeframe: str # Time interval (e.g., \"1d\", \"4h\", \"1m\")\r\n as_of: datetime # Analysis timestamp\r\n```\r\n\r\n### LegendEnvelope\r\n\r\n```python\r\n@dataclass(frozen=True) \r\nclass LegendEnvelope:\r\n legend: str # Engine name\r\n at: datetime # Analysis time\r\n tf: str # Timeframe\r\n facts: Dict[str, Any] # Analysis results\r\n quality: QualityMeta # Quality metrics\r\n```\r\n\r\n### ILegendEngine Protocol\r\n\r\n```python\r\nclass ILegendEngine(Protocol):\r\n @property\r\n def name(self) -> str: ...\r\n \r\n async def run_async(\r\n self,\r\n request: LegendRequest,\r\n progress_callback: Optional[ProgressCallback] = None\r\n ) -> LegendEnvelope: ...\r\n```\r\n\r\n## Examples\r\n\r\nSee `examples.py` for comprehensive usage examples including:\r\n\r\n- Single engine execution\r\n- Multi-engine orchestration \r\n- Custom engine implementation\r\n- Progress monitoring\r\n- Error handling\r\n\r\n## License\r\n\r\nMIT License - see LICENSE file for details.\r\n\r\n## Contributing Your Legend\r\n\r\nHave a working legend? Share it with the community!\r\n\r\n### **Quick Start:**\r\n1. **Convert your scanner**: `python -m legends create`\r\n2. **Implement your logic** in the generated template\r\n3. **Test thoroughly** with real market data\r\n4. **Submit a pull request** to share with others\r\n\r\n### **Community Guidelines:**\r\n- **Clear documentation** of what your legend detects\r\n- **Example usage** with sample outputs\r\n- **Performance characteristics** (speed, accuracy, etc.)\r\n- **Data requirements** and dependencies\r\n\r\n### **Legend Naming:**\r\n- Use descriptive names: `BreakoutDetector`, `VolumeSpike`, `MomentumShift`\r\n- Include version if iterating: `BreakoutDetectorV2`\r\n- Mention methodology: `WyckoffAccumulation`, `DowTrendConfirmation`\r\n\r\n## Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Add tests for new functionality\r\n4. Ensure all tests pass\r\n5. Submit a pull request\r\n\r\n## Roadmap\r\n\r\n- [ ] Additional built-in legend engines\r\n- [ ] Data source integrations\r\n- [ ] Performance optimizations\r\n- [ ] Advanced orchestration features\r\n- [ ] Web API interface\r\n- [ ] Real-time streaming support\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python framework for implementing financial market analysis legend engines with type-aware Traditional vs Scanner distinction",
"version": "0.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/SpartanDigitalDotNet/pantheon-legends/issues",
"Documentation": "https://spartandigitaldotnet.github.io/pantheon-legends",
"Homepage": "https://github.com/SpartanDigitalDotNet/pantheon-legends",
"Repository": "https://github.com/SpartanDigitalDotNet/pantheon-legends"
},
"split_keywords": [
"finance",
" trading",
" technical-analysis",
" market-analysis",
" legends"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6f47bd51e1f5ac2623b18d03d4aee3deca9a1fdcfa62bde3c713f0453901c977",
"md5": "a39316811824b5b8934788db50a73547",
"sha256": "d3d36a05726acc8831ada5a2cd021c73ba6f58123b9763325cc1fa25bdfdfece"
},
"downloads": -1,
"filename": "pantheon_legends-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a39316811824b5b8934788db50a73547",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 18514,
"upload_time": "2025-09-08T03:59:23",
"upload_time_iso_8601": "2025-09-08T03:59:23.573737Z",
"url": "https://files.pythonhosted.org/packages/6f/47/bd51e1f5ac2623b18d03d4aee3deca9a1fdcfa62bde3c713f0453901c977/pantheon_legends-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4951a6aadcd5a9b93ff477f32675d832c0c09631d9fdacb0b7f3ffc47a1615a2",
"md5": "7631fef053c3a747151db8862322d834",
"sha256": "15a6cbd5c1beb2929cbca3e0b109f663381d9b1280180ea784de59c36f613063"
},
"downloads": -1,
"filename": "pantheon_legends-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "7631fef053c3a747151db8862322d834",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 18683,
"upload_time": "2025-09-08T03:59:24",
"upload_time_iso_8601": "2025-09-08T03:59:24.399757Z",
"url": "https://files.pythonhosted.org/packages/49/51/a6aadcd5a9b93ff477f32675d832c0c09631d9fdacb0b7f3ffc47a1615a2/pantheon_legends-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-08 03:59:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SpartanDigitalDotNet",
"github_project": "pantheon-legends",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pantheon-legends"
}
JSON
