finkovsky 0.5.0

Typed Python client for the Finkovsky API.

Finkovsky SDK — Python

Typed Python client for the Finkovsky API — technical analysis, equity data, Taiwan market, and economic indicators.

pip install finkovsky

Requires Python 3.10+.

Three Ways to Use

1. Agent / LLM tool call (synchronous)

from finkovsky import Client, CreditError, RateLimitError

fk = Client(api_key="sk-...")  # or set FINKOVSKY_API_KEY

try:
    result = fk.ta.analyze(symbol="AAPL")
    print(result)
except CreditError as e:
    print(f"out of credits: {e.remaining}/{e.required}")
except RateLimitError as e:
    print(f"slow down: retry after {e.retry_after}s")

See examples/agent_tool_wrapping.md for framework-specific wrapping patterns.

2. Notebook / quantitative research

from finkovsky import Client
from finkovsky.pandas import to_dataframe

fk = Client()
df = to_dataframe(fk.tw.ohlcv(symbol="2330", days=90))
df["close"].plot()

Install the pandas extra: pip install 'finkovsky[pandas]'.

3. Async backend service

import asyncio
from finkovsky import AsyncClient

async def main():
    async with AsyncClient() as fk:
        result = await fk.ta.analyze(symbol="AAPL")
        print(result)

asyncio.run(main())

Authentication

• Client(api_key="sk-...") — explicit key.
• Client() — reads FINKOVSKY_API_KEY; raises AuthError if neither is set.
• Client(api_key="sk-...", base_url="https://staging.example.com") — override for staging/self-hosted deployments.

Error Hierarchy

Exception	HTTP trigger	Meaning
AuthError	401, 403, missing key	Credentials need fixing.
CreditError	402	Out of credits; carries remaining / required.
RateLimitError	429	Too many requests; carries retry_after.
APIError	other 4xx, 5xx	Carries status_code, body, request_id.
ValidationError	client-side	Response could not be parsed into the expected schema.

Endpoint Reference

All routes are available via client.<namespace>.<method>(...). The generated typed surface lives in src/finkovsky/_facade.py.

Development

cd sdk/python
pip install -e '.[dev]'
./scripts/gen.sh          # regenerate from a running API
./scripts/gen.sh --check  # drift check
pytest -m "not integration"

License

MIT — same as the parent repository.