openfatture

OpenFatture v2.0.0

Release date: 7 August 2026
Status: Stable (architecture modernization)

Major packaging and architecture release. The public CLI surface is unchanged; import paths, optional extras, and honesty gates for experimental features are the breaking surface for integrators and contributors.

Highlights

Modular package layout: billing, events, hooks, platform, pdf replace the old core / utils / services grab-bags.
Optional feature extras: core install is invoicing + SDI + payment; AI, RAG, ML, and Lightning install via PEP 621 extras.
Unified assistant runtime: all CLI/interactive traffic goes through openfatture.ai.runtime.AssistantRuntime.
D2 tool layering: AI tools are thin adapters over application services (no raw SQLAlchemy in ai/tools).
Honesty gates: Lightning never silent-mocks; RAG reindex queue requires a real callback; missing extras raise MissingExtraError.
Ruff-only lint/format; no in-code noqa / type: ignore suppressions.

Breaking changes

Import paths

Removed / old	Use instead
`openfatture.core.*`	`openfatture.billing.`, `openfatture.events.`, `openfatture.hooks.*`
`openfatture.utils.*`	`openfatture.platform.*`
`openfatture.services.pdf.*`	`openfatture.pdf.*`
`openfatture.ai.voice.*`	removed
`openfatture.web_scraper.*`	removed
In-process `plugins` package	removed; use hooks under `~/.openfatture/hooks`

There are no compatibility shims. Update imports or pin to 1.3.x.

Install / extras

# Core (billing, SDI, payment, PDF, CLI)
uv sync

# Optional stacks
uv sync --extra ai
uv sync --extra rag      # includes AI
uv sync --extra ml
uv sync --extra lightning
uv sync --extra all

openfatture assistant / interactive require the ai extra.

Lightning

Default: lightning_allow_mock=false.
Without real LND stubs, invoice/node operations raise LNDClientError.
Mock responses only when lightning_allow_mock=true (local/dev only).
Full LND protobuf gRPC is still experimental / not production-ready.

RAG auto-update

ReindexQueue requires a reindex_callback (wired by AutoIndexingService).
No silent sleep-based simulation of reindex work.

Public CLI (unchanged)

openfatture init
openfatture assistant [MESSAGE] [--session ID] [--stream/--no-stream] [--json]
openfatture interactive start
openfatture config ...
openfatture status [--json]

Domain workflows stay on the assistant and application tools.

Assistant runtime

Path	Role
`AssistantRuntime` → `ChatAgent` tool loop	Product path (CLI / interactive)
`ai.runtime.graph.build_tool_loop_graph`	Multi-node LangGraph helper (tests / optional)
`ai.orchestration.workflows.*`	Internal / experimental multi-agent graphs

Interactive sessions persist to the file session store and print a session ID. Resume with openfatture assistant --session <id> or continue in interactive mode (history comes from the store when persistence is enabled).

Migration from 1.3.x

Update any third-party or local scripts that import core / utils / services.pdf.
Install feature extras if you use AI, RAG, ML, or Lightning.
Review lightning_allow_mock (defaults to off).
Re-run openfatture init / config if paths or settings keys changed in your environment (see CONFIGURATION.md).
Run the deterministic test gate after upgrading.

Quality gate for this release

ruff check / ruff format --check
mypy openfatture/
Default pytest suite (excludes performance / e2e / ollama markers)
Honesty tests for Lightning mock, RAG queue, and extras