ebia 0.3.3

EquipeBaie Invoice Automation

Equipe Baie — Invoice Automation

Automated invoicing pipeline that parses PDF invoices, enriches them with client accounting references, and generates Excel accounting exports — with a desktop UI for day-to-day operation.

---

Project structure

EquipeBaie_Freelance-project/
├── src/
│   ├── ebia/                  # Core library (published to PyPI)
│   │   ├── parser.py          # PDF invoice parser
│   │   ├── xls_generator.py   # Excel (.xlsx) generator
│   │   └── cli.py             # CLI entry point
│   └── ebia_ui/               # Desktop application (not on PyPI)
│       ├── paths.py           # All filesystem paths — single source of truth
│       ├── logging_config.py  # App-wide logging setup
│       ├── main.py            # Application entry point
│       ├── core/
│       │   ├── config_manager.py   # Persistent JSON config
│       │   ├── client_manager.py   # Client reference registry
│       │   ├── engine.py           # Orchestration layer (RunEngine)
│       │   ├── manifest.py         # Processed-file tracking (SHA-256)
│       │   └── _mp_worker.py       # Subprocess entry point (multiprocessing)
│       ├── ui/
│       │   ├── main_window.py
│       │   ├── components/    # Reusable widgets, sidebar
│       │   └── views/         # Run, Config, Client, About pages
│       └── assets/            # logo.png, logo.ico, default_clients.json
├── tests/
│   ├── unit/                  # Pure-function tests, no I/O
│   ├── integration/           # Real PDF/Excel tests
│   └── e2e/                   # CLI subprocess tests
├── scripts/
│   └── build_exe.py           # PyInstaller Windows exe build
└── pyproject.toml

---

Components

ebia — core library

Stateless, no side effects. Can be used standalone via CLI or imported directly.

• parser.py — extracts Client, date, total_ttc from a French-format PDF invoice using pdfplumber; parse_many() parses a list of PDFs in parallel using ProcessPoolExecutor, returning (path, dict | Exception) pairs so callers never need to manage workers directly
• xls_generator.py — generates one .xlsx per month with one sheet per day; 3 accounting rows per invoice (411 / 44571 / 701). Supports retroactive insertion (patch_month_workbook) for late invoices arriving after a month has already been processed.

ebia_ui — desktop application

Built with customtkinter. Requires Python + display (not headless).

• Run view — manual trigger + recurring scheduler (daily / weekly / monthly). The engine runs in a separate process (own GIL) so the UI stays responsive during execution.
• Config view — VAT rate, invoice folder path, configurable reports output folder, manual PDF archive trigger
• Client view — client reference registry (accounting code ↔ client name) with inline editing. Pre-populated with a default client list on first launch.
• About view — app version (read dynamically from the installed package)
• Manifest — SHA-256 deduplication: already-processed PDFs are skipped on subsequent runs; only recorded after successful Excel generation
• Per-month document counters — each calendar month tracks its own last-used document number independently, so re-running for a past month never resets or conflicts with other months

ebia_ui/paths.py — centralised path configuration

All filesystem paths are defined in one place. To change a location, edit only this file:

APP_DIR      = Path.home() / ".equipe_baie"                          # config, clients, manifest, logs
REPORTS_DIR  = Path.home() / "Documents" / "Equipe_Baie" / "Rapports"
ARCHIVES_DIR = Path.home() / "Documents" / "Equipe_Baie" / "factures_archives"

---

Application data locations

Data	Default location
Config (VAT rate, folder paths, etc.)	~/.equipe_baie/config.json
Client reference registry	~/.equipe_baie/clients.json
Processed-file manifest	~/.equipe_baie/processed.json
Application logs	~/.equipe_baie/logs/ebia.log (5 MB × 3 rotating backups)
Generated Excel reports	~/Documents/Equipe_Baie/Rapports/ (configurable in Config view)
Archived PDFs	~/Documents/Equipe_Baie/factures_archives/ (configurable in Config view)

On Windows ~ resolves to C:\Users\<user>, on Linux/macOS to /home/<user>.

---

Installation

Windows — no Python required

Download EquipeBaie.exe from the latest GitHub Release and run it directly. No installation needed.

Library only (CLI usage)

pip install ebia

Development (library + UI + tests)

git clone https://github.com/Alamajdoub9/EquipeBaie_Freelance-project.git
cd EquipeBaie_Freelance-project

python -m venv .venv
source .venv/bin/activate          # Linux / macOS
# .venv\Scripts\Activate.ps1       # Windows PowerShell

pip install -e ".[dev,app]"

---

Running the application

ebia-ui
# or
python -m ebia_ui.main

On first launch:

1. Go to Configurations and set the invoice folder path (where your PDFs are stored)
2. Optionally adjust the VAT rate, the reports output folder, and the archive folder
3. Go to Clients to review the pre-loaded client list and add or edit entries as needed
4. Go to Exécution and click Lancer maintenant

Generated Excel files are written to the reports folder configured in the Config view (default: ~/Documents/Equipe_Baie/Rapports/).

To archive processed PDFs after a run, go to Configurations → Archivage des Factures and click Archiver les factures traitées. Only PDFs already recorded in the manifest are moved.

---

CLI usage (library only)

# Parse a single PDF and print extracted fields
ebia --path facture.pdf

# Generate Excel from a folder of PDFs
ebia --path ./invoices --out ./output/result.xlsx --start-piece 1 --start-document 1

---

Running tests

# All tests
pytest

# By level
pytest -m unit
pytest -m integration
pytest -m e2e

# With coverage
pytest --cov=src/ebia --cov=src/ebia_ui/core --cov-report=term-missing

Test matrix:

Suite	What it covers
unit/test_parser.py	PDF field extraction logic, parse_many contract
unit/test_generator.py	Excel row generation and formatting
unit/test_manifest.py	SHA-256 manifest: load, save, deduplication
unit/test_ebia_ui_core.py	ConfigManager, ClientManager, RunEngine error paths
integration/test_engine.py	Full pipeline: PDFs → parse → enrich → xlsx
integration/test_generator_xlsx.py	Multi-month/multi-day workbook structure
integration/test_parser_pdf.py	Real PDF corpus parsing
e2e/test_cli.py	CLI invoked as subprocess

---

Delivery

The project has two deliverables released together by the same workflow.

1. ebia PyPI package

pip install ebia

Published automatically on every release. The ebia_ui package is excluded from the wheel (internal app, not a public library).

2. Windows desktop application (.exe)

Built via PyInstaller on a Windows runner and attached to the GitHub Release alongside the wheel. No Python installation required.

# Build locally (requires PyInstaller)
python scripts/build_exe.py
# produces: dist/EquipeBaie.exe

---

Versioning and release

Both deliverables share a single version number defined in pyproject.toml. The about view reads it dynamically via importlib.metadata — no manual update needed.

To publish a new release, trigger the Release workflow from the GitHub Actions UI and pick the bump type:

Input	Effect	Example
patch (default)	Bug fixes	0.2.0 → 0.2.1
minor	New features, backwards-compatible	0.2.0 → 0.3.0
major	Breaking changes	0.2.0 → 1.0.0

The workflow will:

1. Bump the version in pyproject.toml and push a chore: bump version to X.Y.Z commit to main
2. Run the full test suite (gate)
3. Build and publish the wheel to PyPI
4. Create a GitHub Release with the wheel attached
5. Build EquipeBaie.exe on Windows and attach it to the release

---

Requirements

• Python >= 3.10
• Library deps: pdfplumber, openpyxl
• UI extra deps: customtkinter >= 5.2.0, Pillow >= 10.0.0
• Dev deps: pytest, pytest-cov, pytest-mock, ruff, mypy