cpz-ai 0.1.4

CPZ — Python SDK for Strategy Lab, Risk, Backtesting, and Execution (multi-broker)

CPZ AI — Python SDK

Install

pip install cpz-ai
# dev
pip install -e .[dev]

60-second Quickstart (Sync)

import cpz
from cpz.execution.models import OrderSubmitRequest
from cpz.execution.enums import OrderSide, OrderType, TimeInForce

client = cpz.clients.sync.CPZClient()
client.execution.use_broker("alpaca", env="paper")

order = client.execution.submit_order(OrderSubmitRequest(
    symbol="AAPL",
    side=OrderSide.BUY,
    qty=10,
    type=OrderType.MARKET,
    time_in_force=TimeInForce.DAY,
))
print(order.id, order.status)

Execution Architecture

CPZClient.execution  -->  BrokerRouter  -->  AlpacaAdapter
                              |               ^
                              +---- future brokers (IBKR, Tradier, ...)

Configuration (.env)

Key	Description	Example	Required
CPZ_ENV	SDK environment	dev	No
CPZ_LOG_LEVEL	Log level	INFO	No
CPZ_REQUEST_TIMEOUT_SECONDS	Default request timeout	30	No
ALPACA_ENV	Alpaca environment	paper	Yes (if using Alpaca)
ALPACA_API_KEY_ID	Alpaca API key	AK...	Yes (if using Alpaca)
ALPACA_API_SECRET_KEY	Alpaca API secret	...	Yes (if using Alpaca)

Usage

Selecting a broker

client.execution.use_broker("alpaca", env="paper")

Submit / cancel / replace order (sync)

from cpz.execution.models import OrderSubmitRequest, OrderReplaceRequest
from cpz.execution.enums import OrderSide, OrderType, TimeInForce

req = OrderSubmitRequest(symbol="AAPL", side=OrderSide.BUY, qty=1,
                         type=OrderType.MARKET, time_in_force=TimeInForce.DAY)
order = client.execution.submit_order(req)
client.execution.cancel_order(order.id)
client.execution.replace_order(order.id, OrderReplaceRequest(qty=2))

Async + Streaming

import asyncio
from cpz.clients.async_ import AsyncCPZClient

async def main():
    client = AsyncCPZClient()
    await client.execution.use_broker("alpaca", env="paper")
    async for q in client.execution.stream_quotes(["AAPL", "MSFT"]):
        print(q.symbol, q.bid, q.ask)
        break

asyncio.run(main())

Get account / positions

acct = client.execution.get_account()
positions = client.execution.get_positions()

CLI

cpz-ai broker list
cpz-ai broker use alpaca --env paper
cpz-ai order submit --symbol AAPL --side buy --qty 10 --type market --tif day
cpz-ai order get --id <id>
cpz-ai positions
cpz-ai stream quotes --symbols AAPL,MSFT

Error handling

Catch cpz.common.errors.CPZBrokerError. Broker errors are mapped to CPZ errors.

Logging & Redaction

Structured JSON logging via structlog, with redaction of Authorization, ALPACA_API_SECRET_KEY, and similar. Configure level via CPZ_LOG_LEVEL.

Testing & Quality

• make test (coverage goal ≥ 85%)
• mypy --strict

Contributing

Style: ruff/black/isort, pre-commit, branch naming. See CONTRIBUTING.md.

Versioning & Release

Bump version in pyproject.toml, build, and publish to PyPI.

Roadmap

Next brokers: IBKR, Tradier, …

Security

See SECURITY.md. No LICENSE file is included intentionally.