investify-data 0.1.0a1

Python client for the Investify Data API (wos-data-api)

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

pip install investify-data

Python 3.10+ required.

Quickstart — Sync

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

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

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

Error handling

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

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