WelfareGraph

An executable formalization and research prototype for semantic call classification and explainable matching between funding opportunities and legal entities.

The G1 operational graph produced by the partial experiment on public calls. A navigable representation and the structured artifacts are available in examples/results.

WelfareGraph contains the code, questionnaires, and experimental artifacts developed for a master's thesis on data-driven welfare. The project translates concepts formalized in Lean by mathprompt into Python: semantic domains, operational differentiation graphs, question-answer signatures, cross-domain rules, and target-domain-guided inference.

This repository contains the actual implementation used in the experiment. It is a research prototype, not a commercial product or an automated decision-making system.

Experiment status

The experiment is partial and primarily covers the D1_bandi domain:

• document collection and filtering;
• construction of the base D1 questionnaire;
• classification and traversal of the G1 operational graph;
• generation and comparison of operational call signatures.

The second phase has not yet been completed empirically. The second D2 questionnaire for legal entities still needs to be designed, stabilized, and used with real organizational profiles. It will simplify the base questionnaire by selecting a reduced set of questions about an organization, sufficient to induce only the relevant D1 requirements. Entity-call matching, final ranking, and human-in-the-loop evaluation therefore remain future work.

The file questionario_D2_estrazione_requisiti_normalizzato.json preserves a separate draft schema for extracting call requirements. Its 45 questions do not constitute a validated D2 questionnaire for legal entities used in the experiment.

Model used: DeepSeek V4 Flash through DS4

Every experimental phase requiring language inference used DeepSeek V4 Flash, served locally through DS4 / DwarfStar, the open-source inference engine developed by Salvatore Sanfilippo (antirez).

DeepSeek V4 Flash is the language model, while DS4 is the runtime that executes it and exposes an OpenAI-compatible endpoint. This setup was used to:

• classify documents as BANDO or ALTRO and disambiguate multiple candidates;
• answer D1 questionnaire items while traversing the graph;
• propose discriminating questions when multiple calls retained the same signature;
• generate prototype cross-domain questions and rules.

Requests used a temperature of zero and constrained JSON output where required. Automated tests use a simulated client instead, so they do not measure the performance of DS4 or the model.

What the code implements

The pipeline is organized around four algorithms:

1. build_g1 builds the D1_bandi domain and the G1 operational graph from the questionnaire, or generates questions with the model.
2. infer_g1 traverses G1 for a single call and computes its operational signature: the set of question-answer pairs reached.
3. build_induction_objects prepares D2 questions, cross-domain rules, and premise sets that may induce answers in G1.
4. associate_legal_subject provides a prototype for inferring compatible calls from an entity profile.

Algorithms 3 and 4 are implemented and covered by deterministic tests, but this does not amount to a completed D2 experiment: the simplified entity questionnaire has not yet been stabilized or applied to a real sample.

The base D1 questionnaire contains 74 questions, 209 answers, and 192 declared edges. The versioned corpus contains 219 call and notice texts collected from public sources. The automated suite contains 89 tests.

Flow architecture

flowchart LR
    subgraph E["Experimented phase: D1 domain"]
        A["Public portals"] --> B["Scraping and download"]
        B --> C["Filtering and text extraction"]
        C --> D["D1 corpus"]
        Q["Base D1 questionnaire"] --> G["build_g1"]
        D --> G
        G --> S["infer_g1: operational signatures"]
        S --> V["Signature validation and comparison"]
    end
    G -. "phase 2 not completed" .-> I["Simplified D2 entity questionnaire"]
    I -.-> M["Human-in-the-loop matching and ranking"]

Loading

Graph and results from the included run

The g1_graph.json artifact describes a rooted acyclic graph with:

• 171 node instances and 170 edges;
• one root, q_n0, from which every node is reachable;
• 68 terminal nodes;
• 31 distinct question identifiers and 140 __sep nodes, introduced to reuse questions in different branches without creating cycles.

The report for the 219 operational signatures shows:

• 219 structurally valid signatures;
• 143 distinct signatures;
• 99 calls with a unique signature;
• 120 calls in 44 duplicate-signature groups, with a maximum group size of 7;
• 79 terminal classifications as FIN, 50 as APP, 40 as ACC, 36 as MAN, and 14 as MIX.

These results demonstrate execution of D1 classification, while also showing that differentiation is incomplete. They do not validate entity matching or empirical ranking. Metrics, calculation methods, and limitations are documented in docs/EXPERIMENTAL_RESULTS.md.

Quick start

Python 3.11 or later is required.

python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
pytest

The tests use a simulated AI client and require neither network access nor credentials.

To run the pipeline on four samples with a local DS4 server:

export LEAN_AI_BASE_URL=http://127.0.0.1:8000/v1
export LEAN_AI_MODEL=deepseek-v4-flash
export LEAN_AI_API_KEY=local-development

welfaregraph \
  --questionnaire questionnaires/questionario_D1_bandi_strutturato_VALID.json \
  --bandi-dir data/mini \
  --output-prefix results/

The endpoint must support /v1/chat/completions and constrained JSON output.

Repository structure

lean_prompt_thesis/      Python package and tests for the four algorithms
formal/                  Experimental Lean specification
questionnaires/          D1 questionnaire, drafts, and reduced cases
data/corpus/             Text corpus of 219 documents
data/mini/               Four small samples for quick tests
scripts/                 Pipeline, example, and signature analysis
tools/scraper/           Document collection, selection, and extraction
examples/results/        Graph, signatures, and D1 experiment reports
docs/                    Architecture, method, results, limitations, and roadmap

Main artifacts

• questionario_D1_bandi_strutturato_VALID.json: base questionnaire and initial D1 graph.
• questionario_D2_estrazione_requisiti_normalizzato.json: draft extraction schema, not a validated entity questionnaire.
• g1_graph.json: operational graph produced by the included run.
• report_vettori.csv: comparison of operational signatures for the 219 documents.
• grafo_percorso.mmd: Mermaid representation of the paths.

AI client configuration

Variable	Default	Purpose
LEAN_AI_BASE_URL	http://127.0.0.1:8000/v1	OpenAI-compatible DS4 endpoint
LEAN_AI_API_KEY	local-development	Local endpoint credential
LEAN_AI_MODEL	deepseek-v4-flash	Model used in the experiment
LEAN_AI_TIMEOUT	7200	Per-request timeout in seconds
LEAN_AI_RETRIES	3	Retries for transient errors
LEAN_AI_BACKOFF	5	Linear backoff in seconds
LEAN_MAX_BANDO_CHARS	40000	Maximum text sent per question

Scientific limitations

• The included run consolidates D1, not the entire D1-D2 methodology.
• The simplified D2 entity questionnaire, matching on real profiles, and explainable ranking are not validated results.
• Duplicate signatures show that the graph has not yet achieved complete differentiation across the corpus.
• Model answers may trigger deterministic fallbacks; logs and artifacts must be reviewed.
• The included Lean specification is an experimental artifact; the extended theoretical specification remains in mathprompt.
• Results do not constitute a legal assessment of eligibility for a call.

Data and responsibility

The corpus documents come from public sources and are included for research reproducibility. The Apache-2.0 license applies to the repository's original code; it does not alter the rights, terms, or attribution requirements applicable to third-party documents. Verify the official source and current version before reusing or redistributing the corpus.

The system must remain human-in-the-loop: its associations may guide analysis, but responsible people must verify requirements and make the final decision.

License

Code is released under the Apache-2.0 license. See LICENSE.