cpz-ai 1.8.8

CPZAI Python SDK for trading strategies, market data, and multi-broker execution

CPZAI Python SDK

Unified Trading, Market Data, AI Assistant, and Analytics Platform

---

Overview

The CPZAI Python SDK provides a unified interface for systematic trading and quantitative research:

Feature	Description
Simons AI Assistant	AI-powered trading analysis, strategy help, and code generation
Trading Execution	Multi-broker order management with audit trails
Market Data	Stocks, crypto, options via Alpaca and Twelve Data
Economic Data	800,000+ FRED time series
SEC Filings	10-K, 10-Q, 8-K, insider transactions via EDGAR
Social Sentiment	Reddit and Stocktwits analysis
Technical Indicators	100+ indicators including SMA, EMA, RSI, MACD

---

Installation

pip install cpz-ai

---

Quick Start

from cpz import CPZClient

client = CPZClient()

# Market Data
bars = client.data.bars("AAPL", timeframe="1D", limit=100)
quotes = client.data.quotes(["AAPL", "MSFT", "GOOGL"])
news = client.data.news("TSLA", limit=5)

# Economic Data
gdp = client.data.economic("GDP")
unemployment = client.data.economic("UNRATE")

# SEC Filings
filings = client.data.filings("AAPL", form="10-K")

# Social Sentiment
sentiment = client.data.sentiment("GME")

# Technical Indicators
rsi = client.data.rsi("AAPL", period=14)
macd = client.data.macd("AAPL")

# Trading Execution
client.execution.use_broker("alpaca", environment="paper")
order = client.execution.order(
    symbol="AAPL",
    qty=10,
    side="buy",
    strategy_id="my-strategy"
)

# Simons AI Assistant
response = client.simons.chat("Analyze AAPL for momentum trading")
print(response.content)

---

Simons AI Assistant

Simons is an AI assistant specialized in quantitative trading. Access it via SDK to get trading analysis, strategy help, and code generation.

Requirements: Enable the simons scope on your API key in Settings > API Keys

Simple Chat

from cpz import CPZClient

client = CPZClient()

# Get a complete response
response = client.simons.chat("Analyze AAPL for momentum trading opportunities")
print(response.content)

# Check usage stats
print(f"Model: {response.model}")
print(f"Cost: ${response.cost:.4f}")

Streaming Responses

Stream responses token-by-token as they're generated (like ChatGPT):

from cpz import CPZClient

client = CPZClient()

# Stream the response
for chunk in client.simons.stream("Write a simple moving average crossover strategy"):
    if chunk.type == "text":
        print(chunk.content, end="", flush=True)
    elif chunk.type == "done":
        print()  # Newline at end

Strategy Context

Provide a strategy ID to give Simons access to your strategy files:

import os
from cpz import CPZClient

client = CPZClient()
strategy_id = os.getenv("CPZ_AI_STRATEGY_ID")

response = client.simons.chat(
    message="Analyze my strategy's risk profile and suggest improvements",
    strategy_id=strategy_id,
    mode="ask"  # "ask" (read-only), "agent" (code changes), "debug" (debugging)
)

print(response.content)

# In agent mode, check for code proposals
if response.proposals:
    for proposal in response.proposals:
        print(f"Proposed change: {proposal.file_path}")
        print(proposal.diff)

Memory Management

Simons remembers your preferences across conversations:

from cpz import CPZClient

client = CPZClient()

# Get your Simons memory
memory = client.simons.get_memory()
print(f"Preferences: {memory.preferences}")
print(f"Learned facts: {memory.facts}")

# Update preferences
client.simons.update_memory(
    preferences={"risk_profile": "moderate", "preferred_sectors": ["tech", "healthcare"]},
    facts=["Prefers momentum strategies", "Uses 1% position sizing"]
)

Async Support

Use async methods for non-blocking operations:

import asyncio
from cpz import AsyncCPZClient

async def main():
    client = AsyncCPZClient()
    
    # Async chat
    response = await client.simons.chat("Analyze the S&P 500")
    print(response.content)
    
    # Async streaming
    async for chunk in client.simons.stream("Write a backtest"):
        print(chunk.content, end="", flush=True)

asyncio.run(main())

---

Trading

Broker Configuration

from cpz import CPZClient

client = CPZClient()

# Single account setup
client.execution.use_broker("alpaca", environment="paper")
client.execution.use_broker("alpaca", environment="live")

# Multi-account: Use account_id to select specific account
client.execution.use_broker("alpaca", account_id="PA3FHUB575J3")

When account_id is provided, the SDK matches credentials by account ID exclusively, ignoring the environment parameter.

Order Placement

# Simple order placement
order = client.execution.order(
    symbol="AAPL",
    qty=10,
    side="buy",
    strategy_id="my-strategy"
)
print(f"Order: {order.id} - {order.status}")

# Full control with OrderSubmitRequest
from cpz import OrderSubmitRequest, OrderSide, OrderType, TimeInForce

request = OrderSubmitRequest(
    symbol="AAPL",
    side=OrderSide.BUY,
    qty=10,
    order_type=OrderType.LIMIT,
    time_in_force=TimeInForce.GTC,
    limit_price=150.00,
    strategy_id="my-strategy"
)
order = client.execution.submit_order(request)

Account and Positions

account = client.execution.get_account()
print(f"Buying Power: ${account.buying_power:,.2f}")

positions = client.execution.get_positions()
for pos in positions:
    print(f"{pos.symbol}: {pos.qty} shares @ ${pos.avg_entry_price}")

---

Data API

Market Data

# Stock bars
bars = client.data.bars("AAPL", timeframe="1D", limit=100)
for bar in bars[-5:]:
    print(f"{bar.timestamp}: O={bar.open} H={bar.high} L={bar.low} C={bar.close}")

# Crypto bars
btc = client.data.bars("BTC/USD", timeframe="1H", limit=50)

# Latest quotes
quotes = client.data.quotes(["AAPL", "MSFT", "GOOGL"])

# News articles
news = client.data.news("TSLA", limit=10)

# Options chain
options = client.data.options("AAPL", option_type="call")

Economic Data (FRED)

# Access 800,000+ economic time series
gdp = client.data.economic("GDP")
unemployment = client.data.economic("UNRATE", limit=12)
cpi = client.data.economic("CPIAUCSL")
fed_rate = client.data.economic("FEDFUNDS")

# Search for series
results = client.data.fred.search("housing prices")

SEC Filings (EDGAR)

# Get filings by type
filings = client.data.filings("AAPL", form="10-K", limit=5)

# Get structured financial data
facts = client.data.edgar.get_facts("AAPL")
revenue = client.data.edgar.get_concept("AAPL", "Revenue")

# Insider transactions
insider = client.data.edgar.insider_transactions("TSLA")

Social Sentiment

# Aggregated sentiment
sentiment = client.data.sentiment("GME")
print(f"Score: {sentiment['score']}, Bullish: {sentiment['bullish_pct']:.1%}")

# Trending symbols
trending = client.data.trending()

# Social posts
posts = client.data.social.get_posts(symbols=["AAPL"], source="reddit")

Technical Indicators

IMPORTANT: To use technical indicators, you must have Twelve Data connected in the CPZAI platform. Go to the Data page and connect your Twelve Data API key.

# Via Twelve Data (100+ indicators available)
# Requires Twelve Data connection on the Data page

# Trend indicators
sma = client.data.sma("AAPL", period=20)
ema = client.data.ema("AAPL", period=20)
bbands = client.data.bbands("AAPL", period=20)
vwap = client.data.vwap("AAPL")
ichimoku = client.data.ichimoku("AAPL")
supertrend = client.data.supertrend("AAPL")

# Momentum indicators
rsi = client.data.rsi("AAPL", period=14)
macd = client.data.macd("AAPL")
stoch = client.data.stoch("AAPL")
adx = client.data.adx("AAPL", period=14)
cci = client.data.cci("AAPL", period=20)
mfi = client.data.mfi("AAPL", period=14)
willr = client.data.willr("AAPL", period=14)

# Volatility indicators
atr = client.data.atr("AAPL", period=14)

# Volume indicators
obv = client.data.obv("AAPL")

# Direct provider access for full control
keltner = client.data.twelve.get_keltner("AAPL", period=20, multiplier=2)
donchian = client.data.twelve.get_donchian("AAPL", period=20)
aroon = client.data.twelve.get_aroon("AAPL", period=14)
force_index = client.data.twelve.get_force_index("AAPL")

# Access ANY TwelveData indicator by name
custom = client.data.indicator("stochrsi", "AAPL", time_period=14)

# Candlestick pattern recognition
patterns = client.data.twelve.get_pattern("cdl_doji", "AAPL")

Direct Provider Access

For advanced use cases, access providers directly:

# Alpaca-specific features
crypto = client.data.alpaca.get_crypto_bars("ETH/USD", "1H")
options = client.data.alpaca.get_options_chain("SPY")

# FRED-specific features
categories = client.data.fred.categories()

# Twelve Data-specific
forex = client.data.twelve.get_forex("EUR/USD")

---

Architecture

CPZClient
├── simons             Simons AI Assistant
│   ├── chat()         Send message, get response
│   ├── stream()       Stream response tokens
│   ├── get_memory()   Get user preferences
│   └── update_memory() Update preferences
│
├── execution          Trading operations
│   ├── use_broker()   Configure broker connection
│   ├── order()        Place orders
│   ├── get_account()  Account information
│   └── get_positions() Current positions
│
├── data               Market and reference data
│   ├── bars()         OHLCV price data
│   ├── quotes()       Real-time quotes
│   ├── news()         News articles
│   ├── options()      Options chains
│   ├── economic()     FRED economic data
│   ├── filings()      SEC EDGAR filings
│   ├── sentiment()    Social sentiment
│   └── [provider]     Direct provider access
│
└── platform           CPZAI platform services
    ├── health()       Platform status
    └── list_tables()  Available data tables

---

Configuration

Environment Variables

Variable	Description	Required
CPZ_AI_API_KEY	CPZAI API key	Yes
CPZ_AI_SECRET_KEY	CPZAI API secret	Yes
CPZ_AI_STRATEGY_ID	Strategy ID for orders	Yes (for trading)

Getting Started

1. Get CPZAI Credentials: https://ai.cpz-lab.com/settings?tab=api-keys
2. Configure Trading Accounts: https://ai.cpz-lab.com/execution

Alpaca market data uses your trading account credentials automatically.

---

CLI Reference

# List available brokers
cpz-ai broker list

# Configure broker connection
cpz-ai broker use alpaca --env paper
cpz-ai broker use alpaca --env live --account-id "YOUR_ACCOUNT_ID"

# Stream quotes
cpz-ai stream quotes AAPL,MSFT,GOOGL --broker alpaca --env paper

---

Error Handling

from cpz.common.errors import CPZBrokerError

try:
    order = client.execution.order(
        symbol="AAPL",
        qty=10,
        side="buy",
        strategy_id="my-strategy"
    )
except CPZBrokerError as e:
    print(f"Order failed: {e}")

---

Testing

# Run tests
make test

# Run with coverage
pytest --cov=cpz --cov-report=term-missing

---

Python Compatibility

Version	Status
Python 3.9	Supported
Python 3.10	Supported
Python 3.11	Supported
Python 3.12	Supported

---

Documentation

• User Guide - Comprehensive usage documentation
• Contributing - Contribution guidelines
• Security - Security policy
• Changelog - Version history

---

Support

• Documentation: https://ai.cpz-lab.com/
• Repository: https://github.com/CPZ-Lab/cpz-py
• Email: [e-mail]

---

_{Built by CPZAI}