bandiradar: Instructions file for Claude Code

CLAUDE.md — bandiradar (open core)

Internal status, roadmap and strategy live in ROADMAP.local.md (gitignored, local only — read it first if present).

Project memory for coding agents. Read this fully before editing. The deep design lives in ARCHITECTURE.md; this file is the operational contract.

One-liner

Open-source engine that monitors Italian public funding opportunities (tenders, grants, incentives), normalizes them into one canonical Opportunity model, and ranks them against a company Profile with a two-stage matcher.

What this repo IS / IS NOT

• IS (open, MIT): engine, Source framework, reference adapters (ANAC, later incentivi.gov.it), two-stage matcher, CLI, MCP server.
• IS NOT (lives in private bandiradar-pro): web dashboard, premium/regional adapters, delivery channels (WhatsApp/email/alerts), multi-tenant, hosting.
• Boundary rule: single-user/local = here. Managed/multi-client/delivery = pro.
• Never add dashboard, paid, or delivery-channel code to this repo.

Architecture map (module → responsibility)

src/bandiradar/
  models.py        # pydantic: Opportunity, RawDoc, Profile, Match. THE contract.
  sources/
    base.py        # Source Protocol + registry
    anac.py        # ANAC/PNCP (OCDS) historical adapter + fixture
    anac_pvl.py    # ANAC PVL — OPEN tenders, live, no-creds + fixture
    heal.py        # LLM crawl-recipe healer (re-derives a drifted recipe)
    llm_scraper.py # reusable LLM HTML extractor; re-exports the crawl spine
    wordpress.py   # reusable WP-REST base (lazio, sicilia configs)
    plone.py       # reusable Plone `Bando` base (emilia_romagna config)
    sicilia.py     # EuroInfoSicilia FESR/FSC (WP base + categories filter)
    emilia_romagna.py # ER Politiche territoriali (Plone Bando)
    trentino.py    # Prov. Trento FEASR — CKAN open-data CSV adapter
    veneto.py      # Veneto SIU — LlmScraperSource (landing, HTML regex-recipe heal)
    piemonte.py    # Piemonte Drupal — LlmScraperSource (Views, HTML regex-recipe heal)
    puglia.py      # Puglia PR 21-27 — LlmScraperSource (Liferay fragment, badge; detect-only)
    sardegna.py    # Sardegna Impresa — LlmScraperSource (Views, HTML regex-recipe heal)
    fvg.py         # FVG bandi module — LlmScraperSource (contributi filter in regex; recipe heal; relay in CI)
    campania.py    # Sviluppo Campania — LlmScraperSource (widget anchors, title_template; recipe heal)
    calabria.py    # Calabria Europa — LlmScraperSource (WP-REST CPT, JSON recipe heal)
    basilicata.py  # Portalebandi — LlmScraperSource (WP-REST CPT, JSON recipe heal)
    liguria.py     # Liguria publiccompetition — LlmScraperSource (POST+CSRF fetch, regex recipe heal)
  cpv.py           # CPV Italian-label → 8-digit code resolver (pure, offline)
  trust.py         # trust spine: deterministic validation of LLM extractions (pure)
  crawl.py         # self-healing crawl spine (stdlib: recipes + drift + golden)
  recipe_store.py  # per-source CrawlRecipe overrides + golden (CONFIG, not code)
  matching/
    prefilter.py   # Stage 1: pure deterministic filter
    relevance.py   # Stage 2: LLM scorer (+ offline fallback + cache)
    llm.py         # provider-agnostic LLM client
    prompts.py     # prompt templates
  storage.py       # SQLite store, dedupe, change detection
                   #   + crawl_recipes + crawl_golden tables (self-healing crawl)
  core.py          # service layer that orchestrates the pipeline
  evaluation.py    # matching-quality eval: pure metrics + run over eval corpus
  cli.py           # Typer CLI (thin)
  mcp_server.py    # FastMCP server (thin)
  resources.py     # importlib.resources access to packaged data (below)
  data/            # PACKAGED runtime data (ships in the wheel)
    fixtures/      # recorded source payloads for offline tests / --sample
    profiles/      # example profiles (mayai.yaml, manifattura.yaml, …)
    eval/          # labelled eval set: opportunities.jsonl + gold.yaml
    cpv_it.json    # official EU CPV 2008 vocabulary (Italian label → code)
    comuni_it.json # ISTAT comuni table (region resolution for anac_pvl)
tests/
scripts/
  monitor_status.py    # live-monitor STATUS.md generator (pure, offline, tested)
.github/workflows/
  monitor.yml          # daily self-maintaining monitor (keyless; key→LLM+healer)

Runtime data lives INSIDE the package and is reached via bandiradar.resources (importlib.resources) — never Path(__file__).parents[...] — so --sample and the bundled example profiles work from a pip-installed wheel, not only a checkout. Interfaces (cli.py, mcp_server.py) are THIN — no business logic. All logic lives in core.py, sources/, matching/, storage.py.