Metadata-Version: 2.4
Name: omni-datastream-py
Version: 0.2.0
Summary: Python SDK for Omni Datastream
Author: Autonomous Computer
License: MIT
Project-URL: Homepage, https://secapi.ai/developers
Project-URL: Documentation, https://docs.secapi.ai
Project-URL: Repository, https://github.com/autonomous-computer/omni-datastream
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# omni-datastream-py

Python SDK for [Omni Datastream](https://secapi.ai/developers) -- SEC filings, financial statements, ownership data, and more.

## Installation

```bash
pip install omni-datastream-py
```

## Configuration

```python
from omni_datastream_py import OmniDatastreamClient

client = OmniDatastreamClient(
    api_key="ods_test_...",
    # Optional: override base URL (defaults to https://api.secapi.ai)
    # base_url="http://127.0.0.1:8787",
)
```

You can also authenticate with a Bearer token:

```python
client = OmniDatastreamClient(bearer_token="your-bearer-token")
```

### Environment Variables

| Variable | Description |
|----------|-------------|
| `OMNI_DATASTREAM_API_KEY` | Your Omni Datastream API key (starts with `ods_`) |

### Configuration Options

| Parameter | Default | Description |
|-----------|---------|-------------|
| `api_key` | `None` | API key authentication |
| `bearer_token` | `None` | Bearer token authentication |
| `base_url` | `https://api.secapi.ai` | API base URL |
| `api_version` | `2026-03-19` | API version header |

## Quickstart

```python
import os
from omni_datastream_py import OmniDatastreamClient

client = OmniDatastreamClient(api_key=os.environ["OMNI_DATASTREAM_API_KEY"])

# Resolve a company entity
entity = client.resolve_entity(ticker="AAPL")
print(entity)

# Get the latest 10-K filing
filing = client.latest_filing(ticker="AAPL", form="10-K")
print(filing)

# Extract a specific section
section = client.latest_section(
    section_key="item_1a",
    ticker="AAPL",
    form="10-K",
    mode="compact",
)
print(section)
```

## Common Use Cases

### Financial Statements

```python
# XBRL facts
facts = client.facts(ticker="AAPL", tag="Assets", taxonomy="us-gaap", limit=5)

# Full financial statements
statements = client.all_statements(ticker="AAPL", period="annual", limit=3)
```

### Ownership and Institutional Holdings

```python
# Latest 13F filing (institutional holdings)
holdings = client.latest_13f(cik="0001067983", limit=10)
```

### Market Data

```python
# Market calendar
calendar = client.market_calendar(market="XNYS", duration=3)

# Volatility signal
vol = client.volatility_signal(ticker="AAPL")
```

### Offerings and M&A

```python
# IPO and offering filings
offerings = client.offerings(forms="S-1,424B4", limit=3)
```

### Diagnostics

```python
# Artifact summary (data freshness)
summary = client.artifact_summary()

# System observability
obs = client.observability()
```

## Error Handling

```python
from omni_datastream_py import OmniDatastreamClient, OmniDatastreamError

client = OmniDatastreamClient(api_key="ods_test_...")

try:
    result = client.resolve_entity(ticker="INVALID")
except OmniDatastreamError as e:
    print(f"Status: {e.status}")
    print(f"Payload: {e.payload}")
```

## Scope

The Python SDK covers the full REST surface including:

- Entity resolution and search
- Filing retrieval and section extraction
- XBRL facts and financial statements
- Offerings, market calendar, and volatility signals
- Ownership, insiders, and compensation data
- Institutional holdings (13F)
- Enforcement actions and M&A events
- Artifacts, diagnostics, and observability
- Events, streams, and webhooks

## Links

- [API Documentation](https://docs.secapi.ai)
- [Developer Portal](https://secapi.ai/developers)
- [GitHub Repository](https://github.com/autonomous-computer/omni-datastream)
