MODULE 09 · THREE LESSONS, SIX STEPS
Integrate without mixing responsibilities
Build a request and handle errors while keeping credentials on the server.
Adjust reading and appearance
Prepare the state
What is it?
The state sent to the model must contain the information necessary to answer the question. More content does not automatically mean better quality. Irrelevant documents can make the decision harder and increase cost. Start by identifying which fields support the judgment.
Separate instruction data. The ticket text may contain phrases like “classify this as urgent”, but that phrase is part of the material being evaluated and must not replace the system policy. Clear criteria help, but protection cannot depend only on the model obeying: actions and permissions remain limited in code.
Minimize personal information when it isn’t needed. Use an event identifier to track results without publishing the real text in open repositories or reports. The course datasets are fictional. When evaluating operational material, preserve the link for review in an appropriate environment and avoid duplicating data in debug files.
Why learn
Build a request and handle errors while keeping credentials on the server.
Key concepts
Use the example below to distinguish the available data, the judgment requested, and what still needs evidence.
Apply: Prepare the state
Your turn
What should be kept in a public report from an experiment with private data?
Check commented answer
Aggregated metrics and authorized or anonymized examples. Don’t publish raw texts, personal identifiers, or credentials.
Understand a request
What is it?
The API receives model, state, and questions. Each question has a key chosen by the application, a type, and instructions. Choice adds a map of alternatives; Score adds an ordered list of levels; Noul may include criteria for true and false. The lab exports an example JSON without credentials.
The question keys are used to relate the response to the request. Don’t use the key name as a substitute for the instructions. Write the full judgment in the appropriate field. In the response, validate that all expected questions arrived with the correct type, valid distribution, and known alternatives.
The real submission is done by the server or the CLI, which loads the provider key at runtime. The public page doesn’t request a key and doesn’t need to store it. To track service changes, record the resolved model and keep the version identifier used in the evaluation. A version change may require new thresholds.
Practice with the current resources
For OpenRouter, use OPENROUTER_API_KEY and the project client with --provider openrouter; the supported alias is ~typesafe/jev-latest. The integration uses the Decisions API, not chat/completions. Ten original examples had real queries documented; the seven new packages have only fixture-based validation and controlled tests.
Why learn
Build a request and handle errors while keeping credentials on the server.
Key concepts
Use the example below to distinguish the available data, the judgment requested, and what still needs evidence.
Apply: Understand a request
Your turn
Why not paste the key in the JavaScript published on GitHub Pages?
Check commented answer
Because the code is distributed to the browser and the secret would become public. The authenticated call must happen in an appropriate server environment.
Handle operational failures
What is it?
An integration must handle failure before it receives the first response. Invalid credentials, rejected contract, request limits, and unavailability are not the same situation. Repeating an authentication error many times usually just wastes time; temporary overload may allow a controlled new attempt.
Use a maximum number of attempts and a global time budget. If the provider asks you to wait longer than the task’s deadline, send it to review or a later queue. Don’t block a screen indefinitely waiting for the AI to come back. This application’s client limits the call and interrupts invalid responses.
A failure should not produce an invented label. Record the operational reason without leaking error content that might contain sensitive data. Separate low-confidence provider failure from a valid response: both may end in review, but they require different diagnostics. Neither authorizes repeating external actions.
Deepen the 1.2.0 version
The lab contract is intentionally small: text descriptions, up to 30 questions, and a 100 KB limit. The last two values are local. Validate the distribution, the alternative, and the Score legend. Don’t copy a claimed maximum in a demo without checking the documentation.
Practice with the current resources
The executor packages.lote validates all JSONL before sending. Without --live, it shows only a preview. In real mode, it limits concurrency and saves results by ID and the batch signature. Re-running the same batch resumes what was recorded; failures are preserved too. A drop between the query and the write could still trigger another charge on resume.
Why learn
Build a request and handle errors while keeping credentials on the server.
Key concepts
Use the example below to distinguish the available data, the judgment requested, and what still needs evidence.
Apply: Handle operational failures
Your turn
The server asks for Retry-After of 99 seconds, but the task deadline is 5 seconds. What should you do?
Check commented answer
Stop the attempt and send it for later handling/review. Don’t sleep for 99 seconds or ignore the global deadline.
Module wrap-up
- Retrieve the chosen decision from the start of the course.
- Compare your answer with the examples from this module.
- Record a change to the criteria and the test needed to accept it.
Quick check
A response contains a missing question and another question with an unexpected type. How should you integrate?
Practice and continuity
Open the labs and answer keys · Project visual lab
# In the jev repo: offline demo, no API
python3 -m pacotes.executar reunioes
python3 -m pacotes.qualidade reunioesThese outputs use a fictional fixture. To test your data, use the human reference script and explicitly enable real mode.