PORTIQA Python

portiqa is the dependency-free Python client for the PORTIQA Portfolio Analysis API. It sends typed portfolio inputs to POST https://portiqa.ai/evaluate and returns typed response models. All scoring and analysis stays on the PORTIQA service; this package contains no scoring logic.

Requirements

• Python 3.9 or newer
• A PORTIQA API key from the PORTIQA dashboard

Installation

Install the official package from PyPI:

python -m pip install portiqa

For editable local development from a clone:

python -m pip install -e .

Quick start

Store the key outside your source code:

export PORTIQA_API_KEY="ptq_your_api_key"

PowerShell:

$env:PORTIQA_API_KEY = "ptq_your_api_key"

Then evaluate a portfolio:

from portiqa import EvaluationRequest, PortiqaClient, Position

client = PortiqaClient(timeout=20.0)
request = EvaluationRequest(
    risk_level="medium",
    cash_balance=5_000,
    positions=(
        Position(ticker="AAPL", market_value=25_000),
        Position(ticker="MSFT", market_value=22_000),
        Position(ticker="NVDA", market_value=8_000),
    ),
)

response = client.evaluate(request)
print(response.evaluation.score)
print(response.evaluation.status)

You can pass the key directly when an environment variable is not suitable:

client = PortiqaClient(api_key="ptq_your_api_key", timeout=10.0)

An explicit api_key takes precedence over PORTIQA_API_KEY. Never hard-code or commit a real key.

Models

Each Position requires a ticker and at least one of:

• market_value: the value already known for the position; or
• amount: the number of units, which PORTIQA combines with its latest available close price when market_value is absent.

risk_level accepts "low", "medium", or "high". Position values and the cash balance must be finite, non-negative numbers. Invalid local inputs raise ValidationError before any request is made.

Stable response fields are typed, while the complete server response remains available through response.raw and response.evaluation.raw. Newly added API fields are therefore accessible without waiting for an SDK release.

Errors and timeouts

All SDK exceptions inherit from PortiqaError:

from portiqa import APITimeoutError, PortiqaError, RateLimitError

try:
    response = client.evaluate(request)
except RateLimitError as exc:
    print(f"Limit reached (HTTP {exc.status_code})")
except APITimeoutError:
    print("PORTIQA did not respond before the configured timeout")
except PortiqaError as exc:
    print(f"PORTIQA request failed: {exc}")

The timeout defaults to 20 seconds. The client does not retry automatically, leaving retry and backoff policy under the caller's control.

Development

The tests use standard-library mocks and never contact the live API:

python -m unittest discover -s tests -v

See the API reference, OpenAPI specification, and security policy for more information.

PORTIQA output is quantitative information, not investment advice. See the financial disclaimer.

License

Released under the MIT License.