Concepts

Sources, dossiers, questions, réponse adaptative, modes et budgets, preuves, threads et runs.

Sources#

Un fichier envoyé, une URL, une spécification de connecteur (arxiv:1706.03762) ou du texte (text:...) (Formats).

Identifiant src_…; un plan de régions (pages, sections, chapitres, fenêtres de temps, enregistrements).
Une source inconnue nommée dans une question est inspectée à la volée et gardée dans la bibliothèque. Ajout explicite: POST /v1/sources.
Parmi beaucoup de sources, Sextant classe leurs courtes descriptions (titre, plan, premières lignes) et n'ouvre que les meilleures, au plus max_sources.
Dans une bibliothèque de séries (plusieurs rapports par société, un par an), les noms de fichiers, ou à défaut les premières pages, disent l'auteur et la période de chaque document: une question qui nomme une société et une année ouvre d'abord ces documents.

Sources dynamiques#

Recherches (hn-search:...), flux (feed:...), issues GitHub, DNS, directs.

Un identifiant par spécification, quel que soit le contenu.
Rafraîchie quand une requête l'ouvre et que sa capture est plus ancienne que refresh_s (PATCH /v1/sources/{id}). Rien ne tourne en tâche de fond.
Chaque changement est un instantané daté; un contenu inchangé marque seulement le dernier comme à jour.
Un run garde la capture qu'il a interrogée. Une capture qui sert une réponse est conservée comme source fixe dans le dossier Kept from live sources (« Captures conservées » dans l'application); à la main: POST /v1/sources/{id}/keep.
twitch:<chaîne> et twitch-chat:<chaîne>: rien n'est enregistré à l'ajout; chaque requête enregistre le flux (ou lit le chat) pendant qu'elle tourne, par morceaux de 10 s interrogés à leur arrivée. Durée: ?window=N ou config.window_s, 5 à 300 s (chat: 120 s au plus), dans la limite de temps du mode.

Dossiers#

Ensembles de sources nommés et imbriqués (API).

Une source peut être dans plusieurs dossiers; noms uniques entre voisins.
Supprimer un dossier garde ses sources; ses sous-dossiers remontent d'un niveau.
Cibler un dossier dans les sources d'une question: par identifiant (fld_…), nom ("Contrats") ou chemin ("Clients/Acme"). Il est remplacé par ses sources et celles de ses sous-dossiers, puis la sélection habituelle s'applique.

Questions#

Un seul point d'accès, POST /v1/ask, pour toutes les questions. Sextant choisit la méthode:

la plupart des questions: une recherche directe, puis une réponse citée;
une question en plusieurs parties, comparative ou une liste: le workflow de recherche. Jusqu'à 4 sous-questions, cherchées dans toutes les sources; preuves recoupées; chaque affirmation vérifiée contre ses citations; SQL en lecture seule sur les tableaux trouvés (un total, une moyenne), cité comme preuve. En deep, une boucle d'agent avec outils le mène (événement research_mode).

Réponse adaptative#

La réponse est aussi longue que la question le demande: une phrase pour « Quel âge a le PDG ? », un rapport structuré pour « Une étude complète de mes 10 PDF ». Ni la question ni la réponse n'ont de limite de taille fixe.

Avant la lecture, la longueur est planifiée d'après la question (ses mots, sa longueur) et les sources qu'elle concerne.
Pendant la lecture, le plan est révisé selon ce qui est trouvé: une demande ouverte dont les preuves couvrent plusieurs sources devient un rapport, lu aussi profondément qu'en deep. Un fait (une date, un montant, un nom) reste court.
Le plan figure dans processing.adaptive_output et dans les événements output_planned et output_replanned. Une réponse longue reçoit les jetons de modèle de langage qu'il lui faut au-delà de max_llm_tokens.
max_output_tokens plafonne la réponse, budget la recherche. Une réponse longue coûte plus (billing.price_usd); le monthly_budget_usd d'une clé d'API plafonne la dépense (Tarifs).

Modes et budgets#

Un budget borne le temps et ce qu'une requête lit. Préréglages (Rapide, Équilibré, Approfondi dans l'application):

Champ	Limite	`fast`	`balanced`	`deep`
`max_latency_s`	temps de recherche (s)	8	30	180
`max_sources`	sources ouvertes	3	8	16
`max_regions`	passages lus en profondeur	4	10	30
`max_transcription_seconds`	audio ou vidéo transcrit (s)	120	600	2 400
`max_ocr_pages`	pages en OCR	4	20	80
`max_frames`	images de vidéo examinées	24	80	300
`max_followed_links`	pages web liées suivies	0	2	4
`max_llm_tokens`	jetons du modèle de langage	10 000	30 000	150 000

budget: un préréglage ("deep") ou un objet qui en part et remplace des champs:

JSON

{ "budget": { "preset": "deep", "max_latency_s": 60, "max_frames": 50 } }

Champ	Description
`preset`	`fast`, `balanced` (défaut), `deep`
`follow_links`	suivre les liens des pages lues si la réponse reste faible (même site d'abord, `robots.txt` respecté); défaut `true`
`derive_sources`	ouvrir une source appelée par la question (« combien de pharmacies à... »: données cartographiques); défaut `true`
`answer_mode`	`auto` (défaut), `extractive` (citations seules, sans modèle de langage), `llm`
`reasoning_tier`	`auto` (défaut), `fast`, `flagship`: niveau du modèle qui rédige
`background_enrichment`	lecture peu coûteuse du reste de la source après le run; défaut `true`
`max_decisions`, `max_steps`, `candidate_pool`	avancé: décisions rapides, étapes de l'agent, passages considérés

La limite de temps borne la recherche; la rédaction ajoute quelques secondes, plus pour un rapport long. Un budget est un plafond, pas un prix (Tarifs).

Preuves et citations#

Champ	Description
`id`	`ev_…`; `GET /v1/evidence/{id}`
`source_id`, `region_id`, `source_title`, `source_uri`	provenance
`quote`	texte exact (`description` pour une preuve visuelle)
`locator`	emplacement précis (ci-dessous)
`label`	emplacement lisible: `p. 847`, `pp. 12-13`, `7:47-8:09`, `§ Tarifs`, `lines 40-52`
`link`	lien profond: page du PDF, seconde de la vidéo, ancre de la page web
`path`	titres des sections englobantes
`confidence`, `modality`	0 à 1; `text`, `visual`, `audio`, `table`
`table`	preuve calculée: SQL, colonnes, lignes

`locator.kind`	Champs
`pages`	`page_start`, `page_end`, `bbox` (`[x0, y0, x1, y1]`, points PDF, origine en haut à gauche, une seule page), `page_width`, `page_height`
`time`	`time_start`, `time_end` (s), `frames` (horodatages des images examinées)
`web`	`url`, `heading_path`, `anchor`, `dom_path`
`text`	`char_start`, `char_end`, `line_start`, `line_end`
`record`	`index`, `keys` (champs identifiants), `field`

La réponse est rédigée dans la langue de la question.
confidence vient de signaux (pertinence, couverture, sources concordantes, chiffres cités mot pour mot, affirmations vérifiées, contradictions), pas d'une auto-évaluation d'un modèle.
Preuves faibles mais liées: la première phrase dit que les sources ne répondent pas directement, puis la réponse rapporte ce qu'elles disent, cité.
Contradiction: signalée; un erratum ou une correction donne la valeur en vigueur.

Threads et relances#

Renvoyez le thread_id d'un résultat pour une relance (« et pour 2025 ? », « c'est faux, regarde la page 12 »). Elle est réécrite en requête autonome et cherchée dans les sources du thread (sauf si elle en nomme d'autres), à partir des preuves des tours précédents. Points d'accès: Threads.

Runs et liens de partage#

Chaque question est un run (run_id; une « recherche » dans l'application). Il garde ses événements, passages lus, preuves, couverture par source, tableaux et requêtes SQL. Lien de partage (environment_url) et SQL: Runs.

Espaces de travail#

Un par compte: sources, dossiers, threads, runs, solde. Un identifiant d'un autre espace répond 404, comme un identifiant inexistant.