fintom8 0.1.0__tar.gz

fintom8-0.1.0/.env.example

@@ -0,0 +1,25 @@
+# Copy to .env in your project. Never commit .env. Set LLM_MODEL + matching key(s).
+
+LLM_MODEL=gemini/gemini-3.5-flash
+LLM_TEMPERATURE=0.0
+
+# Gemini API (default)
+# LLM_MODEL=gemini/gemini-3.5-flash
+# GEMINI_API_KEY=
+
+# Vertex AI
+# LLM_MODEL=vertex_ai/gemini-3.5-flash
+# VERTEXAI_PROJECT=
+# VERTEXAI_LOCATION=eu
+# Also run: gcloud auth application-default login
+
+# OpenAI
+# LLM_MODEL=gpt-4o
+# OPENAI_API_KEY=
+# OPENAI_API_BASE=
+
+# Azure OpenAI (use your deployment name)
+# LLM_MODEL=azure/<deployment-name>
+# AZURE_API_KEY=
+# AZURE_API_BASE=https://<resource>.openai.azure.com
+# AZURE_API_VERSION=2024-10-21

fintom8-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.venv/
+.env
+*.pyc

fintom8-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: fintom8
+Version: 0.1.0
+Summary: LiteLLM connector for Gemini, Vertex AI, OpenAI, and Azure — chat, stream, and document extract.
+Project-URL: Homepage, https://github.com/fintom8/f_templates
+Project-URL: Documentation, https://github.com/fintom8/f_templates/tree/main/fintom8
+License: MIT
+Keywords: azure,gemini,litellm,llm,openai,vertex
+Classifier: Development Status :: 4 - Beta
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: litellm<2.0.0,>=1.94.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fintom8
+
+LiteLLM connector for **Gemini / Vertex AI / OpenAI / Azure**. Chat, stream, and document extract. Students install with pip and call a few methods — keys stay in `.env`.
+
+```bash
+pip install fintom8
+```
+
+```python
+from fintom8 import LLM
+
+llm = LLM()  # reads .env / environment
+print(llm.chat("Summarize this invoice").text)
+```
+
+Local development from this repo:
+
+```bash
+pip install -e ./fintom8
+# or: pip install -e "./fintom8[dev]"
+```
+
+## Configuration
+
+Resolution order: **constructor kwargs / `LLMConfig` > environment > defaults**.
+
+Copy [`.env.example`](./.env.example) to `.env` in your project (never commit it).
+
+| Param | Env | Default | When needed |
+|-------|-----|---------|-------------|
+| `model` | `LLM_MODEL` | `gemini/gemini-3.5-flash` | always |
+| `temperature` | `LLM_TEMPERATURE` | `0.0` | optional |
+| `num_retries` | — | `3` | optional |
+| `api_key` | `GEMINI_API_KEY` / `OPENAI_API_KEY` / `AZURE_API_KEY` (from model prefix) | unset | Gemini / OpenAI / Azure |
+| `api_base` | `AZURE_API_BASE` / `OPENAI_API_BASE` | unset | Azure (required) |
+| `api_version` | `AZURE_API_VERSION` | `2024-10-21` | Azure |
+| `vertex_project` | `VERTEXAI_PROJECT` | unset | Vertex |
+| `vertex_location` | `VERTEXAI_LOCATION` | `eu` | Vertex |
+
+```python
+from fintom8 import LLM, LLMConfig
+
+llm = LLM()  # env defaults
+llm = LLM(model="gpt-4o", api_key="sk-...", temperature=0)
+llm = LLM(LLMConfig(
+    model="azure/my-deploy",
+    api_key="...",
+    api_base="https://....openai.azure.com",
+    api_version="2024-10-21",
+))
+```
+
+### Switch provider
+
+| `LLM_MODEL` | Env |
+|-------------|-----|
+| `gemini/gemini-3.5-flash` | `GEMINI_API_KEY` |
+| `vertex_ai/gemini-3.5-flash` | `VERTEXAI_PROJECT` + `VERTEXAI_LOCATION` + ADC (`gcloud auth application-default login`) |
+| `gpt-4o` | `OPENAI_API_KEY` |
+| `azure/<deployment>` | `AZURE_API_KEY` + `AZURE_API_BASE` + `AZURE_API_VERSION` |
+
+## Usage
+
+```python
+from fintom8 import LLM
+
+llm = LLM()
+
+resp = llm.chat("Hello")
+resp = llm.chat(
+    [{"role": "user", "content": "Extract the invoice total"}],
+    response_schema={
+        "type": "object",
+        "properties": {"total": {"type": "number"}},
+        "required": ["total"],
+    },
+    schema_name="Invoice",
+)
+print(resp.text, resp.data, resp.usage)
+
+for chunk in llm.stream([{"role": "user", "content": "Write a haiku"}]):
+    print(chunk, end="", flush=True)
+
+resp = llm.extract("invoice.pdf", response_schema={...})
+```
+
+Async twins for FastAPI / async scripts: `achat`, `astream`, `aextract`.
+
+Structured-output helpers (also used internally): `json_schema_response_format`, `enforce_strict`, `inline_refs`.
+
+Failures raise `Fintom8Error`.
+
+See [`examples/chat.py`](./examples/chat.py) and [`examples/extract.py`](./examples/extract.py).
+
+## Publish (maintainers)
+
+1. Install dev extras and run tests:
+
+   ```bash
+   cd fintom8
+   pip install -e ".[dev]"
+   pytest
+   python -c "from fintom8 import LLM"
+   ```
+
+2. Build:
+
+   ```bash
+   python -m build
+   ```
+
+3. Upload to TestPyPI first, then PyPI:
+
+   ```bash
+   python -m twine upload --repository testpypi dist/*
+   python -m twine upload dist/*
+   ```
+
+4. Tag for CI Trusted Publishing (OIDC). Create the PyPI project once and add a GitHub environment `pypi` with Trusted Publisher pointing at `.github/workflows/publish-fintom8.yml`. Then:
+
+   ```bash
+   git tag fintom8-v0.1.0
+   git push origin fintom8-v0.1.0
+   ```

fintom8-0.1.0/README.md

@@ -0,0 +1,124 @@
+# fintom8
+
+LiteLLM connector for **Gemini / Vertex AI / OpenAI / Azure**. Chat, stream, and document extract. Students install with pip and call a few methods — keys stay in `.env`.
+
+```bash
+pip install fintom8
+```
+
+```python
+from fintom8 import LLM
+
+llm = LLM()  # reads .env / environment
+print(llm.chat("Summarize this invoice").text)
+```
+
+Local development from this repo:
+
+```bash
+pip install -e ./fintom8
+# or: pip install -e "./fintom8[dev]"
+```
+
+## Configuration
+
+Resolution order: **constructor kwargs / `LLMConfig` > environment > defaults**.
+
+Copy [`.env.example`](./.env.example) to `.env` in your project (never commit it).
+
+| Param | Env | Default | When needed |
+|-------|-----|---------|-------------|
+| `model` | `LLM_MODEL` | `gemini/gemini-3.5-flash` | always |
+| `temperature` | `LLM_TEMPERATURE` | `0.0` | optional |
+| `num_retries` | — | `3` | optional |
+| `api_key` | `GEMINI_API_KEY` / `OPENAI_API_KEY` / `AZURE_API_KEY` (from model prefix) | unset | Gemini / OpenAI / Azure |
+| `api_base` | `AZURE_API_BASE` / `OPENAI_API_BASE` | unset | Azure (required) |
+| `api_version` | `AZURE_API_VERSION` | `2024-10-21` | Azure |
+| `vertex_project` | `VERTEXAI_PROJECT` | unset | Vertex |
+| `vertex_location` | `VERTEXAI_LOCATION` | `eu` | Vertex |
+
+```python
+from fintom8 import LLM, LLMConfig
+
+llm = LLM()  # env defaults
+llm = LLM(model="gpt-4o", api_key="sk-...", temperature=0)
+llm = LLM(LLMConfig(
+    model="azure/my-deploy",
+    api_key="...",
+    api_base="https://....openai.azure.com",
+    api_version="2024-10-21",
+))
+```
+
+### Switch provider
+
+| `LLM_MODEL` | Env |
+|-------------|-----|
+| `gemini/gemini-3.5-flash` | `GEMINI_API_KEY` |
+| `vertex_ai/gemini-3.5-flash` | `VERTEXAI_PROJECT` + `VERTEXAI_LOCATION` + ADC (`gcloud auth application-default login`) |
+| `gpt-4o` | `OPENAI_API_KEY` |
+| `azure/<deployment>` | `AZURE_API_KEY` + `AZURE_API_BASE` + `AZURE_API_VERSION` |
+
+## Usage
+
+```python
+from fintom8 import LLM
+
+llm = LLM()
+
+resp = llm.chat("Hello")
+resp = llm.chat(
+    [{"role": "user", "content": "Extract the invoice total"}],
+    response_schema={
+        "type": "object",
+        "properties": {"total": {"type": "number"}},
+        "required": ["total"],
+    },
+    schema_name="Invoice",
+)
+print(resp.text, resp.data, resp.usage)
+
+for chunk in llm.stream([{"role": "user", "content": "Write a haiku"}]):
+    print(chunk, end="", flush=True)
+
+resp = llm.extract("invoice.pdf", response_schema={...})
+```
+
+Async twins for FastAPI / async scripts: `achat`, `astream`, `aextract`.
+
+Structured-output helpers (also used internally): `json_schema_response_format`, `enforce_strict`, `inline_refs`.
+
+Failures raise `Fintom8Error`.
+
+See [`examples/chat.py`](./examples/chat.py) and [`examples/extract.py`](./examples/extract.py).
+
+## Publish (maintainers)
+
+1. Install dev extras and run tests:
+
+   ```bash
+   cd fintom8
+   pip install -e ".[dev]"
+   pytest
+   python -c "from fintom8 import LLM"
+   ```
+
+2. Build:
+
+   ```bash
+   python -m build
+   ```
+
+3. Upload to TestPyPI first, then PyPI:
+
+   ```bash
+   python -m twine upload --repository testpypi dist/*
+   python -m twine upload dist/*
+   ```
+
+4. Tag for CI Trusted Publishing (OIDC). Create the PyPI project once and add a GitHub environment `pypi` with Trusted Publisher pointing at `.github/workflows/publish-fintom8.yml`. Then:
+
+   ```bash
+   git tag fintom8-v0.1.0
+   git push origin fintom8-v0.1.0
+   ```

fintom8-0.1.0/examples/chat.py

@@ -0,0 +1,7 @@
+"""Minimal chat example. Set LLM_MODEL + matching key in .env or the environment."""
+from fintom8 import LLM
+
+llm = LLM()
+response = llm.chat("Say hello in one short sentence.")
+print(response.text)
+print("usage:", response.usage)

fintom8-0.1.0/examples/extract.py

@@ -0,0 +1,20 @@
+"""Document extract example. Pass a PDF or image path as the first argument."""
+import json
+import sys
+
+from fintom8 import LLM
+
+schema = {
+    "type": "object",
+    "properties": {
+        "title": {"type": "string"},
+        "summary": {"type": "string"},
+    },
+    "required": ["title", "summary"],
+}
+
+if __name__ == "__main__":
+    path = sys.argv[1] if len(sys.argv) > 1 else "invoice.pdf"
+    llm = LLM()
+    response = llm.extract(path, response_schema=schema, schema_name="Doc")
+    print(json.dumps(response.data or {"text": response.text}, indent=2))

fintom8-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fintom8"
+version = "0.1.0"
+description = "LiteLLM connector for Gemini, Vertex AI, OpenAI, and Azure — chat, stream, and document extract."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["llm", "litellm", "gemini", "openai", "azure", "vertex"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "litellm>=1.94.0,<2.0.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "build>=1.2.0",
+    "twine>=5.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/fintom8/f_templates"
+Documentation = "https://github.com/fintom8/f_templates/tree/main/fintom8"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fintom8"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/examples",
+    "/README.md",
+    "/.env.example",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

fintom8-0.1.0/src/fintom8/__init__.py

@@ -0,0 +1,18 @@
+"""fintom8 — LiteLLM connector for Gemini, Vertex AI, OpenAI, and Azure."""
+
+from fintom8.client import LLM
+from fintom8.config import LLMConfig
+from fintom8.exceptions import Fintom8Error
+from fintom8.schema import enforce_strict, inline_refs, json_schema_response_format
+from fintom8.types import ChatResponse
+
+__version__ = "0.1.0"
+__all__ = [
+    "LLM",
+    "LLMConfig",
+    "ChatResponse",
+    "Fintom8Error",
+    "json_schema_response_format",
+    "enforce_strict",
+    "inline_refs",
+]

fintom8-0.1.0/src/fintom8/client.py

@@ -0,0 +1,263 @@
+"""LiteLLM connector — chat, stream, and document extract."""
+from __future__ import annotations
+
+import base64
+import json
+import mimetypes
+from collections.abc import AsyncIterator, Iterator
+from pathlib import Path
+from typing import Any
+
+import litellm
+
+from fintom8.config import LLMConfig, resolve_config
+from fintom8.exceptions import Fintom8Error
+from fintom8.schema import json_schema_response_format
+from fintom8.types import ChatResponse
+
+ALLOWED_MIME = {"application/pdf", "image/png", "image/jpeg", "image/webp", "image/gif"}
+MAX_FILE_BYTES = 20 << 20
+_SUFFIX_MIME = {
+    ".pdf": "application/pdf",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+}
+
+
+class LLM:
+    """Student-facing LiteLLM client. Sync-first; async twins for FastAPI/scripts."""
+
+    def __init__(
+        self,
+        config: LLMConfig | None = None,
+        *,
+        model: str | None = None,
+        temperature: float | None = None,
+        num_retries: int | None = None,
+        api_key: str | None = None,
+        api_base: str | None = None,
+        api_version: str | None = None,
+        vertex_project: str | None = None,
+        vertex_location: str | None = None,
+        load_env: bool = True,
+    ) -> None:
+        self.config = resolve_config(
+            config,
+            model=model,
+            temperature=temperature,
+            num_retries=num_retries,
+            api_key=api_key,
+            api_base=api_base,
+            api_version=api_version,
+            vertex_project=vertex_project,
+            vertex_location=vertex_location,
+            load_env=load_env,
+        )
+        litellm.drop_params = True
+
+    def chat(
+        self,
+        messages: str | list[dict[str, Any]],
+        *,
+        response_schema: dict[str, Any] | None = None,
+        schema_name: str = "Response",
+    ) -> ChatResponse:
+        kw = self._completion_kwargs(_normalize_messages(messages), response_schema, schema_name)
+        try:
+            return _pack(litellm.completion(**kw), self.config.model or "", response_schema is not None)
+        except Fintom8Error:
+            raise
+        except Exception as exc:
+            raise Fintom8Error(str(exc)) from exc
+
+    async def achat(
+        self,
+        messages: str | list[dict[str, Any]],
+        *,
+        response_schema: dict[str, Any] | None = None,
+        schema_name: str = "Response",
+    ) -> ChatResponse:
+        kw = self._completion_kwargs(_normalize_messages(messages), response_schema, schema_name)
+        try:
+            return _pack(await litellm.acompletion(**kw), self.config.model or "", response_schema is not None)
+        except Fintom8Error:
+            raise
+        except Exception as exc:
+            raise Fintom8Error(str(exc)) from exc
+
+    def stream(self, messages: str | list[dict[str, Any]]) -> Iterator[str]:
+        kw = self._completion_kwargs(_normalize_messages(messages), None, "Response")
+        kw["stream"] = True
+        try:
+            stream = litellm.completion(**kw)
+            for chunk in stream:
+                piece = _delta_text(chunk)
+                if piece:
+                    yield piece
+        except Fintom8Error:
+            raise
+        except Exception as exc:
+            raise Fintom8Error(str(exc)) from exc
+
+    async def astream(self, messages: str | list[dict[str, Any]]) -> AsyncIterator[str]:
+        kw = self._completion_kwargs(_normalize_messages(messages), None, "Response")
+        kw["stream"] = True
+        try:
+            stream = await litellm.acompletion(**kw)
+            async for chunk in stream:
+                piece = _delta_text(chunk)
+                if piece:
+                    yield piece
+        except Fintom8Error:
+            raise
+        except Exception as exc:
+            raise Fintom8Error(str(exc)) from exc
+
+    def extract(
+        self,
+        file: str | Path | bytes,
+        *,
+        response_schema: dict[str, Any],
+        instructions: str = "Extract every field from this document.",
+        schema_name: str = "Extraction",
+        mime: str | None = None,
+        filename: str | None = None,
+    ) -> ChatResponse:
+        messages = _extract_messages(file, instructions, mime=mime, filename=filename)
+        return self.chat(messages, response_schema=response_schema, schema_name=schema_name)
+
+    async def aextract(
+        self,
+        file: str | Path | bytes,
+        *,
+        response_schema: dict[str, Any],
+        instructions: str = "Extract every field from this document.",
+        schema_name: str = "Extraction",
+        mime: str | None = None,
+        filename: str | None = None,
+    ) -> ChatResponse:
+        messages = _extract_messages(file, instructions, mime=mime, filename=filename)
+        return await self.achat(messages, response_schema=response_schema, schema_name=schema_name)
+
+    def _completion_kwargs(
+        self,
+        messages: list[dict[str, Any]],
+        response_schema: dict[str, Any] | None,
+        schema_name: str,
+    ) -> dict[str, Any]:
+        cfg = self.config
+        model = cfg.model or ""
+        kw: dict[str, Any] = {
+            "model": model,
+            "messages": messages,
+            "temperature": cfg.temperature,
+            "num_retries": cfg.num_retries,
+        }
+        if cfg.api_key:
+            kw["api_key"] = cfg.api_key
+        if cfg.api_base:
+            kw["api_base"] = cfg.api_base
+        lowered = model.lower()
+        if lowered.startswith("azure/") and cfg.api_version:
+            kw["api_version"] = cfg.api_version
+        if lowered.startswith("vertex_ai/") or lowered.startswith("vertex_ai_beta/"):
+            if cfg.vertex_project:
+                kw["vertex_project"] = cfg.vertex_project
+            if cfg.vertex_location:
+                kw["vertex_location"] = cfg.vertex_location
+        if response_schema is not None:
+            kw["response_format"] = json_schema_response_format(schema_name, response_schema)
+        return kw
+
+
+def _normalize_messages(messages: str | list[dict[str, Any]]) -> list[dict[str, Any]]:
+    if isinstance(messages, str):
+        if not messages.strip():
+            raise Fintom8Error("messages must not be empty.")
+        return [{"role": "user", "content": messages}]
+    if not messages:
+        raise Fintom8Error("messages must not be empty.")
+    return list(messages)
+
+
+def _delta_text(chunk: Any) -> str | None:
+    choices = getattr(chunk, "choices", None) or []
+    if not choices:
+        return None
+    delta = getattr(choices[0], "delta", None)
+    piece = getattr(delta, "content", None) if delta is not None else None
+    return piece or None
+
+
+def _pack(response: Any, model: str, want_json: bool) -> ChatResponse:
+    text = ""
+    try:
+        text = response.choices[0].message.content or ""
+    except (AttributeError, IndexError) as exc:
+        raise Fintom8Error("Unexpected LLM response shape.") from exc
+    usage_obj = getattr(response, "usage", None)
+    data = None
+    if want_json:
+        try:
+            parsed = json.loads(text)
+            data = parsed if isinstance(parsed, dict) else None
+        except json.JSONDecodeError:
+            pass
+    return ChatResponse(
+        text=text,
+        data=data,
+        model=model,
+        usage={
+            "prompt_tokens": getattr(usage_obj, "prompt_tokens", 0) or 0,
+            "completion_tokens": getattr(usage_obj, "completion_tokens", 0) or 0,
+            "total_tokens": getattr(usage_obj, "total_tokens", 0) or 0,
+        },
+    )
+
+
+def _extract_messages(
+    file: str | Path | bytes,
+    instructions: str,
+    *,
+    mime: str | None,
+    filename: str | None,
+) -> list[dict[str, Any]]:
+    raw, inferred_name = _read_file(file)
+    if not raw:
+        raise Fintom8Error("Empty file.")
+    if len(raw) > MAX_FILE_BYTES:
+        raise Fintom8Error("File exceeds 20 MB.")
+    name = filename or inferred_name or "doc"
+    resolved_mime = mime or _guess_mime(name)
+    if resolved_mime is None:
+        raise Fintom8Error("Could not infer MIME type; pass mime= explicitly.")
+    if resolved_mime not in ALLOWED_MIME:
+        raise Fintom8Error(f"Unsupported type {resolved_mime!r}.")
+    url = f"data:{resolved_mime};base64,{base64.b64encode(raw).decode()}"
+    part: dict[str, Any]
+    if resolved_mime.startswith("image/"):
+        part = {"type": "image_url", "image_url": {"url": url}}
+    else:
+        part = {
+            "type": "file",
+            "file": {"file_data": url, "format": resolved_mime, "filename": name},
+        }
+    return [{"role": "user", "content": [{"type": "text", "text": instructions}, part]}]
+
+
+def _read_file(file: str | Path | bytes) -> tuple[bytes, str | None]:
+    if isinstance(file, bytes):
+        return file, None
+    path = Path(file)
+    return path.read_bytes(), path.name
+
+
+def _guess_mime(name: str) -> str | None:
+    suffix = Path(name).suffix.lower()
+    if suffix in _SUFFIX_MIME:
+        return _SUFFIX_MIME[suffix]
+    guessed, _ = mimetypes.guess_type(name)
+    return guessed

fintom8-0.1.0/src/fintom8/config.py

@@ -0,0 +1,122 @@
+"""LLM settings: constructor kwargs / LLMConfig > environment > defaults."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from dotenv import load_dotenv
+
+DEFAULT_MODEL = "gemini/gemini-3.5-flash"
+DEFAULT_TEMPERATURE = 0.0
+DEFAULT_NUM_RETRIES = 3
+DEFAULT_API_VERSION = "2024-10-21"
+DEFAULT_VERTEX_LOCATION = "eu"
+
+
+@dataclass
+class LLMConfig:
+    """Optional fields are `None` until resolved (unset → fall through to env / defaults)."""
+
+    model: str | None = None
+    temperature: float | None = None
+    num_retries: int | None = None
+    api_key: str | None = None
+    api_base: str | None = None
+    api_version: str | None = None
+    vertex_project: str | None = None
+    vertex_location: str | None = None
+
+
+def _env(name: str) -> str | None:
+    value = os.getenv(name)
+    if value is None or value.strip() == "":
+        return None
+    return value
+
+
+def env_api_key_for_model(model: str) -> str | None:
+    lowered = model.lower()
+    if lowered.startswith("gemini/") or lowered.startswith("gemini-"):
+        return _env("GEMINI_API_KEY")
+    if lowered.startswith("azure/"):
+        return _env("AZURE_API_KEY")
+    if lowered.startswith("vertex_ai/") or lowered.startswith("vertex_ai_beta/"):
+        return None
+    return _env("OPENAI_API_KEY")
+
+
+def env_api_base_for_model(model: str) -> str | None:
+    if model.lower().startswith("azure/"):
+        return _env("AZURE_API_BASE")
+    return _env("OPENAI_API_BASE")
+
+
+def resolve_config(
+    config: LLMConfig | None = None,
+    *,
+    model: str | None = None,
+    temperature: float | None = None,
+    num_retries: int | None = None,
+    api_key: str | None = None,
+    api_base: str | None = None,
+    api_version: str | None = None,
+    vertex_project: str | None = None,
+    vertex_location: str | None = None,
+    load_env: bool = True,
+) -> LLMConfig:
+    if load_env:
+        load_dotenv()
+
+    cfg = config or LLMConfig()
+
+    resolved_model = model or cfg.model or _env("LLM_MODEL") or DEFAULT_MODEL
+
+    env_temp = _env("LLM_TEMPERATURE")
+    resolved_temp = (
+        temperature
+        if temperature is not None
+        else cfg.temperature
+        if cfg.temperature is not None
+        else float(env_temp)
+        if env_temp is not None
+        else DEFAULT_TEMPERATURE
+    )
+
+    resolved_retries = (
+        num_retries
+        if num_retries is not None
+        else cfg.num_retries
+        if cfg.num_retries is not None
+        else DEFAULT_NUM_RETRIES
+    )
+
+    resolved_key = api_key if api_key is not None else cfg.api_key
+    if resolved_key is None:
+        resolved_key = env_api_key_for_model(resolved_model)
+
+    resolved_base = api_base if api_base is not None else cfg.api_base
+    if resolved_base is None:
+        resolved_base = env_api_base_for_model(resolved_model)
+
+    resolved_version = api_version if api_version is not None else cfg.api_version
+    if resolved_version is None:
+        resolved_version = _env("AZURE_API_VERSION") or DEFAULT_API_VERSION
+
+    resolved_project = vertex_project if vertex_project is not None else cfg.vertex_project
+    if resolved_project is None:
+        resolved_project = _env("VERTEXAI_PROJECT")
+
+    resolved_location = vertex_location if vertex_location is not None else cfg.vertex_location
+    if resolved_location is None:
+        resolved_location = _env("VERTEXAI_LOCATION") or DEFAULT_VERTEX_LOCATION
+
+    return LLMConfig(
+        model=resolved_model,
+        temperature=resolved_temp,
+        num_retries=resolved_retries,
+        api_key=resolved_key,
+        api_base=resolved_base,
+        api_version=resolved_version,
+        vertex_project=resolved_project,
+        vertex_location=resolved_location,
+    )

fintom8-0.1.0/src/fintom8/exceptions.py

@@ -0,0 +1,5 @@
+"""Public errors for the fintom8 LLM connector."""
+
+
+class Fintom8Error(Exception):
+    """Raised when configuration is invalid or an LLM call fails."""

fintom8-0.1.0/src/fintom8/schema.py

@@ -0,0 +1,75 @@
+"""JSON Schema → OpenAI response_format (Gemini/Vertex/OpenAI/Azure via LiteLLM).
+
+enforce_strict: all props required + additionalProperties false; optionals → nullable.
+inline_refs: flatten $ref/$defs (Gemini rejects them).
+"""
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+_C = ("anyOf", "oneOf", "allOf")
+
+
+def json_schema_response_format(name: str, schema: dict[str, Any], *, strict: bool = True) -> dict[str, Any]:
+    s = enforce_strict(schema) if strict else copy.deepcopy(schema)
+    return {"type": "json_schema", "json_schema": {"name": name, "strict": strict, "schema": s}}
+
+
+def inline_refs(schema: dict[str, Any]) -> dict[str, Any]:
+    defs = {**(schema.get("$defs") or {}), **(schema.get("definitions") or {})}
+
+    def go(n: Any, seen: frozenset[str]) -> Any:
+        if isinstance(n, list):
+            return [go(i, seen) for i in n]
+        if not isinstance(n, dict):
+            return n
+        if "$ref" in n:
+            k = n["$ref"].rsplit("/", 1)[-1]
+            if k not in defs:
+                raise ValueError(f"Cannot resolve $ref {n['$ref']!r}")
+            if k in seen:
+                raise ValueError(f"Recursive $ref {n['$ref']!r}")
+            return {**go(defs[k], seen | {k}), **{a: go(b, seen) for a, b in n.items() if a != "$ref"}}
+        return {a: go(b, seen) for a, b in n.items() if a not in ("$defs", "definitions")}
+
+    return go(schema, frozenset())
+
+
+def enforce_strict(schema: dict[str, Any]) -> dict[str, Any]:
+    def go(n: Any) -> Any:
+        if isinstance(n, list):
+            return [go(i) for i in n]
+        if not isinstance(n, dict):
+            return n
+        out = {k: go(v) for k, v in n.items()}
+        for c in _C:
+            if c in out:
+                out[c] = [go(i) for i in out[c]]
+        props = out.get("properties") or {}
+        obj = out.get("type") == "object" or (
+            isinstance(out.get("type"), list) and "object" in out["type"]
+        ) or ("properties" in out and "type" not in out)
+        if props and obj:
+            req = set(out.get("required") or [])
+            out["properties"] = {k: (v if k in req else _null(v)) for k, v in props.items()}
+            out["required"], out["additionalProperties"] = list(props), False
+        return out
+
+    return go(inline_refs(schema))
+
+
+def _null(s: Any) -> Any:
+    if not isinstance(s, dict):
+        return s
+    n, t = dict(s), s.get("type")
+    if isinstance(t, str) and t != "null":
+        return {**n, "type": [t, "null"]}
+    if isinstance(t, list) and "null" not in t:
+        return {**n, "type": [*t, "null"]}
+    for c in _C:
+        if isinstance(n.get(c), list):
+            if not any(isinstance(m, dict) and m.get("type") == "null" for m in n[c]):
+                n[c] = [*n[c], {"type": "null"}]
+            return n
+    return {"anyOf": [n, {"type": "null"}]}

fintom8-0.1.0/src/fintom8/types.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ChatResponse:
+    text: str
+    data: dict[str, Any] | None
+    model: str
+    usage: dict[str, int] = field(default_factory=dict)

fintom8-0.1.0/tests/test_client.py

@@ -0,0 +1,213 @@
+from types import SimpleNamespace
+
+import pytest
+
+from fintom8 import Fintom8Error, LLM
+from fintom8.client import _pack
+
+
+def _response(text: str, prompt=1, completion=2, total=3):
+    return SimpleNamespace(
+        choices=[SimpleNamespace(message=SimpleNamespace(content=text))],
+        usage=SimpleNamespace(prompt_tokens=prompt, completion_tokens=completion, total_tokens=total),
+    )
+
+
+def _chunk(text: str):
+    return SimpleNamespace(choices=[SimpleNamespace(delta=SimpleNamespace(content=text))])
+
+
+def test_chat_string_and_pack(monkeypatch):
+    captured = {}
+
+    def fake_completion(**kwargs):
+        captured.update(kwargs)
+        return _response("hello")
+
+    monkeypatch.setattr("fintom8.client.litellm.completion", fake_completion)
+    llm = LLM(model="gpt-4o", api_key="sk-test", temperature=0.2, load_env=False)
+    resp = llm.chat("Hi there")
+    assert resp.text == "hello"
+    assert resp.model == "gpt-4o"
+    assert resp.usage["total_tokens"] == 3
+    assert captured["messages"] == [{"role": "user", "content": "Hi there"}]
+    assert captured["api_key"] == "sk-test"
+    assert captured["temperature"] == 0.2
+    assert "response_format" not in captured
+
+
+def test_chat_with_schema_parses_json(monkeypatch):
+    def fake_completion(**kwargs):
+        assert "response_format" in kwargs
+        assert kwargs["response_format"]["type"] == "json_schema"
+        return _response('{"total": 12.5}')
+
+    monkeypatch.setattr("fintom8.client.litellm.completion", fake_completion)
+    llm = LLM(model="gpt-4o", api_key="sk-test", load_env=False)
+    resp = llm.chat(
+        [{"role": "user", "content": "extract"}],
+        response_schema={
+            "type": "object",
+            "properties": {"total": {"type": "number"}},
+            "required": ["total"],
+        },
+        schema_name="Invoice",
+    )
+    assert resp.data == {"total": 12.5}
+
+
+def test_chat_wraps_errors(monkeypatch):
+    def fake_completion(**kwargs):
+        raise RuntimeError("provider down")
+
+    monkeypatch.setattr("fintom8.client.litellm.completion", fake_completion)
+    llm = LLM(model="gpt-4o", api_key="sk-test", load_env=False)
+    with pytest.raises(Fintom8Error, match="provider down"):
+        llm.chat("hi")
+
+
+def test_stream_yields_text(monkeypatch):
+    def fake_completion(**kwargs):
+        assert kwargs["stream"] is True
+        return iter([_chunk("Hel"), _chunk("lo"), _chunk("")])
+
+    monkeypatch.setattr("fintom8.client.litellm.completion", fake_completion)
+    llm = LLM(model="gpt-4o", api_key="sk-test", load_env=False)
+    assert "".join(llm.stream("x")) == "Hello"
+
+
+@pytest.mark.asyncio
+async def test_achat_and_astream(monkeypatch):
+    async def fake_acompletion(**kwargs):
+        if kwargs.get("stream"):
+            async def gen():
+                yield _chunk("A")
+                yield _chunk("B")
+
+            return gen()
+        return _response("ok")
+
+    monkeypatch.setattr("fintom8.client.litellm.acompletion", fake_acompletion)
+    llm = LLM(model="gpt-4o", api_key="sk-test", load_env=False)
+    assert (await llm.achat("q")).text == "ok"
+    chunks = []
+    async for piece in llm.astream("q"):
+        chunks.append(piece)
+    assert chunks == ["A", "B"]
+
+
+def test_extract_pdf_message_shape(monkeypatch, tmp_path):
+    pdf = tmp_path / "invoice.pdf"
+    pdf.write_bytes(b"%PDF-1.4 fake")
+    captured = {}
+
+    def fake_completion(**kwargs):
+        captured.update(kwargs)
+        return _response('{"title": "Inv"}')
+
+    monkeypatch.setattr("fintom8.client.litellm.completion", fake_completion)
+    llm = LLM(model="gpt-4o", api_key="sk-test", load_env=False)
+    resp = llm.extract(
+        pdf,
+        response_schema={"type": "object", "properties": {"title": {"type": "string"}}, "required": ["title"]},
+    )
+    assert resp.data == {"title": "Inv"}
+    content = captured["messages"][0]["content"]
+    assert content[0]["type"] == "text"
+    assert content[1]["type"] == "file"
+    assert content[1]["file"]["format"] == "application/pdf"
+    assert content[1]["file"]["filename"] == "invoice.pdf"
+    assert "response_format" in captured
+
+
+def test_extract_image_uses_image_url(monkeypatch):
+    captured = {}
+
+    def fake_completion(**kwargs):
+        captured.update(kwargs)
+        return _response("{}")
+
+    monkeypatch.setattr("fintom8.client.litellm.completion", fake_completion)
+    llm = LLM(model="gpt-4o", api_key="sk-test", load_env=False)
+    llm.extract(
+        b"\x89PNG",
+        mime="image/png",
+        filename="shot.png",
+        response_schema={"type": "object", "properties": {}},
+    )
+    part = captured["messages"][0]["content"][1]
+    assert part["type"] == "image_url"
+    assert part["image_url"]["url"].startswith("data:image/png;base64,")
+
+
+def test_extract_rejects_empty_and_bad_mime():
+    llm = LLM(model="gpt-4o", api_key="sk-test", load_env=False)
+    schema = {"type": "object", "properties": {}}
+    with pytest.raises(Fintom8Error, match="Empty file"):
+        llm.extract(b"", mime="application/pdf", response_schema=schema)
+    with pytest.raises(Fintom8Error, match="Unsupported"):
+        llm.extract(b"xx", mime="text/plain", response_schema=schema)
+    with pytest.raises(Fintom8Error, match="infer MIME"):
+        llm.extract(b"xx", response_schema=schema)
+
+
+def test_vertex_kwargs_passed(monkeypatch):
+    captured = {}
+
+    def fake_completion(**kwargs):
+        captured.update(kwargs)
+        return _response("v")
+
+    monkeypatch.setattr("fintom8.client.litellm.completion", fake_completion)
+    llm = LLM(
+        model="vertex_ai/gemini-3.5-flash",
+        vertex_project="my-proj",
+        vertex_location="us-central1",
+        load_env=False,
+    )
+    llm.chat("hi")
+    assert captured["vertex_project"] == "my-proj"
+    assert captured["vertex_location"] == "us-central1"
+    assert "api_key" not in captured
+
+
+def test_azure_kwargs_passed(monkeypatch):
+    captured = {}
+
+    def fake_completion(**kwargs):
+        captured.update(kwargs)
+        return _response("a")
+
+    monkeypatch.setattr("fintom8.client.litellm.completion", fake_completion)
+    llm = LLM(
+        model="azure/my-deploy",
+        api_key="az",
+        api_base="https://res.openai.azure.com",
+        api_version="2024-10-21",
+        load_env=False,
+    )
+    llm.chat("hi")
+    assert captured["api_key"] == "az"
+    assert captured["api_base"] == "https://res.openai.azure.com"
+    assert captured["api_version"] == "2024-10-21"
+
+
+def test_pack_handles_invalid_json():
+    resp = _pack(_response("not-json"), "gpt-4o", True)
+    assert resp.data is None
+    assert resp.text == "not-json"
+
+
+def test_empty_messages_raise():
+    llm = LLM(model="gpt-4o", api_key="sk-test", load_env=False)
+    with pytest.raises(Fintom8Error, match="empty"):
+        llm.chat("   ")
+    with pytest.raises(Fintom8Error, match="empty"):
+        llm.chat([])
+
+
+def test_drop_params_enabled():
+    import litellm
+
+    LLM(model="gpt-4o", api_key="sk-test", load_env=False)
+    assert litellm.drop_params is True

fintom8-0.1.0/tests/test_config.py

@@ -0,0 +1,64 @@
+from fintom8.config import LLMConfig, resolve_config
+
+
+def test_defaults_when_env_empty(monkeypatch):
+    monkeypatch.delenv("LLM_MODEL", raising=False)
+    monkeypatch.delenv("LLM_TEMPERATURE", raising=False)
+    monkeypatch.delenv("GEMINI_API_KEY", raising=False)
+    cfg = resolve_config(load_env=False)
+    assert cfg.model == "gemini/gemini-3.5-flash"
+    assert cfg.temperature == 0.0
+    assert cfg.num_retries == 3
+    assert cfg.api_key is None
+    assert cfg.vertex_location == "eu"
+    assert cfg.api_version == "2024-10-21"
+
+
+def test_env_overrides_defaults(monkeypatch):
+    monkeypatch.setenv("LLM_MODEL", "gpt-4o")
+    monkeypatch.setenv("LLM_TEMPERATURE", "0.4")
+    monkeypatch.setenv("OPENAI_API_KEY", "sk-env")
+    monkeypatch.setenv("OPENAI_API_BASE", "https://example.test/v1")
+    cfg = resolve_config(load_env=False)
+    assert cfg.model == "gpt-4o"
+    assert cfg.temperature == 0.4
+    assert cfg.api_key == "sk-env"
+    assert cfg.api_base == "https://example.test/v1"
+
+
+def test_kwargs_override_env_and_config(monkeypatch):
+    monkeypatch.setenv("LLM_MODEL", "gpt-4o")
+    monkeypatch.setenv("OPENAI_API_KEY", "sk-env")
+    cfg = resolve_config(
+        LLMConfig(model="azure/deploy", api_key="sk-cfg"),
+        model="gemini/gemini-3.5-flash",
+        api_key="sk-kw",
+        load_env=False,
+    )
+    assert cfg.model == "gemini/gemini-3.5-flash"
+    assert cfg.api_key == "sk-kw"
+
+
+def test_config_overrides_env(monkeypatch):
+    monkeypatch.setenv("LLM_MODEL", "gpt-4o")
+    monkeypatch.setenv("LLM_TEMPERATURE", "0.9")
+    cfg = resolve_config(LLMConfig(model="azure/x", temperature=0.1), load_env=False)
+    assert cfg.model == "azure/x"
+    assert cfg.temperature == 0.1
+
+
+def test_model_prefix_selects_provider_key(monkeypatch):
+    monkeypatch.setenv("GEMINI_API_KEY", "g-key")
+    monkeypatch.setenv("OPENAI_API_KEY", "o-key")
+    monkeypatch.setenv("AZURE_API_KEY", "a-key")
+    monkeypatch.setenv("AZURE_API_BASE", "https://res.openai.azure.com")
+    gemini = resolve_config(model="gemini/gemini-3.5-flash", load_env=False)
+    openai = resolve_config(model="gpt-4o", load_env=False)
+    azure = resolve_config(model="azure/my-deploy", load_env=False)
+    vertex = resolve_config(model="vertex_ai/gemini-3.5-flash", vertex_project="proj", load_env=False)
+    assert gemini.api_key == "g-key"
+    assert openai.api_key == "o-key"
+    assert azure.api_key == "a-key"
+    assert azure.api_base == "https://res.openai.azure.com"
+    assert vertex.api_key is None
+    assert vertex.vertex_project == "proj"

fintom8-0.1.0/tests/test_schema.py

@@ -0,0 +1,48 @@
+from fintom8.schema import enforce_strict, inline_refs, json_schema_response_format
+
+
+def test_inline_refs_flattens_defs():
+    schema = {
+        "type": "object",
+        "properties": {"item": {"$ref": "#/$defs/Item"}},
+        "$defs": {
+            "Item": {
+                "type": "object",
+                "properties": {"name": {"type": "string"}},
+                "required": ["name"],
+            }
+        },
+    }
+    out = inline_refs(schema)
+    assert "$defs" not in out
+    assert "$ref" not in out["properties"]["item"]
+    assert out["properties"]["item"]["properties"]["name"]["type"] == "string"
+
+
+def test_enforce_strict_requires_all_props_and_nulls_optionals():
+    schema = {
+        "type": "object",
+        "properties": {
+            "total": {"type": "number"},
+            "note": {"type": "string"},
+        },
+        "required": ["total"],
+    }
+    out = enforce_strict(schema)
+    assert out["required"] == ["total", "note"]
+    assert out["additionalProperties"] is False
+    assert out["properties"]["total"]["type"] == "number"
+    assert out["properties"]["note"]["type"] == ["string", "null"]
+
+
+def test_json_schema_response_format_wraps_strict_schema():
+    schema = {
+        "type": "object",
+        "properties": {"ok": {"type": "boolean"}},
+        "required": ["ok"],
+    }
+    fmt = json_schema_response_format("Flag", schema)
+    assert fmt["type"] == "json_schema"
+    assert fmt["json_schema"]["name"] == "Flag"
+    assert fmt["json_schema"]["strict"] is True
+    assert fmt["json_schema"]["schema"]["additionalProperties"] is False