ccnl-engine

A Python library for modeling Italian collective labor agreements (CCNL) as structured, versioned data and computing gross-to-net salary and employer cost from first principles.

Why

Italian payroll is governed by collective agreements (CCNL) that define base salaries, seniority increments, and allowances as time-series values — they change at negotiated renewal dates. Existing tools either lock this data inside proprietary systems or require a full HRMS. This library treats each CCNL as a validated JSON file and the computation as a pure function:

compute(ccnl, rules, ComputeRequest(...)) → ComputationResult

Quickstart

from datetime import date
from ccnl_engine.contracts.loaders import load_ccnl
from ccnl_engine.tax.loaders import load_year_rules
from ccnl_engine.engine.compute import ComputeRequest, compute
from ccnl_engine.models.ccnl import TaxSector
from ccnl_engine.models.employment import Permanent

ccnl = load_ccnl("commercio-confcommercio.json")
rules = load_year_rules(2026, TaxSector.TERZIARIO, num_employees=50)
result = compute(
    ccnl,
    rules,
    ComputeRequest(level_code="4", as_of=date(2026, 9, 1), employment=Permanent()),
)

print(result.net_annual)  # → Decimal('...')
print(result.employer_cost_annual)  # → Decimal('...')

CCNL coverage

Layers legend

Status legend

CCNL Matrix

1. Approximate estimates. Sources: CNEL, INPS, Ministero del Lavoro, CCNL renewal communications.

2. Salary tables were extracted from official CCNL documents using Claude Code (AI-assisted), without manual human review. Values should be verified against the official source before use in production payroll systems.

The 59 contracts above cover approximately 14.3 million workers (sum of per-CCNL estimates; some overlap is possible where sector boundaries are not mutually exclusive, so the unique-worker count is somewhat lower). Italy has roughly 16 million employees covered by some collective agreement (ISTAT/CNEL 2024, public and private sectors combined). This library therefore reaches an estimated ~85–90% of CCNL-covered workers on a gross-headcount basis.

What is not modelled

• Addizionali regionali and addizionali comunali
• Detrazioni per carichi di famiglia (Art. 12 TUIR)
• IVS contributory ceiling split (Art. 1 L. 335/1995)
• Second-level bargaining (territorial and company agreements)
• Bilateral system contributions (EST, Fon.Te, …)
• Overtime, night/holiday premiums, leave accruals, sick-pay integrations

Each limitation is documented in the relevant data file's coverage.notes field and marked with # SIMPLIFICATION: comments in the engine source.

Releasing a new version

Releases are fully automated via GitHub Actions. Steps:

1. Bump version in pyproject.toml following SemVer.
2. Commit the change: git commit -m "chore: bump version to X.Y.Z".
3. Push a tag: git tag vX.Y.Z && git push origin vX.Y.Z.

The release workflow then: runs the full test suite, builds the wheel and sdist with uv build, verifies the tag matches the package version, publishes to PyPI via Trusted Publishing (no API token required), and creates a GitHub Release with auto-generated notes and the dist files attached.

Pre-requisite (one-time): configure a Trusted Publisher on PyPI for this repository under the pypi GitHub environment.

Development

This library was built with AI coding assistants — Claude Code, Codex, and Opencode. Generated code is covered by the test suite but has not been manually reviewed line by line.

Disclaimer

This library is not legal or tax advice. Figures are computed from publicly available CCNL tables and statutory rates as of the dates indicated in the data files. Always verify results against official sources or a qualified payroll professional.