openfatture

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Changed

• Drop remaining user-facing Venere Labs / venerelabs branding after venerelabs.com expired (not renewed). Example company data uses Example S.r.l.; package __author__ is Gianluca Mazza; landing-page copyright is © 2024–2026 Gianluca Mazza (info@gianlucamazza.it). PlatformDirs still uses the historical venerelabs appauthor so Windows data/config paths stay put.

[2.3.0] - 2026-09-11

Added

• Nota di credito (TD04) support (PR #57):
  • create_nota_credito_from_fattura application command for creating credit notes from invoices
  • CLI command: openfatture fattura create-credit-note --from-invoice <id>
  • FatturaPA XML builder support for TD04 document type
  • DatiFattureCollegate XML element for linking credit notes to original invoices
  • Alembic migration adding fattura_originale_id, fattura_originale_numero, fattura_originale_data columns for document linkage
  • Comprehensive integration tests for TD04 XML generation and workflow

Changed

• Real CLI: openfatture fattura generate-xml command now actually generates FatturaPA XML:
  • Wired to existing InvoiceService.generate_xml() and FatturaPA XML builder (no stubs, no mocks)
  • Honors --output for custom XML file path
  • Honors --dry-run to display XML without writing to disk
  • Full test coverage for normal generation, custom output, dry-run mode, and error handling
• Slim Alembic migration (commit 8cf82bd24752):
  • TD04 linkage columns added with minimal schema footprint
  • Migration tested and validated in CI

2.2.0 - 2026-09-11

Added

• PDF Layout improvements (PR #51):
  • Text wrapping for long line descriptions using ReportLab Paragraph objects
  • Multi-page table rendering with proper Table.split() support
  • Dynamic summary box height with space reservation calculation
  • HTML entity escaping for invoice descriptions (& < > characters)
  • Improved spacing between invoice sections
• Professional PDF template (PR #52):
  • Professional template is now the default (was minimalist)
  • Enhanced CEDENTE/PRESTATORE header block with better typography
  • Structured IBAN/payment information block with method mapping
  • Optional logo support via configuration (graceful fallback if missing)
  • Italian terminology throughout (Scadenza, Modalità di pagamento)
• First-class CLI commands (PR #52):
  • openfatture cliente command group (list, show, create)
  • openfatture fattura command group (list, show, create, add-line, generate-pdf, generate-xml, set-status)
  • Rich formatting for terminal output
• FatturaPA XML improvements (PR #53):
  • Fixed XML namespace qualification to pass XSD validation
  • Native support for natura field on line items (N1-N7 codes for zero-rated, exempt, out-of-scope VAT)
  • DatiCassaPrevidenziale model for social security contributions (TC01-TC22 codes)
  • Comprehensive XSD validation tests
  • Documentation: docs/SDI_TRANSPORT_READINESS.md (implementation guide, no live SDI emit)

Removed

• Experimental Lightning Network module (openfatture.lightning, extra lightning, config flags, lifespan hook, tests). LND gRPC was never product-complete. Docs archived under docs/history/lightning/.

Changed

• Project config hygiene: pytest local runs no longer force coverage (CI still does); Settings.app_version tracks package __version__; bumpversion pin aligned; technical debt docs updated for LangGraph default.
• SSOT: assistant backend ids live in platform.assistant_backends; package __version__ is re-exported by subpackages; AISettings hydrates credentials from platform AI_* (init/docs) with OPENFATTURE_AI_* override precedence; coverage fail_under=49 in pyproject.
• Feature extras are now ai, rag, ml only (all no longer includes lightning).
• Default PDF template changed from minimalist to professional.

[2.1.0] - 2026-08-08

Added

• LangGraph is the default product assistant backend (langgraph_tool_loop).
• Release notes: docs/releases/v2.1.0.md.

Changed

• Default assistant_backend / ASSISTANT_BACKEND: chat → langgraph.
• ChatAgent slimmed: single tool-loop via GraphAssistantBackend; keeps structured-output and shared prompt helpers. Rollback path: ASSISTANT_BACKEND=chat.
• AssistantRuntime constructs only the selected backend (no always-on dual init).

Notes

• Opt-in backend plumbing and parity tests shipped in 2.0.x unreleased work and are now the product default.

[2.0.2] - 2026-08-07

Fixed

• Status readiness no longer suggests enabling the AI extra when the extra is already installed and only credentials are missing.

[2.0.1] - 2026-08-07

Added

• Status readiness: core_ready, assistant_ready, checks, and next_steps (human table + --json).
• Interactive slash commands: /help, /exit, /session, /clear.
• LangGraph tool-loop parity tests (product backend remains chat_agent_tool_loop).

Changed

• ai.tools.registry is a package (core + defaults) with stable public imports.
• Init refuses silent .env overwrite; post-setup messaging is honesty-first.

Fixed

• Clearer onboarding next steps after init (does not claim assistant ready without extra).

[2.0.0] - 2026-08-07

Added

• Unified assistant runtime (openfatture.ai.runtime.AssistantRuntime) as the only product entry for CLI and interactive mode.
• Application-layer use-cases for AI tools under billing.application, payment.application, sdi.application, and pdf.tool_ops.
• Optional multi-node LangGraph tool-loop helper (ai.runtime.graph).
• File-backed interactive session persistence with optional --session resume.
• Honesty gates: lightning_allow_mock (default false), RAG reindex callback required, MissingExtraError for optional stacks.
• PEP 621 extras matrix: ai, rag, ml, lightning, all.
• Architecture docs: ARCHITECTURE.md, CORE_VS_EXTENSIONS.md, redesign notes.

Changed

• Package layout: billing, events, hooks, platform, pdf replace core, utils, and services.pdf.
• Tooling is Ruff-only for format and lint (Black/isort removed as drivers).
• Core install no longer pulls AI/ML/RAG/Lightning by default.
• Status JSON reports feature flags and experimental Lightning posture.

Removed

• Voice assistant package, web scraper, orphan analytics agents.
• In-process experimental plugins package (extensions use hooks only).
• Compatibility import shims for old package paths.

Fixed

• Lightning client no longer returns mock invoices/node info unless mock is explicitly allowed.
• RAG reindex queue no longer simulates work without a callback.
• Lint debt: no in-code noqa / type: ignore / pragma: no cover suppressions.

See docs/releases/v2.0.0.md for migration details.

1.3.1 - 2026-07-24

Fixed

• Updated the i18n CLI test contract to validate the current reduced command surface instead of removed web and domain command groups.

1.3.0 - 2026-07-24

Removed

• Removed the retired frontend application, its dependencies, tests, locale bundles, configuration, and documentation.
• Removed the in-memory web session backend; AI sessions now use the file-backed CLI store.

Changed

• OpenFatture is now explicitly CLI-first, with interactive terminal mode as its guided user experience.
• Reduced the public CLI to setup, configuration, status, and the agentic assistant; domain and plugin modules remain internal extension boundaries.
• Updated current documentation, version references, and project status to match the 1.3.0 codebase.

Tooling

• Added deterministic CLI demo validation and modernized GitHub Actions workflows.
• Added pre-commit checks for Python, TOML, YAML, Ruff, Black, and GitHub Actions.
• Consolidated MyPy configuration in pyproject.toml and made type checking blocking in CI.
• Updated Make and Docker Compose targets for the current CLI and Alembic workflow.

Removed

• Removed obsolete media automation workflows, generated scenario videos, and provider-dependent demo scripts.
• Removed obsolete command adapters while retaining core payment, Lightning, SDI, AI, and plugin modules.

1.2.0 - 2025-12-02

Added

• Event System & Audit Trail:

  • EventLog database model for complete event audit trail with UUID, timestamps, and entity tracking
  • Automatic event persistence with EventPersistenceListener (priority -100, error isolation)
  • Entity tracking (invoice, client, etc.) for filtering and timeline generation
  • Metadata support for additional context (JSON format)
  • JSON serialization for datetime, Decimal, nested objects, and lists
  • Global event bus initialization and shutdown management

• Event Repository:

  • Advanced query methods with flexible filtering (event_type, entity_type, entity_id, date_range)
  • Full-text search in event data with SQLite LIKE queries
  • Timeline generation for entities with human-readable summaries
  • Statistics aggregation (by type, by entity, total counts)
  • Pagination support (limit, offset)
  • Session management (internal or external session support)

• Event Analytics Service:

  • Time-based aggregations: daily, weekly, monthly activity
  • Event type distribution with percentages
  • Entity activity metrics (most active entities)
  • Activity trends comparing recent vs previous periods
  • Event velocity metrics (events per hour)
  • Hourly distribution patterns (0-23h analysis)
  • Comprehensive dashboard summary with key metrics

• CLI Event Commands (openfatture events):

  • list - List events with rich filtering (type, entity, date range, limit)
  • show <event-id> - Detailed event view with JSON-formatted data and metadata
  • stats [--last-days N] - Statistics summary with event type and entity breakdowns
  • timeline <entity-type> <entity-id> - Entity event timeline with tree-style visualization
  • search <query> [--limit N] - Full-text search with result snippets
  • types - List all event types with counts
  • dashboard [--days N] - Comprehensive analytics dashboard with:
    • Key metrics (total events, event types, velocity, trends)
    • Top event types with ASCII bar charts
    • Entity activity distribution
    • Trend indicators (increasing, decreasing, stable)
  • trends [--days N] [--type TYPE] - Time-based activity trends with bar charts

• Visualizations:

  • ASCII bar charts using Rich (█ blocks scaled to data)
  • Timeline view with tree-style connectors (┌ ├ └)
  • Trend indicators with color coding (green/red/yellow)
  • Formatted tables with proper alignment and styling
  • Panels for headers and detailed views

Technical

• Tests: 45+ new comprehensive tests for event system
  • 13 tests for event persistence (100% passing)
  • 27 tests for EventRepository (filters, search, stats, pagination)
  • 5 integration tests for fattura events (creation, validation, deletion, sending, timeline)
  • All tests passing with proper timezone handling
• Test Coverage:
  • Event persistence: 100%
  • Event repository: 91%
  • Event base (event bus): 88%
  • Event analytics: 15% (new module, will increase with usage)
• Total Project Tests: ~170 (increased from 117)
• Architecture: Observer pattern for event bus, Repository pattern for data access, error isolation for reliability

1.1.0 - 2025-10-12

Changed

• Localised the CLI, interactive experience, email templates, and PDF outputs to English for consistency across platforms.
• Updated documentation, quickstarts, automation tapes, and examples to reflect global English-first messaging.

Removed

• Dropped the legacy openfatture payment import-statement command alias in favour of openfatture payment import.

1.0.0 - 2025-10-10

Added

• Payment Tracking Module - Enterprise-grade bank reconciliation system:

  Domain Models:

  • BankAccount: Multi-account support with IBAN validation
  • BankTransaction: Full transaction lifecycle (UNMATCHED MATCHED IGNORED)
  • PaymentReminder: Automated payment tracking with configurable strategies
  • Value Objects: MatchResult, ReconciliationResult for type-safe operations
  • Enums: TransactionStatus, MatchType, ReminderStatus, ReminderStrategy

  Application Services:

  • MatchingService: Intelligent payment matching with pluggable algorithms (Facade pattern)
  • ReconciliationService: Saga-based workflow for multi-step reconciliation
  • ReminderScheduler: Automated payment reminder system with escalation strategies

  Matching Strategies (Strategy pattern):

  • ExactAmountMatcher: Amount + date window matching (configurable tolerance)
  • FuzzyDescriptionMatcher: NLP-based description matching with Levenshtein distance
  • IBANMatcher: Direct IBAN/BIC validation for wire transfers
  • DateWindowMatcher: Flexible date range matching
  • CompositeMatcher: Weighted combination of multiple strategies

  Import Infrastructure:

  • Bank statement importers: CSV (Intesa Sanpaolo, UniCredit, Revolut), OFX, QIF
  • Factory pattern for format detection
  • Bank-specific presets with field mapping
  • Transaction deduplication and validation

  Notification System (Strategy + Composite patterns):

  • EmailNotifier: SMTP with Jinja2 templates (HTML + text fallback)
  • ConsoleNotifier: Development/testing output
  • CompositeNotifier: Multi-channel notifications (email + SMS + webhook)
  • Configurable SMTP settings with TLS support

  Reminder Strategies:

  • DEFAULT: Single reminder at due date
  • PROGRESSIVE: Escalating reminders (-7, -3, 0, +3, +7 days)
  • AGGRESSIVE: Frequent follow-ups for high-risk clients
  • CUSTOM: User-defined reminder schedules

  CLI Interface (openfatture payment):

  • import: Bulk transaction import with progress tracking
  • list-transactions: Paginated transaction browser with filters
  • reconcile: Interactive matching with confidence scores
  • review: Review queue for medium-confidence matches
  • batch-reconcile: Automated high-confidence reconciliation
  • ignore/reset: Transaction state management
  • reminders: Schedule and manage payment reminders

  Testing & Quality:

  • 74 comprehensive tests (62 deliverable + 12 integration)
  • 100% test pass rate
  • 82-96% code coverage on critical services
  • Property-based testing with Hypothesis
  • Integration tests with real database workflows
  • CI/CD pipeline with GitHub Actions (multi-OS, multi-Python)

  Architecture:

  • Hexagonal Architecture (Ports & Adapters)
  • Domain-Driven Design (DDD) with aggregates and entities
  • SOLID principles throughout
  • Design patterns: Strategy, Saga, Facade, Composite, Factory
  • Type-safe with full mypy compliance
  • Structured logging with structlog

Changed

• Enhanced Pagamento model with stato tracking and data_pagamento
• Improved database models for payment reconciliation workflows

Technical Metrics

• Production Code: 6,742 LOC
• Test Code: 6,014 LOC
• Examples: 900 LOC
• Total Project Size: 13,656 LOC
• Test Coverage: 85%+ (enforced in CI)
• Dependencies: SQLAlchemy, structlog, rapidfuzz, ofxparse

0.1.0 - 2025-01-10

Added

• Core Invoicing:

  • FatturaPA XML v1.9 generation with full compliance
  • SDI integration via PEC (Certified Email)
  • Automatic XSD schema validation
  • Digital signature support (P7M, CAdES, PKCS#12)
  • Client and product management with SQLite database
  • Invoice CRUD operations with SQLAlchemy ORM
  • Payment tracking and due date monitoring

• Interactive CLI:

  • Modern TUI with Rich and Questionary
  • Hierarchical menu system (9 sections, 40+ actions)
  • Numeric shortcuts (1-9, 0) for fast navigation
  • Fuzzy search in all selectors
  • Multi-selection for batch operations
  • Progress bars for long-running tasks
  • Interactive dashboard with real-time statistics

• AI-Powered Workflows (CLI stubs - implementation planned for Phase 4):

  • CLI commands for AI features (ai describe, ai suggest-vat, ai forecast, ai check)
  • Placeholder responses showing planned functionality
  • Full implementation with LangChain/LangGraph planned for Phase 4
  • Dependencies included (langchain, langgraph, openai, anthropic, chromadb)

• Email System:

  • Professional HTML email templates with Jinja2
  • Multipart MIME support
  • Automatic notifications for SDI events
  • Template preview and testing

• Batch Operations:

  • CSV import/export for invoices
  • Bulk send to SDI with progress tracking
  • Bulk delete with safety confirmations
  • Operation history logging

• Developer Experience:

  • Type-safe code with Pydantic and mypy
  • Comprehensive test suite with pytest (>80% coverage)
  • Code formatting with Black and Ruff
  • Pre-commit hooks for quality checks
  • Database migrations with Alembic
  • Dynamic versioning with Hatchling
  • Automated version bumping with bump-my-version

• Autocomplete & Data:

  • Italian provinces (110 codes)
  • Postal codes for major cities
  • Tax regimes (RF01-RF19)
  • VAT nature codes (N1-N7)
  • Common service descriptions for freelancers
  • Payment methods

• Configuration:

  • TOML-based configuration
  • Environment variable support with .env
  • PEC account setup and testing
  • Database initialization wizard

Changed

• Migrated from Poetry to uv for faster dependency management
• Changed license from MIT to GPL-3.0-or-later

Security

• Secure credential storage for PEC accounts
• Encrypted digital signature handling
• Input validation for all user data

This site is open source. Improve this page.