Settori e YAML

Ogni azienda Queria appartiene a un settore (sector) e opzionalmente a un sotto-settore (subSector). La configurazione vive in file YAML versionati nel repository, che descrivono il dominio semantico del settore: che entita esistono, come si chiamano in linguaggio naturale, quali misure aggregare, quali regole di accesso applicare.

A partire dalla v3.5.0 questi YAML sono molto piu ricchi: includono tag, domain terms, dimensioni con alias, misure, gerarchie e politiche di confidenzialita.

Settori disponibili

Queria include 26+ settori out-of-the-box:

Categoria	Settori
Servizi professionali	LEGAL, FINANCE, INSURANCE, BANKING, HR
Sanitario	HEALTHCARE, PHARMA, RESEARCH
Industria	MANUFACTURING, AUTOMOTIVE, ENERGY, ENGINEERING, CONSTRUCTION
Beni di consumo	FOOD, ECOMMERCE
Trasporti	LOGISTICS, TELECOM
Pubblico	GOVERNMENT, EDUCATION, NONPROFIT
Servizi	HOSPITALITY, TOURISM, SUPPORT, MEDIA, REAL_ESTATE, AGRICULTURE
Generico	CONTRACT, TECHNICAL, GENERIC, CUSTOM

Ogni settore ha un file YAML in backend/src/config/sectors/<sector>.sector.yml e viene caricato all'avvio dal sector-loader.

Anatomia di un settore YAML

Esempio (estratto da legal.sector.yml):

sector: LEGAL
name: "Legale"
description: "Contratti, sentenze, normative, atti legali"

typicalConcepts:
  - tipo_documento
  - parti
  - giurisdizione
  - data
  - materia
  - articolo
  - clausola

typicalQueries:
  - "Cerca contratti con la societa X"
  - "Quali sentenze riguardano il condominio?"
  - "Cosa dice l'articolo 5 del contratto?"
  - "Normativa sulla privacy"

relevantMetadataFields:
  - document_type
  - parties
  - jurisdiction
  - date
  - matter
  - court

externalSources:
  - legal-sources

domainTerms:
  - contratto
  - sentenza
  - clausola
  - articolo
  - giurisdizione
  - parte
  - attore
  - convenuto

dimensions:
  - name: document_type
    type: string
    aliases: ["tipo documento", "tipo atto", "tipologia"]
    hierarchy: [category, specific_type]
  - name: parties
    type: string[]
    aliases: ["parti", "soggetti", "attore", "convenuto"]
  - name: date
    type: date
    aliases: ["data", "anno", "periodo"]

measures:
  - name: count
    type: count
    description: "Conteggio elementi"
  - name: distribution
    type: group_by
    description: "Distribuzione per dimensione"

accessPolicy:
  topicIsolation: true
  confidentialityRules:
    - role: READER
      exclude: ["CONFIDENTIAL", "RESTRICTED"]
    - role: EDITOR
      exclude: ["RESTRICTED"]
    - role: ADMIN
      exclude: []

yamlVersion: 1

Campi del settore

Identita

Campo	Tipo	Descrizione
sector	enum	Codice unico (uppercase, es. LEGAL)
name	string	Nome visualizzato (es. "Legale")
description	string	Descrizione breve, mostrata nell'UI azienda

Linguaggio naturale

Campo	Tipo	Uso
typicalConcepts[]	string[]	Concetti che ricorrono nelle domande, usati dal planner
typicalQueries[]	string[]	Domande tipiche, usate per il prompt del classifier
domainTerms[]	string[]	Vocabolario del settore: aumenta il punteggio dei chunk che li contengono e migliora l'estrazione di metadati

Tag e domain terms potenziati v3.5.0

I domainTerms ora sono anche stampigliati nei chunk Qdrant come payload top-level (domainTerms) tramite il backfill sector-fields. Cio velocizza il filtro retrieval di ~5x e migliora il booster di pertinenza.

Dimensioni e misure

dimensions[] -- attributi semantici sui quali ha senso filtrare, raggruppare, confrontare:

• name: nome canonico (es. parties)
• type: string | string[] | number | date
• aliases[]: sinonimi in linguaggio naturale (es. ["parti", "soggetti", "attore", "convenuto"])
• hierarchy[]: gerarchie facoltative (es. [category, specific_type] per drill-down)

measures[] -- aggregazioni applicabili:

• type: count | sum | avg | min | max | group_by

Il planner LLM usa dimensioni e misure per costruire query strutturate quando l'utente chiede aggregazioni ("quanti contratti del 2025?", "qual e la media degli importi per categoria?").

Sorgenti esterne

externalSources[] -- elenca i microservizi esterni rilevanti per il settore. Esempi:

• LEGAL -> legal-sources (Normattiva)
• FOOD -> food-sources (Open Food Facts)
• PHARMA -> pharma-sources (FDA, ClinicalTrials)
• TOURISM -> consuma open-data via AI Constructor

Access policy

Politiche di confidenzialita per ruolo:

accessPolicy:
  topicIsolation: true
  confidentialityRules:
    - role: READER
      exclude: ["CONFIDENTIAL", "RESTRICTED"]

Significato: un utente con ruolo READER non puo vedere chunk con confidentiality in CONFIDENTIAL o RESTRICTED. Le policy si applicano al filtraggio Qdrant a runtime, indipendentemente dai topic.

Sotto-settori

Un settore puo avere sotto-settori (subSectors) che ereditano la base e applicano delta:

subSectors:
  contractDrafting:
    description: "Redazione e revisione contratti"
    dimensions:
      - name: clause_category
        type: string
        aliases: ["categoria clausola", "tipo clausola"]

I sotto-settori sono utili per company che condividono il settore di base ma hanno specializzazioni: es. uno studio legale "tax" e uno "labor" hanno il settore LEGAL ma sotto-settori diversi con dimensioni piu fini.

In DB ogni sotto-settore e una riga di SubSector; l'assegnazione all'azienda avviene via Company.subSectorId. Senza assegnazione, il routing settoriale non scatta e i chunk Qdrant non vengono arricchiti con i campi di settore.

Assegnare un settore a un'azienda

Dal pannello admin:

1. Aziende > [azienda] > Settore -> seleziona il settore dalla dropdown.
2. Opzionale: scegli un sotto-settore.
3. Salva. Da questo momento i nuovi documenti ingestati saranno stampigliati con i campi di settore.

Per company esistenti precedenti alla v3.5.0:

UPDATE "Company"
SET "subSectorId" = '<id-da-SubSector>'
WHERE id = '<companyId>';

Poi esegui i backfill per arricchire i chunk gia in Qdrant (vedi Ingestion DSL > Reingest).

Modificare un YAML

I file *.sector.yml sono versionati nel repo. Per modificarli:

1. Apri il PR su backend/src/config/sectors/<sector>.sector.yml.
2. Schema validato da Zod (_schema.ts): build CI fallisce se invalido.
3. Bump yamlVersion di 1.
4. Deploy: al boot, sector-loader ricarica gli YAML, sector-seeder aggiorna Sector e SubSector in DB.

Backfill dopo modifica

Se aggiungi/rinomini domainTerms, considera di rieseguire il backfill sector-fields sulle company del settore, altrimenti i chunk esistenti non avranno i nuovi termini in payload.

Custom sector per tenant

Per tenant che non rientrano nei 26 settori inclusi:

• Usa sector: CUSTOM con un YAML interno.
• Configura dimensioni/misure/domain terms specifici per il dominio del cliente.
• I documenti vengono comunque indicizzati e ricercati normalmente.

In V2 e in roadmap la creazione di settori custom da UI (no piu PR del file YAML).

Tag azienda (potenziati v3.5.0)

Indipendentemente dal settore, ogni azienda ha un campo tags[] che funziona da etichetta libera:

• Visibili nella scheda azienda.
• Filtrabili nelle ricerche cross-tenant (solo SYSTEM_ADMIN).
• Usati dal planner per disambiguare domande quando il settore non basta (es. "azienda con tag enterprise" -> usa template enterprise per il bot).

Inserisci i tag dalla scheda Azienda > Tag, separati da invio o tab.

Domain terms aziendali

Oltre ai domainTerms del settore, ogni azienda puo aggiungere domain terms specifici dalla scheda:

• Sigle interne (es. MOL, EBITDA-adj).
• Nomi prodotti del cliente.
• Glossario terminologico aziendale.

Vengono fusi con quelli del settore quando si valuta la pertinenza dei chunk, dando un boost esplicito al lessico dell'azienda.

---

Queria v3.5.0 -- Settori YAML potenziati