Metadata-Version: 2.4
Name: sablier-sdk
Version: 0.1.0
Summary: Python SDK for Sablier Market Scenario Generator - Create scenario-conditioned synthetic financial data
Author: Sablier Team
License: MIT
Project-URL: Repository, https://github.com/michu5696/sablier-sdk
Project-URL: Issues, https://github.com/michu5696/sablier-sdk/issues
Keywords: finance,synthetic-data,scenarios,quantitative-finance,machine-learning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: pandas>=1.5.0
Requires-Dist: numpy>=1.23.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: scikit-optimize>=0.9.0
Provides-Extra: viz
Requires-Dist: seaborn>=0.12.0; extra == "viz"
Requires-Dist: plotly>=5.0.0; extra == "viz"
Provides-Extra: stats
Requires-Dist: scipy>=1.11.0; extra == "stats"
Requires-Dist: statsmodels>=0.14.0; extra == "stats"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: all
Requires-Dist: sablier-sdk[dev,stats,viz]; extra == "all"
Dynamic: license-file

# Sablier SDK

Python SDK for the Sablier Market Scenario Generator - Create scenario-conditioned synthetic financial data for portfolio testing and risk analysis.

## Installation

### From PyPI
```bash
pip install sablier-sdk
```

### From Source
```bash
# Clone the repository
git clone https://github.com/michu5696/sablier-sdk.git
cd sablier-sdk/sdk

# Install in editable mode
pip install -e ".[all]"
```

### Requirements
- Python 3.8 or higher
- Core dependencies: requests, pandas, numpy, pydantic, python-dateutil, matplotlib

## Quick Start

### Using Template Projects 

Template projects provide pre-configured models that you can use immediately. This is the fastest way to get started:

```python
from sablier import SablierClient

# Initialize client with your API URL
client = SablierClient(api_url="https://your-backend.run.app")

# List available projects (includes template projects)
projects = client.list_projects()

# Find the template project
template_project = [p for p in projects if p.is_template][0]
print(f"Using template: {template_project.name}")

# Get the first model from the template
models = template_project.list_models()
model = models[0]
print(f"Model: {model.name}")

# Create a scenario on the template model
scenario = model.create_scenario(
    simulation_date="2020-03-15",  # COVID crash date
    name="COVID Scenario"
)

# Simulate the scenario to generate synthetic market paths
result = scenario.simulate(n_samples=50)

# Access the forecast data
forecast_data = result.get('forecast_windows', [])
print(f"Generated {len(forecast_data)} forecast samples")

# Visualize the forecasts
scenario.plot_forecasts(save=True, save_dir="./forecasts")

# Test a portfolio against the scenario
portfolio = client.create_portfolio(
    name="Test Portfolio",
    target_set=model.get_target_set(),
    asset_configs={
        "10-Year Treasury Constant Maturity Rate": {
            "type": "treasury_bond",
            "params": {
                "coupon_rate": 0.04,  # 4% coupon rate
                "face_value": 1000,
                "issue_date": "2018-08-15",
                "payment_frequency": 2  # Semi-annual
            }
        },
        "20-Year Treasury Constant Maturity Rate": {
            "type": "treasury_bond",
            "params": {
                "coupon_rate": 0.042,  # 4.2% coupon rate
                "face_value": 1000,
                "issue_date": "2018-08-15",
                "payment_frequency": 2
            }
        },
        "30-Year Treasury Constant Maturity Rate": {
            "type": "treasury_bond",
            "params": {
                "coupon_rate": 0.041,  # 4.1% coupon rate
                "face_value": 1000,
                "issue_date": "2018-08-15",
                "payment_frequency": 2
            }
        }
    }
)

# Set portfolio weights
portfolio.set_weights({
    "10-Year Treasury Constant Maturity Rate": 0.4,
    "20-Year Treasury Constant Maturity Rate": -0.3,
    "30-Year Treasury Constant Maturity Rate": 0.3
})

# Run portfolio test
test = portfolio.test(scenario)

# View portfolio metrics
print(f"Sharpe Ratio: {test.summary_stats['sharpe']:.3f}")
print(f"Total Return: {test.summary_stats['total_return']:.2%}")
print(f"Max Drawdown: {test.summary_stats['max_drawdown']:.2%}")

# Plot portfolio performance evolution
test.plot_evolution('pnl')
test.plot_evolution('drawdown')
```


## Features

- **Template Projects**: Access pre-trained models immediately
- **Scenario Generation**: Define custom market scenarios with historical or synthetic conditions
- **Synthetic Data**: Generate thousands of realistic market paths
- **Portfolio Testing**: Test portfolios against synthetic scenarios with comprehensive metrics
- **Visualization**: Built-in plotting for scenarios, forecasts, and portfolio performance

## Portfolio Testing

The SDK includes comprehensive portfolio testing capabilities:

```python
# Create portfolio with asset configurations (for bonds, equities, etc.)
portfolio = client.create_portfolio(
    name="Treasury Portfolio",
    target_set=target_set,
    asset_configs={
        "DGS10": {
            "type": "treasury_bond",
            "params": {
                "coupon_rate": 0.04,
                "face_value": 1000,
                "issue_date": "2018-08-15",
                "payment_frequency": 2
            }
        }
    }
)

# Set portfolio weights
portfolio.set_weights({
    "DGS10": 0.6,
    "DGS30": 0.4
})

# Test portfolio against multiple scenarios
test = portfolio.test(scenario)

# Access comprehensive metrics
print(test.summary_stats)
# Returns: Sharpe Ratio, Sortino Ratio, Calmar Ratio, VaR, CVaR, Total Return, Max Drawdown

# Plot time-series evolution
test.plot_evolution('pnl')
test.plot_evolution('returns')
test.plot_evolution('drawdown')
test.plot_evolution('portfolio_value')

# Plot distributions
test.plot_distribution('sharpe_ratio')
test.plot_distribution('total_return')
test.plot_distribution('max_drawdown')
```

## API Key Management

The SDK automatically manages API keys and settings in a local SQLite database:

```python
# First time: SDK will prompt for registration
client = SablierClient(api_url="https://your-backend.run.app")

# Save an API key with a custom name
client.save_api_key(
    api_key="sk_...",
    api_url="https://your-backend.run.app",
    description="production"
)

# List all saved keys
keys = client.list_api_keys()

# Use a specific key by name
client = SablierClient(api_url="https://your-backend.run.app")
# Will use the default key automatically
```

## Examples

See the `examples/` directory for detailed usage examples.

## License

MIT License
