# TypeSafe — teren de test

Separat de ROAFACTURARE si de restul produselor ROA. Nimic de aici nu intra in
niciun produs; e doar pentru a invata API-ul si a proba pe date reale.

## Rulare

Pune cheia in `.env` (o linie, fara ghilimele):

```
TYPESAFE_API_KEY=cheia_ta
```

apoi:

```sh
python typesafe_test.py
```

`.env` e in `.gitignore` — nu pleaca niciodata pe git. `.env.example` e sablonul
versionat. Daca `TYPESAFE_API_KEY` exista in mediu, are prioritate peste `.env`.

## Ce e in folder

| | |
|---|---|
| `.env` / `.env.example` | cheia API, neversionata / sablon |
| `typesafe_test.py` | un apel, cate o intrebare din fiecare tip, pe o linie de factura de furnizor. Modifica `state` si `criteria` pe cazuri reale. |
| `docs/` | documentatia oficiala, descarcata ca Markdown (111 pagini) |
| `update_docs.sh` | reia docs-urile cand se schimba |

## API, pe scurt

`POST https://api.typesafe.ai/v1/systemone`, header `Authorization: Bearer <cheie>`.
Trimiti `model` (`jev-latest`), `state` (ce vede modelul) si `questions` — oricate,
evaluate in paralel intr-un singur apel, fara sa se vada intre ele.

| tip | intoarce | pentru |
|---|---|---|
| `choice` | optiunea aleasa, probabilitati per optiune, `confidence` | una din N |
| `noul` | o probabilitate 0–1 de „da” | tine o conditie? |
| `score` | poziția pe scara descrisa, probabilitati per nivel, `confidence` | grad pe o dimensiune |

Nu intoarce text, cod sau explicatii. Fara imagini/audio deocamdata.

## De citit, in ordine

1. `docs/introduction/quickstart.md`
2. `docs/concepts/system-one.md` si `docs/concepts/how-to-build-with-system-one.md`
3. `docs/concepts/state.md` — cum structurezi ce trimiti
4. `docs/primitives.md` + pagina primitivei alese (`docs/primitives/choice.md` etc.)
5. `docs/confidence.md` — cum se citeste incertitudinea si de ce pragurile se
   calibreaza pe datele tale
6. `docs/model-jaggedness/` — unde modelul se descurca prost
7. `docs/api.md` sau `docs/sdk/python.md` daca vrei SDK in loc de urllib

Cookbooks relevante pentru ce ar putea folosi in ROA: `cookbooks/entity_alignment.md`
(potrivire furnizor/client), `cookbooks/pre_parsed_value_extraction_cookbook.md` si
`cookbooks/date_extraction_cookbook.md` (extragere din documente),
`cookbooks/hierarchical_classification.md` (incadrare pe plan de conturi),
`cookbooks/sde_cascade.md` (escaladare cand modelul nu e sigur).

## Capcane de reținut

- `confidence` spune cat de concentrata e distributia, nu cat de corect e raspunsul.
- `noul` la 0.50 = „da si nu la fel de probabile”, nu „intensitate medie”.
- Pune mereu o ieșire „niciuna” cand s-ar putea sa nu se potriveasca nimic.
- La selectie din candidati: nu poate alege o valoare pe care n-ai trimis-o.
- Pragurile din cookbooks sunt exemple, nu reguli.