Documentary assistant and statistics

Connect a question, numbers and a territory

Understand a question, find its proofs, calculate and locate the results on a map. Mobilize large language models by limiting the data transmitted to their API.

Discover the project
010203
  1. 01

    Define

    How to measure profitability?

  2. 02

    Measure

    What margin rate for each store?

  3. 03

    Locate

    Where are the five stores selected?

A question may ask for a document, a calculation and a map

“In the Ain department, what are the five most profitable stores in 2025? Rank them according to their operating margin rate and show them on a map. » To answer, you have to find the definition of this indicator, compare the stores over the same year, then locate them. My goal is to bring these steps together without sending all the files to the model vendor.

Why is a simple chatbot not enough?

A language model can interpret a question, but its general knowledge does not contain our files or their current figures. RAG supplies document passages: first retrieve, then write from the evidence found. I add statistical and geographical tools to address questions that text alone cannot answer.

123The result feeds the rest
  1. 01

    Interpret

    The model chooses a tool and its parameters.

  2. 02

    Run

    The application controls then carries out the operation.

  3. 03

    Observe

    The result guides the next action.

The model interprets; tools retrieve and calculate

The assistant works like an analyst with tools. The language model chooses an action: consult a dictionary, find a rule, query a table or prepare a map. The server executes it and returns a bounded result. The model can then continue the analysis or formulate an answer.

Why separate reasoning and execution?

The flexibility of natural language comes from the model; the figures come from operations actually executed. FastAPI organizes server-side exchanges and verifies tool calls. React presents answers, tables, sources and maps. This separation makes it possible to change the model used without directly entrusting it with the storage of files or the rendering of the interface.

010203
  1. 01

    A described field

    Type, definition and unit.

  2. 02

    An authorized operation

    Sum, average, counting… depending on the meaning.

  3. 03

    A recognizable source

    Document, passage and data version.

Before calculating, know what each column represents

In our example, the file contains the store, department, year, revenue, operating expenses and coordinates. We need to know whether amounts cover the same period and which costs are included. On import, columns are described by type, definition, unit and permitted aggregations. Published data becomes resources available to the agent.

Why a dictionary rather than column names alone?

The dictionary prevents the model from guessing the meaning of an abbreviation or mixing two indicators. A published version sets out what is available and how to use it. The documents follow another preparation: division into passages, conservation of the source and indexing. We thus prepare the tables to calculate and the texts to justify.

010203
  1. 01

    Question

    Compare the margins of stores in Ain.

  2. 02

    Settings

    Department 01, year 2025, margin rate, top 5.

  3. 03

    Control

    Check the query before calculating.

Transform “the most profitable in Ain” into a query

The agent must filter department 01 and the year 2025, calculate the margin rate of each store, sort from highest to lowest, then retain five results. If the user only says “the most profitable”, the criterion must be specified: profit in euros or margin in percentage? These two classifications may be different.

Why regulate the freedom of the model?

The agent can offer SQL, but the server controls access and execution. The project also has a typed plan path: filters, measurements and groupings pass through an intermediate representation, or Query IR. In both cases, a plausible intention must be distinguished from an authorized operation on the correct columns.

010203
  1. 01

    Two searches

    Exact words and proximity of meaning.

  2. 02

    A common classification

    Merger of ranks and reclassification.

  3. 03

    Some evidence

    Excerpts retained with their sources.

Find a definition even if the question changes words

The user talks about “profitability”, while the guide describes “operating profit” and “margin rate”. The search must find the correct definitions without treating these terms as exact synonyms. SQLite FTS5 lexical search finds exact words and identifiers. Vector search encodes passages in coordinates, called embeddings, and brings formulations closer together. Embeddings and their ChromaDB index are operated locally.

Why combine two searches?

Lexical search is useful for exact references; vector search helps with paraphrases. RRF combines their rankings using ranks, without assuming comparable scores. Lightweight reranking refines the selection. The writing model then receives a small set of relevant passages rather than the whole corpus.

What does “profitable” mean in this ranking?

For this example, the guide defines operating profit as revenue minus operating expenses. The margin rate relates this result to turnover. The response cites this definition and the rules on the charges retained: the user thus understands what the classification measures, before reading the figures.

Why display the proof next to the answer?

Smooth wording can be convincing even when it is wrong. Linking the statements to the passages found allows us to verify their origin and their scope. The references are checked, but an existing citation is not enough to guarantee a good interpretation: the evaluation also verifies that the text supports the answer and that the system knows how to abstain.

The biggest turnover is not the best margin

In the example table, the Bourg-en-Bresse store achieves €1.2 million in turnover for €960,000 in expenses: its result is €240,000, or a margin of 20%. That of Gex achieves €2.5 million in turnover but generates €200,000, or 8%. DuckDB calculates these values on the application side and ranks the five stores by decreasing margin rate.

Why specify the criterion before designating the best store?

Bourg-en-Bresse comes first in terms of margin: 20 cents of operating profit per euro of sales. Oyonnax, however, generates more results in euros: €340,000, compared to €240,000. “Best” therefore depends on the question asked. The model explains the difference; the calculation applies the chosen definition, over the same year and a comparable scope of charges.

The same results take a geographical position

“Show these five stores on a map.” The server reuses the ranked selection: Bourg-en-Bresse, Oyonnax, Ambérieu-en-Bugey, Belley and Gex in our example. Leaflet displays their coordinates; clicking a point reveals the store’s revenue, operating profit and margin rate.

Why does a map provide something other than a table?

The table ranks performance; the map reveals its distribution across the department. It helps locate nearby or distant stores without, on its own, explaining their margins. GeoJSON associates coordinates with indicators. A store without coordinates may be listed, but should not be placed arbitrarily on the map.

“Among these five stores, keep those whose margin reaches 15%”

The request retains the department, the year and the five previously classified stores. It adds an inclusive threshold of 15%. Bourg-en-Bresse (20%), Oyonnax (17%) and Ambérieu-en-Bugey (15%) remain displayed. Belley (11%) and Gex (8%) come out of this selection.

Why distinguish between a filter, a grouping and a limit?

“Among these five stores” asks to filter the previous selection. “All stores in Ain above 15%” would require starting from the entire department, without keeping the top 5. The agent must distinguish these intentions so as not to display an incomplete subset. Here, the map and the export must contain the same three stores.

010203
  1. 01

    In the app

    Complete files, indexes, calculations and results.

  2. 02

    To the model

    Request, definitions, extracts and bounded overviews.

  3. 03

    To the interface

    Tables, maps and exports from local results.

The supplier receives a selection useful for the task

Source files, indexes and work results are preserved on the application side. To take action, the model can receive the question, conversation context, useful column definitions, document extracts and a preview of results. The code caps previews at 40 lines and 40,000 characters, with lower configurable budgets.

Why keep a local result behind an identifier?

The agent can request a map or an export based on a result identifier: the application then finds the complete lines. The preview sent to the model does not become the limit of the data displayed. This mechanism reduces the circulation of data and the cost of exchanges, while retaining enough information for the model to choose what to do next. A preview can, however, contain values: limiting the volume does not anonymize them.

123The result feeds the rest
  1. 01

    Useful context

    What was requested and selected.

  2. 02

    New intention

    What the follow-up keeps or replaces.

  3. 03

    Updated result

    An updated range calculation or map.

Remember scan without resending all files

“And in the Rhône department?” only makes sense with the previous question. The project keeps the application history and a state useful for analysis: geographical scope, operation and previous result. Redis supports sessions and caches, to reuse context between requests.

Why does continuity imply a choice of conservation?

The agent channel uses a response chain maintained by the provider to continue the conversation. Its identifiers are tracked locally, with expiration and deletion mechanisms. The separate document editor uses a request without response storage. Architecture therefore seeks to control what circulates and its lifespan; it does not correspond to entirely offline operation.

Find the right proof

Hit@5 · share of questions for which an expected passage appears among the first 5 results.

  1. Vector only76.4 %
  2. Hybrid without reclassification90.6 %
  3. Hybrid + light reclassification93.4 %
  4. Cross-encoder tested85.8 %

Local comparison on 118 questions. Good research is necessary; the correctness of the written answer is checked separately.

Is more complex research necessarily better?

The local evaluation compares methods on 118 questions. The relevant passage appears among the first five results in 76.4% of cases with vector search alone, 90.6% with hybrid search without reranking, and 93.4% with lightweight reranking. This metric, Hit@5, evaluates retrieval: it is not the proportion of correct final answers.

Why choose the compromise rather than the biggest device?

The tested cross-encoder, which reads the question and each passage together, selects more precise context but retrieves the relevant evidence less often: 85.8% Hit@5, with p95 latency around 1.96 s. The balanced profile also preserves the more expensive profile’s recall with 8 extracts rather than 12. On this corpus, adding computation or context does not improve everything: retrieval, writing, abstention and latency must be measured separately.

010203
  1. 01

    Deploy

    A repeatable service configuration.

  2. 02

    Observe

    Latency, errors and tool behaviour.

  3. 03

    Check

    Access, sources, calculations and conversation scenarios.

A useful response must also be able to be controlled

After a successful demonstration, it remains to manage access, data versions, errors and response time. The server controls accessible resources and requests. The user can consult the sources, examine the results and export their analysis for verification or further analysis.

Why these tools around the model?

Docker Compose brings services together into a reproducible configuration. Prometheus collects operating metrics; Grafana makes them readable to spot an increase in latency or errors. The tests also cover ambiguous requests, missing data and zone changes. These building blocks make behaviour observable, beyond the quality of an isolated response.

010203
  1. 01

    Flexibility

    Formulate, reformulate and combine analyses.

  2. 02

    Limited exchanges

    Transmit what is useful, with explicit budgets.

  3. 03

    Integrity

    Link answers to data, calculations and sources.

A RAG that can be deployed in companies, is flexible and verifiable

The goal is to offer an assistant for non-sensitive data, capable of going from a free question to a sourced explanation, a calculation, a map and an export. Large models provide flexibility of understanding; the tools and application storage provide a concrete basis for the results.

Why combine flexibility and integrity?

The flexibility allows you to formulate a new analysis without creating a screen for each need. Integrity consists of preserving the meaning of the columns, the requested scope and the traceability of the results, while limiting the data transmitted to the supplier. This project aims for this compromise for enterprise deployment: an ability to explain and verify, to test on each corpus and each configuration.