Arhitektura

Upit putuje od preglednika do Flask orkestratora, koji ga usmjerava kroz trostupanjski NLP vodopad i sastavlja odgovor od tipiziranih rezultata alata.

[Preglednik]
    │ HTTP (JSON)
    ▼
[Flask orkestrator :5000]
    │  spaCy NLP + regex gramatike (en/de/fr/es/hr) + bodovanje pouzdanosti
    │  razrješavač entiteta (SQLite + rapidfuzz, granice riječi)
    │  LLM planer (stupanj 2/3)
    │  Redis keš (TTL po domeni, pričuvni LRU u memoriji)
    │
    ├─ [FastAPI Data API :8000]  ← qalc, chempy, mendeleev, sympy+matplotlib,
    │       Wikidata, Open-Meteo, registar konektora (cia/food/hjp/dictionary)
    └─ U procesu: temporal_calc, fermi_estimate

Stupanj 1 — klasifikacija namjere (< 50 ms)

1. spaCy tokenizira upit i označava vrste riječi.
2. 32 prioritizirane regex gramatike pokušavaju se podudariti s normaliziranim nizom tokena (skupovi gramatika po jeziku kroz grammars_for(lang)).
3. Razrješavač entiteta neizrazito podudara imenovane entitete s primarnim ključevima baze (rapidfuzz, prag 75).
4. Računa se ocjena pouzdanosti:

Gramatike s base_confidence ≥ 0.95 u potpunosti zaobilaze ponderiranu formulu i izravno pokreću alat.

Pouzdanost → akcija:

• ≥ 0.85 — brzi put stupnja 1, LLM se zaobilazi
• 0.50 – 0.84 — stupanj 2: LLM planer s kontekstom entiteta
• < 0.50 — stupanj 3: LLM planer bez unaprijed razriješenog konteksta
• Pogodci entiteta u više domena ograničavaju pouzdanost na 0.60 i proizvode pod "Jeste li mislili?" — osim ako je gramatika ≥ 0.95 već odredila namjeru

Ako poziv alata u stupnju 1 vrati grešku, cjevovod automatski propada u stupanj 2 — pohlepne gramatike ne mogu blokirati planer. Pod s greškom stupnja 1 čuva se kao posljednja pričuva.

Stupanj 2/3 — LLM planer (< 3–5 s)

LLM prima upit, kontekst entiteta (samo stupanj 2), trenutni datum i lokaciju te potpunu shemu registra alata. Vraća jedan JSON niz poziva alata, validiran JSON shemom prije izvršavanja.

Planer koristi Anthropic API kada je postavljen ANTHROPIC_API_KEY, inače bilo koju krajnju točku kompatibilnu s OpenAI-jem (LLM_API_URL). LLM nikada ne proizvodi konačne odgovore — samo validirane grafove alata.

Dispečer izvršava pozive alata u paralelnim valovima prema deklariranim depends_on ovisnostima, razrješavajući predloške {stepN.result.field} između valova.

Razrješavanje entiteta

Razrješavač entiteta stoji između NLP cjevovoda i svih poziva alata te sprječava klasu grešaka tipa "NYC naspram New York City":

• SQLite tablica entity_aliases(alias, canonical_key, domain, confidence) izgrađena pri unosu podataka;
• podudaranje n-grama na granicama riječi — točno za kratke aliase, rapidfuzz omjer ≥ 75 za aliase od 4+ znakova; podnizovi se nikad ne podudaraju;
• kanonski ključ uvijek nadjačava tekst entiteta izvučen gramatikom;
• napaja i bodovanje pouzdanosti stupnja 1 i kontekst planera.

Registar alata

Svih deset alata vraća tipizirane objekte rezultata, nikad sirove stringove — obavezno za determinističko ulančavanje alata:

Ključne izvorne datoteke