Metadata-Version: 2.4
Name: finkovsky
Version: 0.4.6
Summary: Typed Python client for the Finkovsky API.
Project-URL: Homepage, https://github.com/daiwanwei/finkovsky-api
Project-URL: Repository, https://github.com/daiwanwei/finkovsky-api
Project-URL: Issues, https://github.com/daiwanwei/finkovsky-api/issues
Author-email: Dai Wan-Wei <galoismoto.san@gmail.com>
License: MIT
Keywords: api-client,finance,finkovsky,openapi,technical-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: attrs>=23.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.5
Requires-Dist: python-dateutil>=2.8
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: openapi-python-client>=0.21; extra == 'dev'
Requires-Dist: pandas>=2.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == 'pandas'
Description-Content-Type: text/markdown

# Finkovsky SDK — Python

Typed Python client for the [Finkovsky API](https://github.com/daiwanwei/finkovsky-api) — technical analysis, equity data, Taiwan market, and economic indicators.

```bash
pip install finkovsky
```

Requires Python 3.10+.

## Three Ways to Use

### 1. Agent / LLM tool call (synchronous)

```python
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`](examples/agent_tool_wrapping.md) for framework-specific wrapping patterns.

### 2. Notebook / quantitative research

```python
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

```python
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

```bash
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.
