openfatture 2.4.0__tar.gz → 2.4.2__tar.gz

openfatture-2.4.2/PKG-INFO

@@ -0,0 +1,347 @@
+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).

openfatture-2.4.2/README.md

@@ -0,0 +1,241 @@
+# 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).

{openfatture-2.4.0 → openfatture-2.4.2}/openfatture/__init__.py

@@ -5,6 +5,6 @@ A modern, CLI-first invoicing system with AI-powered workflows and full
 compliance with FatturaPA and SDI requirements.
 """
 
-__version__ = "2.4.0"
+__version__ = "2.4.2"
 __author__ = "Gianluca Mazza"
 __license__ = "MIT"

{openfatture-2.4.0 → openfatture-2.4.2}/openfatture/ai/providers/openai.py

@@ -229,14 +229,18 @@ class OpenAIProvider(BaseLLMProvider):
                         elif isinstance(tool_call, dict):
                             # Handle dict format tool calls
                             function = tool_call.get("function", {})
+                            arguments = function.get("arguments")
+                            if arguments is None:
+                                arguments = tool_call.get("arguments", {})
+                            if not isinstance(arguments, str):
+                                arguments = json.dumps(arguments, ensure_ascii=False)
                             tool_calls.append(
                                 {
                                     "id": tool_call.get("id") or tool_call.get("call_id"),
                                     "type": "function",
                                     "function": {
                                         "name": function.get("name") or tool_call.get("name"),
-                                        "arguments": function.get("arguments")
-                                        or tool_call.get("arguments", "{}"),
+                                        "arguments": arguments,
                                     },
                                 }
                             )

{openfatture-2.4.0 → openfatture-2.4.2}/openfatture/ai/runtime/prompt.py

@@ -29,6 +29,7 @@ def build_chat_system_prompt(context: ChatContext, *, enable_tools: bool = True)
         "- Risposte proporzionate alla richiesta: a un saluto rispondi con un saluto breve e una domanda, senza cataloghi di funzionalità.",
         "- Fornisci dettagli quando servono; evita emoji decorative e introduzioni ripetitive.",
         "- Distingui capacità disponibili da configurazione pronta. Conferma il completamento solo dopo un risultato positivo degli strumenti.",
+        "- Le fatture issued_elsewhere sono documenti storici emessi altrove, non vere bozze. Nei riepiloghi usa per_documento e distingui stato tecnico, stato SDI e incassi. Non dedurre mai da bozza che una fattura storica non sia stata emessa o trasmessa: senza evidenza SDI dichiara stato non verificato. Nessun pagamento registrato non prova il mancato incasso.",
         "- Usa un tono professionale ma friendly",
         "- Rispondi in italiano (salvo richiesta diversa)",
         "- Se non hai informazioni sufficienti, chiedi chiarimenti",