Metadata-Version: 2.5
Name: openfatture
Version: 2.4.2
Summary: Open-source electronic invoicing for Italian freelancers - CLI-first with AI workflows
Project-URL: Homepage, https://github.com/gianlucamazza/openfatture
Project-URL: Repository, https://github.com/gianlucamazza/openfatture
Project-URL: Issues, https://github.com/gianlucamazza/openfatture/issues
Author-email: Gianluca Mazza <info@gianlucamazza.it>
License: MIT
License-File: LICENSE
Keywords: ai,cli,fattura-elettronica,fatturapa,freelance,invoicing,sdi
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Accounting
Requires-Python: >=3.12
Requires-Dist: alembic>=1.13.1
Requires-Dist: asn1crypto>=1.5.1
Requires-Dist: babel>=2.14.0
Requires-Dist: click>=8.1.7
Requires-Dist: cryptography>=50.0.0
Requires-Dist: fluent-runtime>=0.4.0
Requires-Dist: httpx>=0.26.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: lxml>=5.1.0
Requires-Dist: ofxparse>=0.21
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: pyasn1-modules>=0.3.0
Requires-Dist: pyasn1>=0.5.0
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: questionary>=2.0.0
Requires-Dist: rapidfuzz>=3.0.0
Requires-Dist: reportlab>=4.0.9
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.7.0
Requires-Dist: sqlalchemy>=2.0.25
Requires-Dist: structlog>=24.1.0
Requires-Dist: tomlkit>=0.13.0
Requires-Dist: typer>=0.12.0
Requires-Dist: urllib3>=2.8.0
Requires-Dist: xmlschema>=3.0.1
Provides-Extra: ai
Requires-Dist: anthropic>=0.71.0; extra == 'ai'
Requires-Dist: langgraph-sdk>=0.4.6; extra == 'ai'
Requires-Dist: langgraph>=1.2.14; extra == 'ai'
Requires-Dist: openai>=2.4.0; extra == 'ai'
Requires-Dist: tiktoken>=0.8.0; extra == 'ai'
Provides-Extra: all
Requires-Dist: anthropic>=0.71.0; extra == 'all'
Requires-Dist: apscheduler>=3.10.4; extra == 'all'
Requires-Dist: chromadb>=1.1.1; extra == 'all'
Requires-Dist: langgraph-sdk>=0.4.6; extra == 'all'
Requires-Dist: langgraph>=1.2.14; extra == 'all'
Requires-Dist: numpy>=1.26.0; extra == 'all'
Requires-Dist: openai>=2.4.0; extra == 'all'
Requires-Dist: pandas>=2.3.3; extra == 'all'
Requires-Dist: plotly>=6.3.1; extra == 'all'
Requires-Dist: prophet>=1.1.5; extra == 'all'
Requires-Dist: sentence-transformers>=2.6.0; extra == 'all'
Requires-Dist: tiktoken>=0.8.0; extra == 'all'
Requires-Dist: transformers>=5.5.0; extra == 'all'
Requires-Dist: xgboost>=2.1.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: bump-my-version>=0.18.0; extra == 'dev'
Requires-Dist: hypothesis>=6.98.0; extra == 'dev'
Requires-Dist: lxml-stubs>=0.5.1; extra == 'dev'
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pandas-stubs>=2.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
Requires-Dist: pypdf>=6.21.4; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.3; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff<0.18,>=0.14.0; extra == 'dev'
Requires-Dist: types-pyasn1>=0.5.0; extra == 'dev'
Requires-Dist: types-python-dateutil>=2.9.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
Requires-Dist: types-reportlab>=4.0.0; extra == 'dev'
Requires-Dist: types-requests>=2.31.0; extra == 'dev'
Provides-Extra: ml
Requires-Dist: apscheduler>=3.10.4; extra == 'ml'
Requires-Dist: numpy>=1.26.0; extra == 'ml'
Requires-Dist: pandas>=2.3.3; extra == 'ml'
Requires-Dist: plotly>=6.3.1; extra == 'ml'
Requires-Dist: prophet>=1.1.5; extra == 'ml'
Requires-Dist: xgboost>=2.1.0; extra == 'ml'
Provides-Extra: rag
Requires-Dist: anthropic>=0.71.0; extra == 'rag'
Requires-Dist: chromadb>=1.1.1; extra == 'rag'
Requires-Dist: langgraph-sdk>=0.4.6; extra == 'rag'
Requires-Dist: langgraph>=1.2.14; extra == 'rag'
Requires-Dist: openai>=2.4.0; extra == 'rag'
Requires-Dist: sentence-transformers>=2.6.0; extra == 'rag'
Requires-Dist: tiktoken>=0.8.0; extra == 'rag'
Requires-Dist: transformers>=5.5.0; extra == 'rag'
Description-Content-Type: text/markdown

# OpenFatture

**Open-source electronic invoicing for Italy.**

A local-first, CLI-first invoicing workspace for Italian freelancers and small
businesses. Generate FatturaPA invoices, manage financial workflows, and automate
repetitive tasks with optional AI assistance. Your data remains under your control.

[![Tests](https://github.com/gianlucamazza/openfatture/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/gianlucamazza/openfatture/actions/workflows/test.yml)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](pyproject.toml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

[Quick start](#quick-start) · [Capabilities](#what-you-can-do) ·
[Feature status](#feature-status) · [Documentation](#documentation) ·
[Issues](https://github.com/gianlucamazza/openfatture/issues)

## Why OpenFatture?

Italian electronic invoicing involves more than producing a PDF: structured XML,
customer records, delivery notifications, and payment tracking must fit together.
OpenFatture brings these workflows into a terminal workspace you can inspect and
extend.

- **Work locally.** Keep the default SQLite database and generated documents on
  your machine. Invoice calculations, XML generation, and PDF rendering do not
  require an LLM or a cloud account.
- **Choose how to work.** Use deterministic client and invoice commands, or add an
  assistant that calls application services through registered tools.
- **Automate around your workflow.** Reuse domain services, CSV and bank imports,
  domain events, and user hook scripts.

Built for freelancers and small studios comfortable in a terminal. This repository
has **no browser frontend or web application surface**; it is distinct from
OpenFatture Cloud.

## Quick Start

Requires **Python 3.12+**, Git, and [uv](https://docs.astral.sh/uv/).
Start with the core install; AI, retrieval, and forecasting are separate extras.

```bash
git clone https://github.com/gianlucamazza/openfatture.git
cd openfatture
uv sync --frozen
uv run openfatture init
uv run openfatture status
```

The setup wizard creates local storage and collects company settings. Use your
actual fiscal details and tax regime; AI configuration can be skipped.
`status --json` reports local readiness and next steps, without contacting providers
or verifying SDI delivery.

### Create a draft and preview it without AI

Run this example in a fresh demo database. On an existing database, replace `1`
with the client and invoice IDs printed by the create commands. The sample client
uses a demo VAT number and is for a draft preview only.

```bash
uv run openfatture cliente create --name "Demo Client" --piva 12345678903
uv run openfatture fattura create --client 1 --note "Demo draft"
uv run openfatture fattura add-line --invoice 1 \
  --desc "Software consulting" --qty 3 --price 90 --iva 22
uv run openfatture fattura show 1
uv run openfatture fattura generate-pdf 1 --output demo-invoice.pdf
```

This creates a draft for €270 plus €59.40 VAT and a human-readable PDF; it does
not transmit an invoice. The VAT rate is illustrative. Complete and verify both
issuer and customer fiscal details before preparing a real invoice.

Explore the current command surface with `uv run openfatture --help` and
`uv run openfatture fattura --help`.

## What You Can Do

| Domain | Examples | Entry point |
| --- | --- | --- |
| Clients and invoices | Create clients, add invoice lines, inspect totals and draft status | `cliente`, `fattura` commands; application services |
| Documents | Generate FatturaPA XML, render PDF templates, create linked TD04 credit notes | `fattura generate-xml`, `generate-pdf`, `create-credit-note` |
| Delivery | Send XML through a configured PEC account and process SDI notification files | SDI services; opt-in assistant tools |
| Payments | Import bank statements and reconcile transactions with payments | Payment services; assistant tools |
| Business workflows | Quotes, product records, CSV import/export, batch updates, and reports | Application services; assistant tools |
| Automation | React to domain events with scripts and inspect persisted event records | Events and hooks; [hook examples](examples/hooks/) |

Core capabilities live in application/domain packages. The CLI exposes a subset;
other workflows use services or optional assistant tools, rather than a command
for every operation.

**XML generation and validation are separate concerns.** The current
`fattura generate-xml` command calls generation with validation disabled.
The service layer and `validate_invoice_xml` assistant tool provide validation;
a generated file alone is not evidence of XSD validity or SDI acceptance.
See [XSD validation](docs/XSD_VALIDATION.md).

## AI-Assisted Workflows

Install only the assistant stack when you need natural-language access:

```bash
uv sync --frozen --extra ai
```

Configure `AI_PROVIDER`, `AI_MODEL`, and the provider credential or local endpoint
using the [configuration guide](docs/CONFIGURATION.md). Supported provider
adapters are OpenAI, Anthropic, and Ollama. Ollama requires a running local service
and an installed model; the extra does not install either.

Once configured, start with read-only requests:

```bash
uv run openfatture status --json
uv run openfatture assistant "List my clients"
uv run openfatture assistant "Show invoice 1 and its line items"
uv run openfatture interactive start
```

The assistant interprets the request; registered tools call application services
for business operations. Model responses are not proof that an operation ran:
inspect tool outcomes and the resulting records or files. Review fiscal inputs
and results yourself.

Tool access is controlled by `AI_ENABLED_TOOLS`, which defaults to read-only
invoice/client lookups. Creation, reconciliation, and export requests need their
respective tools enabled. `AI_ENABLED_TOOLS=all` enables non-transmit tools;
**it does not enable SDI/PEC send**. Sending requires explicit opt-in for
`send_invoice_to_sdi`.

`AI_TOOLS_REQUIRE_CONFIRMATION=true` is the default. Tools marked as requiring
confirmation need human approval: a terminal can prompt, while noninteractive
callers without approval are refused. The model cannot approve itself. Turning
this setting off skips confirmation but still requires transmit-tool opt-in.
See [AI architecture](docs/AI_ARCHITECTURE.md) for runtime details.

## Architecture

```mermaid
flowchart TD
    CLI["Deterministic CLI"] --> APP["Application services"]
    TERM["Terminal assistant (optional)"] --> AI["AI runtime and allowed tools"]
    AI --> APP
    AI <--> LLM["Local or cloud LLM provider"]
    APP --> DOMAIN["Billing, SDI, payments, PDF"]
    DOMAIN --> STORE["Database and document files"]
    DOMAIN --> EVENTS["Domain events"]
    EVENTS --> AUDIT["Event persistence and hooks"]
    DOMAIN --> PEC["Configured PEC transport"]
```

The CLI and AI tools route business operations through application services.
Core storage, billing, payment, SDI, and PDF modules
remain usable without optional model dependencies.
See [architecture](docs/ARCHITECTURE.md) and
[core, extras, and extensions](docs/CORE_VS_EXTENSIONS.md).

## Data Ownership & Security

- **Persistence:** SQLite is the default; `DATABASE_URL`, `DATA_DIR`, and
  `ARCHIVIO_DIR` control storage. `init` writes a user profile; `status` shows
  configured paths. Persistent assistant sessions are also local files.
- **External data flow:** local-first does not mean every feature is offline.
  Cloud LLM requests can include prompts and tool results; PEC transmits invoice
  data. Choose providers and enabled tools accordingly.
- **Audit boundaries:** emitted domain events can be persisted to the database.
  This is an operational audit trail, not a tamper-proof archive or a guarantee
  that every action is durably recorded; persistence failures are logged without
  aborting the business operation.
- **Credentials and extensions:** protect local profiles, secrets, and signing
  material; never commit them. Diagnostic masking is not encryption at rest.
  Hook scripts execute local code and should be trusted before enabling them.
- **Retention:** back up the database and documents. A local document archive
  does not by itself establish compliant long-term preservation
  (*conservazione a norma*).

See the [configuration guide](docs/CONFIGURATION.md) and
[security policy](SECURITY.md) for settings and vulnerability reporting.

## Feature Status

The package identifies itself as **2.4.0**, with Beta metadata. These labels
describe implementation and dependencies, not certification or service guarantees.

| Capability | Status | Boundary |
| --- | --- | --- |
| Client and invoice CLI, PDF, FatturaPA XML, TD04 | Available in core | XML CLI generation does not run validation; fiscal inputs still need review |
| Bank import, reconciliation, quotes, batch, reports | Available in core services | Not all operations have direct CLI commands |
| PEC delivery and SDI notification processing | Implemented; configuration required | Requires real credentials and operator verification; local readiness is not a live delivery test |
| Events and user hooks | Available in core | Persistence and script execution have the boundaries described above |
| Assistant and conversational terminal | Optional: `ai` | Requires a configured provider; tool allowlist and confirmation rules apply |
| Retrieval and embeddings | Optional: `rag` (includes `ai`) | Requires indexing and the embedding/vector-store stack |
| Cash-flow forecasting | Optional / frozen: `ml` | Model-based estimates; not accounting guarantees |
| Browser frontend, TUI, in-process plugin API, voice, Lightning | Not supported | Outside the maintained product surface |

### Compatibility and quality evidence

The [test workflow](.github/workflows/test.yml) defines Linux and macOS jobs on
Python 3.12/3.13, plus a core-only Linux smoke/test job. These are configured CI
targets, not a claim that every run passes. Follow the live Tests badge for results;
Windows is not in this workflow's test matrix.

The [test suite](tests/) covers CLI, billing, XML, PDF, payment, events, and hooks.
Coverage floors are **49%** for the full package and **75%** for payments, as
configured in [pyproject.toml](pyproject.toml) and the
[payment workflow](.github/workflows/payment-tests.yml). Floors are thresholds,
not measured coverage results. Historical reports are not current quality evidence.

## Documentation

| Your goal | Start here |
| --- | --- |
| Set up and inspect the installation | [Configuration](docs/CONFIGURATION.md), then command-specific `--help` |
| Find CLI and conversational options | [CLI reference](docs/CLI_REFERENCE.md); use live `--help` for the current `cliente` / `fattura` surface |
| Understand document generation | [XSD validation](docs/XSD_VALIDATION.md), [PDF generation](docs/PDF_GENERATION.md) |
| Configure AI workflows | [AI architecture](docs/AI_ARCHITECTURE.md), [feature extras](docs/CORE_VS_EXTENSIONS.md) |
| Extend or contribute | [Architecture](docs/ARCHITECTURE.md), [hook examples](examples/hooks/), [contributing](CONTRIBUTING.md) |
| Review changes and limitations | [2.4.0 release notes](docs/releases/v2.4.0.md), [changelog](CHANGELOG.md), [technical debt](docs/TECHNICAL_DEBT.md) |

Some deeper guides retain earlier CLI or release descriptions. Prefer the current
command help and package metadata when they differ; material under `docs/history/`
is historical context.

## Development & Contributing

The full development stack includes optional features and test/quality tools:

```bash
uv sync --frozen --all-extras
uv run python -m pytest -q
uv run ruff check .
uv run ruff format --check .
uv run mypy openfatture/
```

The default pytest selection excludes performance, benchmark, slow, end-to-end,
and Ollama tests. Those need explicit selection and, where applicable, external
services. See [contributing](CONTRIBUTING.md) for the development workflow.

Report bugs or propose improvements through
[GitHub issues](https://github.com/gianlucamazza/openfatture/issues).
OpenFatture is released under the [MIT License](LICENSE).
