Metadata-Version: 2.1
Name: investify-data
Version: 0.1.0a1
Summary: Python client for the Investify Data API (wos-data-api)
Author-Email: Investify <dev@investify.vn>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Project-URL: Repository, https://gitlab.com/investify-vn/wealth-os/investify-data
Project-URL: Documentation, https://gitlab.com/investify-vn/wealth-os/investify-data#readme
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Description-Content-Type: text/markdown

# investify-data

Python client for the **Investify Data API** (`wos-data-api`) — an AI-agent-first financial-data platform covering Vietnamese market data, company profiles, financial ratios, and searchable document collections.

## Installation

```bash
pip install investify-data
```

Python 3.10+ required.

## Quickstart — Sync

```python
from investify_data import DataClient

with DataClient(api_key="ifyu_...") as client:
    # Discovery
    categories = client.catalog.list_categories()
    tables = client.catalog.list_tables(category="equities")
    schema = client.catalog.describe_table("financial_ratio", group="valuation")

    # Table query — same operators as REST (eq, in, not_in, gte/lte/gt/lt)
    rows = client.tables.query(
        "stock_price_history",
        columns=["symbol", "date", "close"],
        filters={"symbol": "VNM", "date": {"gte": "-30d"}},
        sort="date.desc",
        limit=5,
    )

    # Document search (semantic)
    hits = client.collections.search(
        "market_news",
        q="lãi suất ngân hàng tác động đến cổ phiếu",
        metadata_filters={"topic": {"in": ["banking", "macro"]}},
        limit=5,
    )
```

## Async

```python
import asyncio
from investify_data import AsyncDataClient

async def main():
    async with AsyncDataClient(api_key="ifyu_...") as client:
        rows = await client.tables.query("stock_price_history", filters={"symbol": "VNM"}, limit=5)
        print(rows)

asyncio.run(main())
```

## Authentication

Three credential types, picked up from the `api_key` prefix:

| Prefix | Role | Use |
|--------|------|-----|
| `ifyu_` | User | Direct queries scoped to the user's permission |
| `ifys_` | Tenant | `on_behalf_of=<user_uuid>` required for data; admin ops without |
| `ifym_` | Super admin | System-wide; `on_behalf_of=<user_uuid>` for data queries |

```python
# Tenant key querying on behalf of an end-user
DataClient(api_key="ifys_...", on_behalf_of="550e8400-e29b-41d4-a716-446655440000")
```

## Error handling

```python
from investify_data import DataClient, NotFound, InvalidRequest, Unauthorized

try:
    client.tables.query("nonexistent")
except NotFound:
    ...
except InvalidRequest as err:
    print(err.code, err.detail)
except Unauthorized:
    ...
```

All exceptions inherit from `InvestifyDataError`. `APIError` subclasses (`Unauthorized`, `Forbidden`, `NotFound`, `InvalidRequest`, `RateLimited`, `ServerError`) carry `status_code`, `code`, and `detail`. `TransportError` wraps network/TLS/timeout failures.

## Security

- **Never commit your API key.** Read it from an env var or secret store.
- The SDK redacts keys in `repr()`, logs, and error messages — only the 5-char prefix is shown (e.g., `ifyu_***`).
- HTTPS is the default (`https://data.investify.vn`). Using `http://` with a production key triggers a runtime warning; local/LAN hosts (`localhost`, `127.0.0.1`, `investify.k8s`) are exempt.
- If you pin a custom `base_url`, keep it behind TLS.

## Configuration

```python
DataClient(
    api_key="ifyu_...",
    base_url="https://data.investify.vn",  # override for dev (e.g. http://investify.k8s:30702)
    on_behalf_of=None,                      # set for tenant/master keys
    timeout=30.0,                           # seconds
    user_agent="my-app/1.0",                # optional
)
```

## Links

- Source: <https://gitlab.com/investify-vn/core/investify-data>
- Data API docs: internal `wos-docs/data-api/`

## License

MIT
