Skip to content

CLAUDE.md

Latest commit

 

History

History
61 lines (37 loc) · 2.88 KB

CLAUDE.md

File metadata and controls

61 lines (37 loc) · 2.88 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

VynFi Python SDK — the primary typed Python client for the VynFi synthetic financial data API. Supports Python 3.9–3.13. Currently synchronous only. The Rust SDK at /home/michael/DEV/Repos/VynFi-rust/VynFi-rust is the reference API surface — this SDK must match it.

Commands

# Install for development
pip install -e ".[dev]"

# Run all tests
pytest -v

# Run a single test file
pytest tests/test_client.py

# Run tests matching a pattern
pytest -k "test_generate"

# Lint
ruff check src/ tests/

# Format check / fix
ruff format --check src/ tests/
ruff format src/ tests/

# Type check
mypy src/vynfi/ --ignore-missing-imports

Architecture

The SDK follows a resource-based pattern with three layers:

  1. Client facade (src/vynfi/__init__.py) — VynFi class is the public entry point. Composes all 12 resource clients as attributes: .jobs, .catalog, .usage, .api_keys, .quality, .webhooks, .billing, .configs, .credits, .sessions, .scenarios, .notifications. Convenience shortcuts: .generate(), .generate_quick().

  2. HTTP layer (src/vynfi/_client.py) — SyncClient handles all HTTP via httpx. Retry with exponential backoff for 429/5xx. Maps HTTP status codes to exception types in _exceptions.py (401, 402, 403, 404, 409, 422, 429, 5xx).

  3. Resource modules (src/vynfi/resources/) — Each file wraps SyncClient with domain-specific methods. All methods return Pydantic models from _types.py.

  4. Ecosystem integrations (src/vynfi/integrations/) — Optional pandas and polars modules for DataFrame conversion of job output and usage data. Gated by optional dependencies (pip install vynfi[pandas]).

All API response types are Pydantic v2 models in _types.py. Some API endpoints return camelCase JSON (sessions, scenarios, credits, configs, templates) — these use the _CamelModel base with alias_generator. The package is PEP 561 typed (py.typed marker).

Linting Notes

  • Ruff targets Python 3.9, line length 100, rules: E, F, I, UP, B, SIM.
  • api_keys.py and webhooks.py have ruff ignores (UP006, UP035, UP045) because they define a list() method that shadows the builtin — use typing.List in those files, not list[...].
  • mypy runs in strict mode with the Pydantic plugin.

Testing

Tests use pytest + respx (httpx mock). test_client.py covers auth, error mapping, retry logic, and resource accessibility. test_resources.py covers every resource endpoint with mock responses matching actual API shapes. CI runs the full matrix across Python 3.9–3.13.

API Parity

The Rust SDK is the reference. When the API adds endpoints, update both SDKs. The resources map 1:1: jobs, catalog, usage, api_keys, quality, webhooks, billing, configs, credits, sessions, scenarios, notifications.