A successful AI system has Very little AI on the critical path.

From abstraction to code

The principles, in real code

It is not theory: each principle becomes few lines of disciplined engineering. Pure Python, strict contracts and the LLM contained at a single step.

from pydantic import BaseModel, Field

class Inference(BaseModel):
    model_config = {"extra": "forbid"}         # rejeita campo inesperado do LLM
    intent: str
    confidence: float = Field(ge=0.0, le=1.0)  # limite no schema, nao no if

def run_pipeline(item, llm):
    # Serve a qualquer dominio: leads B2B, tickets de suporte,
    # pedidos de e-commerce, laudos medicos -- a estrutura e a mesma.
    signals = collect_signals(item)            # M1: deterministico (APIs, banco, sem IA)
    if signals.missing:                        # Open-World: ausencia = incerteza
        return Inference(intent="desconhecido", confidence=0.0)
    raw = llm.extract(signals.snippet)         # M2: LLM so no residuo interpretativo
    return Inference.model_validate(raw)       # valida a saida (input nao confiavel)

class TokenLedger:
    def __init__(self, daily_cap: int):
        self.cap = daily_cap
        self.spent = 0

    def try_spend(self, n: int) -> bool:
        if self.spent + n > self.cap:          # teto do dia atingido
            return False                       # falhar e parar: sem fatura surpresa
        self.spent += n
        return True

ledger = TokenLedger(daily_cap=1000)
for item in fila:
    if not ledger.try_spend(cost(item)):
        mark_pending(item)                     # retoma na proxima onda
        break                                  # para limpo, em ponto seguro

def explain(score):
    # nunca exponha o numero: traduza em "por que agora" + "o que falta"
    return {
        "why_now": [d.text for d in score.positive_signals],
        "gaps": score.missing_signals,         # honestidade Open-World
        "sources": [d.url for d in score.references],
    }

Guided Track

Learn by Discovery

Ten chapters, from prompt chaos to complete design. Open each to see the goal and What you come out with.

1. 01 From magic to engineering Beginner · 6 min

   No one builds a banking system by letting the database "decide freely" what to do with each transaction. The bank is powerful, but it operates inside of transactions, constraints and rigid contracts — it is powerful Because It's contained. An LLM deserves the same architectural respect.

   The problem: the most seductive way to build with AI is to chain prompts and give total autonomy to the model. It works in a demo; in production, it generates defects that classic software rarely faces — infinite loops (one agent returns the task to the other and each turn costs money), unpredictable cost, hallucinations that spread when the invented output of one turns into the other, and irreprobability (the same input produces different outputs, impossible to debug).

   The solution is cultural before technique: stop treating the model as magic and treat it as engineering. It applies to the probabilistic component everything we already know about reliable software — interface contracts, deterministic tests, budget control, isolation of responsibilities.

   In practice, this means that The ability comes from the model, but trust comes from engineering around it.

   Principle 1 →

2. 02 deterministic orchestration Beginner · 8 min

   Think of a fixed flowchart of a factory: each station does a specific thing and passes on the result. Compare it to a room where several people talk trying to decide what to do next. The first is a DAG — a graph of fixed steps; the second is an open conversation between models.

   The problem: giving LLM authority over the flow of control ("agents decide everything from end to end") is flexible and impressive — and impossible to guarantee. You can't promise deadline, estimate cost, or audit.

   The solution is to separate two layers that are usually confused. A orchestration layer/I-O can be asynchronous and fault tolerant — it is the edge of the system. A decision/calculation layer It must be pure and deterministic — that is where the result is computed, without randomness. The model is called inside One step to do one thing; he never decides which one will be next.

   In practice, this means that The LLM answers questions — it does not decide which questions to ask next.

   Principles 1 and 2 →

3. 03 Brain × display Intermediate · 7 min

   It's the difference between kitchen from a restaurant and the lounge. The kitchen is hot, dangerous and does not change every week — it is where hard work happens. The salon is the part that the customer sees and that you redecorate frequently. You don't put the stove in the middle of the tables, and you don't give the customer the key to the stock.

   The problem: cognitive systems have two opposite load profiles. The "brain" (cognitive motor) is heavy, asynchronous, sensitive (keys, data, proprietary logic) and rarely changes. The "Vitrine" (interface) is light, synchronous, exposed to the public internet and changes all the time. Attending them in the same application is a classic trap: a failure in the exposed window compromises the engine, and each interface change risks logic.

   The solution is to separate them physically and connect them by a narrow contract — typically an API with very few endpoints — never by a shared database. The brain processes in the background and public a snapshot ready; a display only read the result and collect feedback, returned in a controlled manner.

   In practice, this means that the itera team in the interface every day without ever risking the sensitive motor.

   Principle 3 →

4. 04 Deterministic-first Intermediate · 7 min

   Before you start the expensive engine, make the most of what is already structured — like a good cook who prepares everything you can to prepare before you light the stove. The golden rule of reliability is counterintuitive: use AI as little as possible.

   The problem: each responsibility given to the LLM is a source of hallucination and a cost. Sending the model to "discover" something that a bank consultation, a business rule or an exact search already answers is to waste money and introduce risk where it did not need to exist.

   The solution: map each field of the task and ask — "Can this come from a structured source, a rule, or an exact search?" If so, it's not AI's job. What remains — unambiguous free text, inferring intention, classifying tone — is the interpretative residue. He alone justifies the cost and risk of a model call. And this residue shrinks to each version, as you discover what else can be deterministic.

   In practice, this means that Less AI on the way is at the same time less cost and more trust.

   Principle 4 →

5. 05 Rigid contracts Intermediate · 8 min

   You never blindly trusted what the browser sends to the backend — always valid on the server. A strict schema is the same form validator, now applied to the LLM output: it is unreliable input by definitionUntil I pass the doorman.

   The problem: if the template invents an attribute, hallucinates a format or returns score = 1.7 where the interval is 0–1, and this enters the system without validation, the error spreads silently — and only appears three steps later, unrecognizable.

   The solution It's shielding every border with strict contracts. Good concrete practices: prohibit the unknown (reject any field outside the scheme instead of ignoring it); put the limits on schema, not on a if lost (it is the scheme that refuses 1.7); validates types statically when the language allows; and degrade item to item — in a lot, a malformed item is marked as uncertain, does not drop the whole lot. It also includes sanitizing adverse input before the Brain.

   In practice, this means that validation fails immediately and cheaply, instead of spreading the error.

   Principle 5 →

6. 06 Open-World Intermediate · 7 min

   Imagine registering a whole new client with no bank history. The classic software operates under "closed world": what is not in the bank is fake. Intelligence systems need the opposite — the Open World: the absence of evidence is uncertainty, not denial.

   The problem: "we found no sign that the client is dissatisfied" no It's the same as "the customer is satisfied" -- it's "unknown." Treating the gap as a "false" invents a conclusion where there is no evidence: the worst category of failure, a wrong business decision made with false confidence.

   The solution It's got two faces. First, isolate the epistemic layers: evidence observed Second, make uncertainty a first-class state: what was not observed is valuable information ("cannot confirm X"), and sensor failures degrade to uncertainty, never to an invented value.

   In practice, this means that teaching the system to say "I don't know" makes it more reliable and safer.

   Principles 6 and 7 →

7. 07 FinOps of AI Advanced · 8 min

   You already master pagetion and job queues to process large volumes without overthrowing the bank, and cache Not to repeat expensive work. AI FinOps is to apply these same standards to a resource whose "miss" costs a model call, not a SELECT.

   The problem: treat token limits and credit with try/except on top of the limit rate error is fragile and amateur. A free flow turns the budget into a random variable — the same request can cost pennies or dozens of reais.

   The solution: model the budget as persistent domain status — one ledger who survives between executions, knows how much he has spent, resets in the period and refuses spending as you approach the ceiling, before the provider refuses for you. Combine with three habits: early pruning (the cheapest filter first — garbage never reaches the LLM); resumable wave processing (each wave saves progress and to clean; the next pick-up from where it left off); and a cumulative corpus with idempotent key — if you have already been processed, do not sue again.

   In practice, this means that The system gets cheaper per item as it grows.

   Principle 8 →

8. 08 BDD for AI Advanced · 8 min

   How to test a system whose central component is stochastic — which can respond differently to each execution? The answer is isolating the stochasticity in the tests: you don't test if the model is "intelligent"; you test if the system around him remains correct when the model, network or data fail.

   The problem: without objective criteria of "ready", "functioned" is a perception, not a verification — and elegant hallucinations go unnoticed. Even worse by delegating to autonomous code agents, who have no common sense to fill gaps: ambiguity given to an agent becomes a hallucination of scope.

   The solution: Write scenarios in Gherkin (Data/When/So) before code with external calls replaced by fixtures recorded — zero API deterministic and cost test. Every scenario covers three axes: Happy path, degraded mode (an API drops, breaks limit or gives timeout — the system degrades gracefully) and open-world (an expected signal is missing). Reinforce with gates: a DoR prevents a task of entering open decisions; DoD Yeah. fail-closed — if it was not possible to conclude, the blockade is recorded and stopped at a safe place.

   In practice, this means that an honest "LOKE" is the success of the process; a false "completed" is debt that wins with interest.

   Principle 9 →

9. 09 XAI Intermediate · 6 min

   No one makes an important decision because "the algorithm gave 0,674". Compare with: "priorized because it signaled recent expansion and has a history of purchase in the sector; it was not possible to confirm the budget". The number is useless and does not inspire confidence; the justification, yes.

   The problem: the "black box" is the largest corporate adoption blocker of AI. An opaque score generates user resistance, flooded with "why did the system suggest this?" in support and failure in explanatory audits.

   The solution is to exchange the number for an actionable explanation with three elements: drivers in natural language (which weighed for and against), absent signs (Open-World honesty — showing the gap increases confidence more than hiding it) and source (from which source came each signal, for the user to check). Two cares make XAI reliable: manages the explanation by deterministic rules on the same object that generated the score — never with a second call from LLM, which would rationalize; and consider hiding the number and showing only the "why now" and "what remains to be known".

   In practice, this means that an explicable and modest response wins an exact and opaque response in adoption.

   Principle 10 →

10. 10 Full project Summary · 10 min

    Everything comes together in a real case: SocialSelling, a B2B lead prioritization system where the ten principles became product. The pipeline is deterministic in five modules — M1 Search, M2 Extraction, M3 Score, M4 Ranking, M5 XAI —, and the LLM acts only in M2 and M5; M3 and M4 are pure Python.

    As the principles appear: the LLM is contained component (P1/P2) in a deterministic flow (P4); the local brain publishes snapshots and the portal never touches the engine bank (P3); strict schemas shield all border (P5) and ledgers govern requests and credits (P8); the operator sees "why now" and "what is missing", never score (P10). The absence of data becomes explicit uncertainty (P6/P7), and degraded BDD scenarios support fail-closed governance (P9).

    The final turn: when the AI goes from copilot to autonomous developer, responsibility migrates to the machine — and this requires structure. The context exits the head and enters the repository (ADRs, SDDs, DoR/DoD versioned), because undocumented context is context that does not exist.

    In practice, this means that the central discipline is to distinguish the implemented from the specified — know when no build.

    Agent-Driven Governance →

Check Your Understanding

Eight real scenarios — four over the ten principles, four over the five pillars. Do not decorate the rule; choose what you would do in production. Each answer explains why.

Laboratory

Playground: mount your architecture

Add components and see the system evaluate architecture by deterministic rules — pointing out risks and good practices.

Quick consultation

Reference and actual case

The ten principles in a sentence, a glossary of the key terms and the case study that originated This content.

Glossary

Syntactic hallucination

Aesthetically perfect but logically wrong code — appearance of correction without substance.

Interpreting residue

The fraction of the task that requires language/inference and that no structured source covers. Only he justifies spending AI.

Open-World

Absence of evidence is uncertainty, not denial. The system learns to say "I don't know."

Quota Ledger

Budget as a state of persistent domination: knows how much spent, resets in the period and refuses spending when hitting the ceiling.

XAI

Explanation by drivers in natural language + gaps + provenance, instead of opaque number.

DoR / DoD

Quality gates that close ambiguity before (Ready) and validate the result after (Done), with honest lock.

Spectrum of Autonomy

The continuum between exploration and critical mission. The correct position is the function of error cost × reversibility — a design decision, not an accident. Pilar 1 →

Mode leak

Code born on holding (disposable) that migrates to production without ever crossing the corresponding border of rigor. The most insidious operational risk.

Transition rule

Lightness is legitimate while the artifact remains at the pole of origin. When someone becomes dependent on it as a production, the promotion requires the upgrade of guarantees. Pilar 5 →

ADR

Architecture Decision Record: Versioned and immutable record of an architectural decision, its context and consequences. Memory that prevents reopening what has already been closed — and turns into injecting context for the agent.

MCP

Model Context Protocol: Open client-server protocol that standardizes agent connection to tools and data. The border where authorisation, scope and audit apply — access listed, not environment. Pilar 3 →

A2UI (layer)

The contractual boundary agent↔interface: Brain emits intention and structured data; Vitrine decides to render. Architectural pattern (not canonical specification) — see AG-UI and A2A as adjacent real protocols.

Intentional System

System whose behavior is governed by explicit architectural intention, not by the most likely exit of the model. The guarantee lives in architecture, which encapsula The probability. Maturity →

Sandbox (brakes)

The space delimited by DoR/DoD/ADR within which the agent operates at maximum capacity — because the edges are known. The restriction increases the safe speed. Pilar 2 →

Case study: SocialSelling

Your progress in this session

Calculated metrics in your browser (localStorage) — nothing is sent to the server.