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.

Install from Git (recommended for private use)

GitHub Packages Python upload is currently unreliable (SSL issues). Install directly from this repo instead:

# HTTPS (use a PAT with repo read access if the repo is private)
pip install "git+https://github.com/NikolaienkoIgor/f8_templates.git#subdirectory=fintom8"

# Pin a tag / commit
pip install "git+https://github.com/NikolaienkoIgor/f8_templates.git@fintom8-v0.1.4#subdirectory=fintom8"

# SSH (no token in the URL if your SSH key is set up)
pip install "git+ssh://git@github.com/NikolaienkoIgor/f8_templates.git#subdirectory=fintom8"

Private HTTPS with an explicit token:

pip install "git+https://<GITHUB_USERNAME>:<GITHUB_PAT>@github.com/NikolaienkoIgor/f8_templates.git#subdirectory=fintom8"

Other install options

# Public PyPI (when published)
pip install fintom8

# Local editable install from this checkout
pip install -e ./fintom8
# or: pip install -e "./fintom8[dev]"

from fintom8 import LLM

llm = LLM()  # reads .env / environment
print(llm.chat("Summarize this invoice").text)

Configuration

Resolution order: constructor kwargs / LLMConfig > environment > defaults.

Copy .env.example to .env in your project (never commit it).

For azure/<deployment>, missing api_key, api_base, or api_version raises Fintom8Error (set via constructor or AZURE_* env vars).

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

Contributors

• Igor Nikolaienko
• Harsh Bansal

Usage

from fintom8 import LLM

llm = LLM()

resp = llm.chat("Hello")
print(resp.text, resp.usage)

# Structured output — file only; detect format → LiteLLM SO → cleanse dates
invoice_rf = {
    "type": "json_schema",
    "json_schema": {
        "name": "Invoice",
        "strict": True,
        "schema": {
            "type": "object",
            "properties": {
                "total": {"type": "number"},
                "vendor": {"type": "string"},
                "invoiceDate": {"type": ["date", "null"]},
            },
            "required": ["total", "vendor", "invoiceDate"],
            "additionalProperties": False,
        },
    },
}
data = llm.structured(
    "invoice.pdf",  # also: .png/.jpg, .txt/.csv/.xml/.xlsx, or bytes
    structuredOutput=invoice_rf,
    dateFormat="DD.MM.YYYY",
)
# {"total": 42.5, "vendor": "Acme", "invoiceDate": "08.08.2026"}

# process() is an alias of structured()
data = llm.process(
    "invoice.pdf",
    structuredOutput=invoice_rf,
    dateFormat="DD.MM.YYYY",
    instructions="Extract invoice vendor and total.",
)

for chunk in llm.stream([{"role": "user", "content": "Write a haiku"}]):
    print(chunk, end="", flush=True)

resp = llm.extract("invoice.pdf", response_format=invoice_rf)

Async twins: achat, astream, aextract, astructured, aprocess.

Optional helpers: detect_format, fields_to_schema, compile_fields, prepare_response_format, apply_cleanse, json_schema_response_format, structured_output, enforce_strict, inline_refs.

Bundled templates

from fintom8.templates import invoice
# or: from fintom8 import templates; templates.invoice
# or: from fintom8 import use_template; use_template("invoice")

data = llm.structured(
    "invoice.pdf",
    structuredOutput=invoice["structuredOutput"],
    systemPrompt=invoice["systemPrompt"],
    dateFormat=invoice.get("dateFormat", "YYYY-MM-DD"),
)

list_templates() lists packaged names (invoice, chemical_composition, recipient_statement). Pass a path or dict to use_template for custom templates.

Invoice validation

After structured invoice extraction, run the same math checks used by the extractor backend (line formulas, gross/net consistency, invoice balance; tolerance 0.03):

from fintom8 import invoice_validation

# dict → dict (endpoint-shaped; always includes _debug; full error text on failure)
response = invoice_validation(data)

Also exported: Invoice, LineItem, validation_payload_from_llm. Does not run the validate/correct retry loop or financial normalizers.

Failures raise Fintom8Error.

If you see an authentication error (for example missing GEMINI_API_KEY, OPENAI_API_KEY, or Vertex setup), that means package import and retries are working; configure credentials for the selected LLM_MODEL.

See examples/chat.py and examples/extract.py.

Publish (maintainers)

1. Install dev extras and run tests:

   cd fintom8
   pip install -e ".[dev]"
   pytest
   python -c "from fintom8 import LLM"
   

2. Build:

   python -m build
   

3. Upload to TestPyPI first, then PyPI:

   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:

   git tag fintom8-v0.1.4
   git push origin fintom8-v0.1.4