Skip to content
Back to search

agevolazioni-radar

Italian hiring incentives read from INPS circulars: citation-gated extraction, deterministic eligibility, Recupero agent with consultant review, MCP server, evals.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zvirmykhailo1987-cyber--agevolazioni-radar/badge.svg)](/listings/zvirmykhailo1987-cyber--agevolazioni-radar)

HTML

<a href="/listings/zvirmykhailo1987-cyber--agevolazioni-radar"><img src="/api/listings/zvirmykhailo1987-cyber--agevolazioni-radar/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 145 lines
  1. # Agevolazioni Radar
  2. [![ci](https://github.com/zvirmykhailo1987-cyber/agevolazioni-radar/actions/workflows/ci.yml/badge.svg)](https://github.com/zvirmykhailo1987-cyber/agevolazioni-radar/actions/workflows/ci.yml)
  3. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  4. **Italian hiring incentives, read from the source and applied to a company's hires.** A daily pipeline loads INPS
  5. circulars and messages, versions their text and turns each incentive into a rule in which every value carries the
  6. paragraph and the exact words it was read from. *Recupero* checks every hire of a company against every incentive,
  7. estimates the contribution saving and hands each proposal to a *consulente del lavoro*, who approves or rejects it.
  8. Agents use the same knowledge base through an MCP server.
  9. **Live demo:** https://incentivi-demo.159.195.219.73.sslip.io — public INPS data, two synthetic example companies.
  10. Consultant sign-in: `consulente` / `consulente-demo-2026` (each visitor's decisions stay in their own session).
  11. Five-minute walkthrough: [docs/DEMO.md](docs/DEMO.md).
  12. > Technical demo, not advice. In Italy the decision on payroll incentives belongs to a *consulente del lavoro*
  13. > (L. 12/1979). This system pre-screens, cites and estimates; it never decides. Not affiliated with INPS.
  14. ![Recupero: the consultant's work queue for one company](docs/screenshot-recupero.png)
  15. ## Why it is built this way
  16. Incentive rules change through a chain of acts: a law, then a circular, then operating messages, sometimes a
  17. corrected circular. Secondary sources often get the details wrong. Example from this corpus: circular 56 says the
  18. 2026 ZES bonus needs a worker who has **reached** 35, an employer with **at most 10** employees, and covers **ten**
  19. regions, Marche and Umbria included. A system that proposes money to an employer has to stand on the primary text,
  20. keep its versions, say "not stated" instead of guessing, and leave the decision to the professional.
  21. ## What it does
  22. | | |
  23. |---|---|
  24. | **Load and version** | `dlt` source over the public JSON endpoints behind inps.it: 651 acts since January 2025, 49 of them about employer contribution incentives. Each run re-reads the last 120 days, because INPS corrects acts after publication; a text row is appended only when its hash is new. `dbt` on DuckDB builds a version table (SCD2 on the text hash) and the knowledge-base input; source freshness warns after 2 days. Dates in Europe/Rome time (UTC puts every act one day early). |
  25. | **Anchored paragraphs** | INPS HTML becomes numbered paragraphs (`§4.p2`, 4,419 in total), so every value and every answer can point at one place in one act. |
  26. | **Extraction with a citation gate** | Claude fills a strict schema through structured outputs, "null if not stated". A value is kept only if its quote (4+ whole words) is in the cited paragraph **and** states the value: digits or Italian number words, full dates, each region by name. Conditions the schema cannot hold ("madre di almeno tre figli") are extracted as text, tagged as about the worker or the employer, and never assumed true. The gate is re-applied to stored model output on every read. |
  27. | **Registry and consolidation** | A human-maintained registry (18 incentives, aliases, required criteria) maps acts to incentives; an unmapped incentive is reported, never merged by guess. The earliest act is primary; a later act fills gaps; a *different* value is shown for review and applied only when a consultant decides, difference by difference. |
  28. | **Eligibility (code, not the model)** | Per criterion: pass / fail / to check, with the quote behind each line. Missing hire data, a value the gate dropped, a required criterion the acts did not yield, an open-ended hiring window or an unresolved difference all mean "to check" — never "passed". A few exact INPS phrases ("Personale non dirigenziale") are settled from profile data; a sentence that mixes topics or carries an exception stays with the consultant. |
  29. | **Recupero (the agent)** | Every hire × incentive. Saving = min(salary × employer rate × exemption %, monthly cap) × duration, with the ZES cap where the region qualifies and the employer rate shown as an assumption. One proposal per hire (incentives treated as not cumulable), alternatives listed, employer conditions as an attestation checklist, CSV export. |
  30. | **Human in the loop** | Consultant sign-in (scrypt, session token stored as a hash, CSRF on every write, 8-hour expiry), approve/reject with a note, an append-only audit log; rejected proposals leave the totals. |
  31. | **Q&A and MCP** | BM25 over the paragraphs, indexed with each act's subject. Every quote must be in its paragraph and every figure in the answer must appear in the retrieved text, otherwise the answer becomes a refusal. MCP tools (read-only): `search_passages`, `list_incentives`, `get_incentive`, `check_eligibility`, `diff_versions`, `kb_status`. |
  32. | **Operations** | Airflow DAG and a server cron (weekdays, Rome time): load, dbt build, paragraphs, extraction of new or changed acts, eval alert; the refresh runs on a copy and swaps it in atomically. LLM call log (tokens, latency, errors), status page with eval history and loads, CSP and rate limits on live questions. |
  33. Architecture and failure modes: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). Decisions a reviewer will question
  34. (DuckDB vs Snowflake, why dense retrieval is off, why the model never decides): [docs/DECISIONS.md](docs/DECISIONS.md).
  35. Product scope: [docs/PRODUCT-SPEC.md](docs/PRODUCT-SPEC.md).
  36. ## Measured (20 Nov 2026)
  37. **Grounded Q&A** — [golden set](evals/golden_qa.json): 24 *dev* questions used while tuning, 8 *holdout* questions
  38. written afterwards and never used for tuning, 7 questions the sources do not answer (2 of them on-topic near
  39. misses). 3 runs each, scored on whole words; min and max equal the mean unless shown.
  40. | | dev (24) | holdout (8) |
  41. |---|---|---|
  42. | Answer states the expected facts | 92% | 75% |
  43. | A cited paragraph itself states those facts | 90% (88–92) | 75% |
  44. | Refuses when the sources are silent | 5/5 | 2/2 |
  45. | Quotes rejected by the gate | 0 | 0 |
  46. | Gold paragraph among the top 10 retrieved (no LLM) | 18/24 | 5/8 |
  47. Every answered question stated the expected facts; every miss was a refusal, not a wrong answer. The misses are
  48. retrieval misses. Dense retrieval (MiniLM embeddings fused with BM25) was measured and did worse on this corpus, so it
  49. ships switched off ([ADR-2](docs/DECISIONS.md)).
  50. **Extraction:** 26/27 hand-labelled fields across circulars 55, 56 and 57, including fields that must stay empty. The
  51. miss: circular 56 also admits *somministrazione*; the model returned only *tempo indeterminato*.
  52. **Recupero** — [answer key](evals/golden_recupero.json) for the two example companies (8 expected findings), written
  53. by hand from the circulars:
  54. | | |
  55. |---|---|
  56. | Expected findings surfaced (recall) | 8/8 |
  57. | Surfaced findings that are expected (precision) | 8/8 |
  58. | Wrong "probabile" (would cost the employer money) | 0 |
  59. | Verdict "to check" where the key says "probabile" | 5/8 |
  60. The engine is conservative on purpose: worker conditions it cannot settle from data, unresolved differences between
  61. acts and required criteria missing from the extraction all become "to check". The answer key and the companies are
  62. the author's; an independent key from a payroll consultant is the next step.
  63. **Code:** 183 tests, offline (fake INPS over `httpx.MockTransport`, fake LLM, real dlt + dbt in a temporary DuckDB),
  64. 96% line+branch coverage (gate 90% in CI), `mypy --strict`, ruff, bandit, pip-audit.
  65. **Crash tests of the full cycle** ([tests/test_crash.py](tests/test_crash.py)): INPS down (three tries, then a loud
  66. failure, yesterday's data untouched); a half-filled listing row (skipped, the rest loads); a model call that times out
  67. (counted, retried next run, the refresh continues); a daily spending cap (spent on the newest acts, cached ones do not
  68. count); hostile HTML and spreadsheet formulas in the model's output (escaped on every page and in the CSV); a broken
  69. database file mid-swap (the app keeps serving the last good one); 8 consultants deciding at once (no 500, no lost
  70. decision); 11 hostile URLs (no 500, no file outside `static/`, no open redirect). Writing them found three real
  71. defects, now fixed: the daily cap counted cached acts, so new acts were never extracted on the server; one bad row
  72. aborted the whole load; `?rate=nan` returned a 500.
  73. **Property-based simulation** ([tests/test_properties.py](tests/test_properties.py), Hypothesis, 2,800 random rules ×
  74. hires per run): less hire data, a value the gate dropped or an open difference never makes a verdict more favourable;
  75. an estimate never exceeds the stated cap; the condition reader stays silent on anything but a known phrase.
  76. **Scale simulation** ([scripts/simulate.py](scripts/simulate.py) → [docs/simulation.json](docs/simulation.json)):
  77. 2,000 synthetic hires against the real knowledge base in under 2 s, 0 invariant violations (one proposal per hire,
  78. never outside a confirmed hiring window, never above the cap, totals add up, rejections reflected); 400 concurrent
  79. page requests, 0 errors. It also showed that every proposal is "to check" — which is why the company page is built as
  80. a work queue ([docs/DESIGN.md](docs/DESIGN.md)).
  81. **Independent review:** an adversarial reviewer with no access to the author's reasoning ran the code and reported
  82. 9 defects; all are fixed with a regression test each (among them: one Italian word order turned an eligible hire into
  83. "not eligible"; a condition dropped by the citation gate disappeared instead of blocking "likely"; a contested value
  84. could exclude a hire; non-ASCII CSRF tokens caused a 500).
  85. **Mutation check:** each guarantee above is removed on purpose and a test must fail
  86. ([docs/mutation-results.json](docs/mutation-results.json)).
  87. **Cost:** extracting all 49 acts took 0.72M input and 0.11M output tokens (prompt v6), once. Afterwards only new or
  88. corrected acts are extracted: results are cached by text hash, prompt version and model, and the server caps a daily
  89. refresh at 10 extractions.
  90. ## Run it
  91. ```bash
  92. python -m venv .venv && . .venv/bin/activate
  93. pip install -c requirements.lock -e ".[dev]"
  94. cp .env.example .env.local # ANTHROPIC_API_KEY=... (extraction, evals and live Q&A only)
  95. radar-load --since 2025-01-01 # INPS -> DuckDB (data/radar.duckdb)
  96. dbt build --project-dir dbt --profiles-dir dbt
  97. radar-kb paragraphs && radar-kb extract
  98. radar-evals --repeats 3 --baseline evals/results/baseline.json # non-zero exit on any regression
  99. radar-web # http://localhost:8040
  100. radar-mcp # MCP over stdio (Claude Desktop, Claude Code)
  101. pytest # no network, no API key
  102. ```
  103. `docker compose up` runs the web app with the knowledge base mounted read-only.
  104. ## Known limits
  105. - Retrieval misses 3 of 8 holdout questions; the system then refuses rather than answers.
  106. - INPS acts only, since 2025; laws in Gazzetta Ufficiale and CCNL texts are not loaded.
  107. - Savings assume the maximum duration and an employer contribution rate; actual start date, part-time and
  108. terminations are not modelled.
  109. - Cumulability between incentives is not modelled; the consultant chooses between the proposal and its alternatives.
  110. - The registry, the answer keys and the example companies are written by the author.
  111. ## License
  112. [MIT](LICENSE) © 2026 Mykhailo Zvir

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.