Tutorial | 1byteone - Java Backend / AI Application Developer

FastAPI AI Streaming APIs with Server-Sent Events

Fri, 21 Aug 2026 00:00:00 +0000

Whiteboard: FastAPI — FastAPI AI Streaming APIs with Server-Sent Events.

Streaming improves time-to-first-byte and perceived responsiveness; it does not make model computation faster. Define event framing, completion signals, error events, and cleanup on disconnect.

Core mental model

The server emits data events and the client parses event boundaries. Do not concatenate arbitrary unescaped text into SSE; prefer JSON events with a stable type field.

Key mechanics

Use try/finally in the generator to release upstream resources. Include a request id in each event. Convert model failures into an error event and close with an explicit done signal.

Python example

import json
from fastapi.responses import StreamingResponse

async def events(prompt: str):
 try:
 async for token in provider.stream(prompt):
 yield f"data: {json.dumps({'type': 'token', 'text': token})}\n\n"
 yield "data: {\"type\":\"done\"}\n\n"
 except Exception:
 yield "data: {\"type\":\"error\",\"code\":\"upstream_failed\"}\n\n"

@app.post("/v1/chat/stream")
async def stream(req: ChatRequest):
 return StreamingResponse(events(req.message), media_type="text/event-stream")

Course focus

This article turns the whiteboard into explicit engineering boundaries: define inputs and outputs first, then decide how state, failures, and observability work. The examples use Python and focus on durable design principles rather than a particular provider version; verify APIs against the documentation for your installed dependencies.

Engineering practice

Keep business rules in the application layer instead of hiding them in untestable prompts or route handlers.
Add timeouts, bounded retries, and idempotency keys to external calls; retries are not a complete error strategy.
Record a request id, latency, input version, model/index version, and outcome without logging sensitive raw content.
Use a small fixed regression set first, then monitor quality and cost with sampled production traffic.

Common mistakes

Drawing only the happy path and omitting timeouts, empty results, rate limits, and rollback paths.
Letting one function parse input, call providers, build prompts, and persist data.
Replacing typed contracts with string conventions that can only be verified by manual integration.

Production checklist

Inputs, outputs, and error responses have explicit schemas
External dependencies have timeouts, bounded retries, rate limits, and fallbacks
Logs, metrics, and traces can be correlated to one request
Critical paths have unit tests, integration tests, and offline evaluation samples
Secrets, user content, and provider responses follow least-privilege and privacy rules

Practice

Implement the smallest loop shown on the whiteboard. Inject a timeout, an empty result, and a malformed payload, then check whether the system remains stable and diagnosable. Add one metric that proves your optimization improved quality or latency.

Hands-on exercise

Write a browser SSE client and test normal completion, upstream failure, refresh, and network disconnect. Track TTFT, full latency, and cancellation rate.

Conclusion

An AI feature becomes maintainable when every arrow on the whiteboard maps to an input, an output, and a failure strategy.

FastAPI Async and Dependency Injection: Keep the Event Loop Healthy

Fri, 21 Aug 2026 00:00:00 +0000

Whiteboard: FastAPI — FastAPI Async and Dependency Injection.

async def does not make blocking code faster. File I/O, synchronous SDKs, and CPU-heavy work can stall the event loop and slow every request.

Core mental model

Async routes are appropriate for async network I/O. Isolate synchronous dependencies explicitly, and move CPU-heavy work to a queue or process pool. Dependency injection should make lifetimes visible and replacements easy.

Key mechanics

Create shared clients in lifespan and reuse their connections. Use a semaphore to bound concurrent provider calls so your service does not overwhelm an upstream.

Python example

import asyncio
from contextlib import asynccontextmanager
from fastapi import FastAPI

limit = asyncio.Semaphore(20)

async def call_provider(client, payload):
 async with limit:
 return await client.post("/responses", json=payload, timeout=15)

@asynccontextmanager
async def lifespan(app: FastAPI):
 app.state.client = make_async_client()
 yield
 await app.state.client.aclose()

app = FastAPI(lifespan=lifespan)

Course focus

Engineering practice

Keep business rules in the application layer instead of hiding them in untestable prompts or route handlers.
Add timeouts, bounded retries, and idempotency keys to external calls; retries are not a complete error strategy.
Record a request id, latency, input version, model/index version, and outcome without logging sensitive raw content.
Use a small fixed regression set first, then monitor quality and cost with sampled production traffic.

Common mistakes

Drawing only the happy path and omitting timeouts, empty results, rate limits, and rollback paths.
Letting one function parse input, call providers, build prompts, and persist data.
Replacing typed contracts with string conventions that can only be verified by manual integration.

Production checklist

Inputs, outputs, and error responses have explicit schemas
External dependencies have timeouts, bounded retries, rate limits, and fallbacks
Logs, metrics, and traces can be correlated to one request
Critical paths have unit tests, integration tests, and offline evaluation samples
Secrets, user content, and provider responses follow least-privilege and privacy rules

Practice

Hands-on exercise

Benchmark 50 concurrent requests with a synchronous fake client and an async fake client. Add a semaphore and compare upstream error rate and mean latency.

Conclusion

An AI feature becomes maintainable when every arrow on the whiteboard maps to an input, an output, and a failure strategy.

FastAPI Project Architecture: Layering Routes and Domain Services

Fri, 21 Aug 2026 00:00:00 +0000

Whiteboard: FastAPI — FastAPI Project Architecture.

FastAPI makes it easy to start in one file—and easy to end up with an unmaintainable global script. A durable structure lets routes handle HTTP, services handle use cases, and repositories handle persistence.

Core mental model

A useful direction is router → service → repository/provider, with dependencies injected through function parameters. Domain services should not depend on Request or HTTP status codes, so they can be reused by jobs and tests.

Key mechanics

Load and validate configuration at startup. Create and close pools in the lifespan context. Map exceptions centrally to a stable error schema.

Python example

from fastapi import APIRouter, Depends
from pydantic import BaseModel

router = APIRouter(prefix="/v1/chat", tags=["chat"])

class ChatRequest(BaseModel):
 message: str

class ChatResponse(BaseModel):
 answer: str

@router.post("", response_model=ChatResponse)
async def chat(req: ChatRequest, service = Depends(get_chat_service)):
 return ChatResponse(answer=await service.answer(req.message))

Course focus

Engineering practice

Keep business rules in the application layer instead of hiding them in untestable prompts or route handlers.
Add timeouts, bounded retries, and idempotency keys to external calls; retries are not a complete error strategy.
Record a request id, latency, input version, model/index version, and outcome without logging sensitive raw content.
Use a small fixed regression set first, then monitor quality and cost with sampled production traffic.

Common mistakes

Drawing only the happy path and omitting timeouts, empty results, rate limits, and rollback paths.
Letting one function parse input, call providers, build prompts, and persist data.
Replacing typed contracts with string conventions that can only be verified by manual integration.

Production checklist

Inputs, outputs, and error responses have explicit schemas
External dependencies have timeouts, bounded retries, rate limits, and fallbacks
Logs, metrics, and traces can be correlated to one request
Critical paths have unit tests, integration tests, and offline evaluation samples
Secrets, user content, and provider responses follow least-privilege and privacy rules

Practice

Hands-on exercise

Split a model-calling route into api, services, providers, and schemas. Inject a fake provider into the service and use TestClient to verify error mapping.

Conclusion

An AI feature becomes maintainable when every arrow on the whiteboard maps to an input, an output, and a failure strategy.

FastAPI Request and Response Contracts with Pydantic

Fri, 21 Aug 2026 00:00:00 +0000

Whiteboard: FastAPI — FastAPI Request and Response Contracts with Pydantic.

AI endpoints receive untrusted client input and often relay unstable model or third-party output. Pydantic schemas create the first boundary by turning data that looks right into data that has been validated.

Core mental model

Request models validate inputs, domain models enforce business invariants, and response models define the public surface. Do not return ORM objects or raw provider JSON directly.

Key mechanics

Bound string lengths, use Literal for enumerations, and model nested structures. Parse model output before returning it; route failures through an observable 502/422 branch.

Python example

from typing import Literal
from pydantic import BaseModel, Field

class ChatRequest(BaseModel):
 message: str = Field(min_length=1, max_length=4000)
 mode: Literal["answer", "summarize"] = "answer"

class ChatResponse(BaseModel):
 request_id: str
 answer: str
 citations: list[str] = Field(default_factory=list)

Course focus

Engineering practice

Keep business rules in the application layer instead of hiding them in untestable prompts or route handlers.
Add timeouts, bounded retries, and idempotency keys to external calls; retries are not a complete error strategy.
Record a request id, latency, input version, model/index version, and outcome without logging sensitive raw content.
Use a small fixed regression set first, then monitor quality and cost with sampled production traffic.

Common mistakes

Drawing only the happy path and omitting timeouts, empty results, rate limits, and rollback paths.
Letting one function parse input, call providers, build prompts, and persist data.
Replacing typed contracts with string conventions that can only be verified by manual integration.

Production checklist

Inputs, outputs, and error responses have explicit schemas
External dependencies have timeouts, bounded retries, rate limits, and fallbacks
Logs, metrics, and traces can be correlated to one request
Critical paths have unit tests, integration tests, and offline evaluation samples
Secrets, user content, and provider responses follow least-privilege and privacy rules

Practice

Hands-on exercise

Add request_id, length limits, a mode enum, and citations to a Q&A endpoint. Submit an empty string, oversized text, unknown mode, and missing fields and verify stable client errors.

Conclusion

An AI feature becomes maintainable when every arrow on the whiteboard maps to an input, an output, and a failure strategy.

LangChain Core Architecture: Runnables, Models, and Composable Chains

Fri, 21 Aug 2026 00:00:00 +0000

Whiteboard: LangChain — LangChain Core Architecture.

LangChain is more than a wrapper around a model. Its useful abstraction is a composable runtime: once a prompt, model, and parser are treated as Runnable stages, invocation, batching, streaming, and tracing follow the same shape.

Core mental model

A typical path is input dict → ChatPromptTemplate → ChatModel → StrOutputParser. Each node owns a contract; the chain only composes them, making model swaps and isolated tests straightforward.

Key mechanics

The | operator describes data flow. Use invoke for one request, batch for bulk work, and stream for low time-to-first-token. Production code should validate at boundaries and enforce timeouts instead of swallowing exceptions.

Python example

from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI

prompt = ChatPromptTemplate.from_messages([
 ("system", "You are a concise technical assistant."),
 ("human", "Explain in three points: {question}"),
])
model = ChatOpenAI(model="gpt-4o-mini", temperature=0)
chain = prompt | model | StrOutputParser()
answer = chain.invoke({"question": "What is idempotency?"})

Course focus

Engineering practice

Keep business rules in the application layer instead of hiding them in untestable prompts or route handlers.
Add timeouts, bounded retries, and idempotency keys to external calls; retries are not a complete error strategy.
Record a request id, latency, input version, model/index version, and outcome without logging sensitive raw content.
Use a small fixed regression set first, then monitor quality and cost with sampled production traffic.

Common mistakes

Drawing only the happy path and omitting timeouts, empty results, rate limits, and rollback paths.
Letting one function parse input, call providers, build prompts, and persist data.
Replacing typed contracts with string conventions that can only be verified by manual integration.

Production checklist

Inputs, outputs, and error responses have explicit schemas
External dependencies have timeouts, bounded retries, rate limits, and fallbacks
Logs, metrics, and traces can be correlated to one request
Critical paths have unit tests, integration tests, and offline evaluation samples
Secrets, user content, and provider responses follow least-privilege and privacy rules

Practice

Hands-on exercise

Split the chain into replaceable render_prompt, call_model, and parse_output stages, and test the parser without a network call. When the model changes, tests should assert the final contract rather than provider-specific response fields.

Conclusion

An AI feature becomes maintainable when every arrow on the whiteboard maps to an input, an output, and a failure strategy.

LangChain Memory: Designing Controlled Multi-Turn State

Fri, 21 Aug 2026 00:00:00 +0000

Whiteboard: LangChain — LangChain Memory.

The challenge of multi-turn chat is not putting every message back into the prompt. It is deciding which facts to retain, for how long, and who can delete them. Memory is explicit data, not an implicit model capability.

Core mental model

Short-term memory serves the current conversation, summaries compress earlier turns, and long-term memory stores consented preferences. All three need a conversation id, tenant isolation, and retention policy.

Key mechanics

Budget tokens before deciding whether to truncate or summarize. Filter PII and deduplicate before writing long-term memory. When reading memory, include source and timestamp so stale facts do not override newer ones.

Python example

from dataclasses import dataclass
from datetime import datetime

@dataclass
class MemoryItem:
 conversation_id: str
 text: str
 source: str
 created_at: datetime

def build_context(history: list[MemoryItem], max_chars: int = 6000) -> str:
 selected, size = [], 0
 for item in reversed(history):
 if size + len(item.text) > max_chars: break
 selected.append(f"[{item.source}] {item.text}")
 size += len(item.text)
 return "\n".join(reversed(selected))

Course focus

Engineering practice

Keep business rules in the application layer instead of hiding them in untestable prompts or route handlers.
Add timeouts, bounded retries, and idempotency keys to external calls; retries are not a complete error strategy.
Record a request id, latency, input version, model/index version, and outcome without logging sensitive raw content.
Use a small fixed regression set first, then monitor quality and cost with sampled production traffic.

Common mistakes

Drawing only the happy path and omitting timeouts, empty results, rate limits, and rollback paths.
Letting one function parse input, call providers, build prompts, and persist data.
Replacing typed contracts with string conventions that can only be verified by manual integration.

Production checklist

Inputs, outputs, and error responses have explicit schemas
External dependencies have timeouts, bounded retries, rate limits, and fallbacks
Logs, metrics, and traces can be correlated to one request
Critical paths have unit tests, integration tests, and offline evaluation samples
Secrets, user content, and provider responses follow least-privilege and privacy rules

Practice

Hands-on exercise

Implement three context layers—recent turns, a conversation summary, and user preferences—and record which message ids each summary covers. When deleting a conversation, verify caches, vector stores, and audit copies are all removed.

Conclusion

An AI feature becomes maintainable when every arrow on the whiteboard maps to an input, an output, and a failure strategy.

LangChain Prompt Chains: Treat Prompts as Maintainable Programs

Fri, 21 Aug 2026 00:00:00 +0000

Whiteboard: LangChain — LangChain Prompt Chains.

A prompt is not an untracked block of text buried in code. It is a program component that needs versioning, input validation, and regression tests. This article builds a reliable template, structured input, model, and parser flow.

Core mental model

A stable Prompt Chain separates system rules, the human task, and conversation context. Variable names should carry semantics; avoid letting a generic text value change meaning across stages.

Key mechanics

Render and inspect the prompt before calling the model. Budget long context and delimit user text; never concatenate user-controlled content into system instructions.

Python example

from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

prompt = ChatPromptTemplate.from_messages([
 ("system", "Answer only from context; say when it is insufficient."),
 ("human", "<context>\n{context}\n</context>\nQuestion: {question}"),
])
chain = prompt | model | StrOutputParser()
print(chain.invoke({"context": "An idempotent request does not create extra side effects when repeated.", "question": "What problem does idempotency solve?"}))

Course focus

Engineering practice

Keep business rules in the application layer instead of hiding them in untestable prompts or route handlers.
Add timeouts, bounded retries, and idempotency keys to external calls; retries are not a complete error strategy.
Record a request id, latency, input version, model/index version, and outcome without logging sensitive raw content.
Use a small fixed regression set first, then monitor quality and cost with sampled production traffic.

Common mistakes

Drawing only the happy path and omitting timeouts, empty results, rate limits, and rollback paths.
Letting one function parse input, call providers, build prompts, and persist data.
Replacing typed contracts with string conventions that can only be verified by manual integration.

Production checklist

Inputs, outputs, and error responses have explicit schemas
External dependencies have timeouts, bounded retries, rate limits, and fallbacks
Logs, metrics, and traces can be correlated to one request
Critical paths have unit tests, integration tests, and offline evaluation samples
Secrets, user content, and provider responses follow least-privilege and privacy rules

Practice

Hands-on exercise

Add a prompt_version, keep 20 fixed questions as a regression set, and compare factuality, abstention rate, and token usage before and after each prompt change.

Conclusion

An AI feature becomes maintainable when every arrow on the whiteboard maps to an input, an output, and a failure strategy.

LangChain Tool-Calling Agents: Separate Decisions from Execution

Fri, 21 Aug 2026 00:00:00 +0000

Whiteboard: LangChain — LangChain Tool-Calling Agents.

An agent should not give a model direct access to your system. The model proposes a structured tool intent; the application validates and executes it. The central boundary is: the model decides, the application executes.

Core mental model

The loop is Think → Call → Observe, while the host application controls iteration limits, tool allowlists, parameter validation, and permissions. Good descriptions improve selection but are not security policies.

Key mechanics

Tools should return machine-readable success or failure results; do not expose raw stack traces to the model or user. Require explicit confirmation for writes and emit an audit event for every call.

Python example

from langchain_core.tools import tool

@tool
def get_weather(city: str) -> dict:
 """Return current weather for an allowed city."""
 if city not in {"Shanghai", "Beijing"}:
 return {"ok": False, "error": "city_not_allowed"}
 return {"ok": True, "city": city, "celsius": 26}

llm_with_tools = model.bind_tools([get_weather])
message = llm_with_tools.invoke("Is Shanghai good for a run today?")
if message.tool_calls:
 result = get_weather.invoke(message.tool_calls[0]["args"])

Course focus

Engineering practice

Keep business rules in the application layer instead of hiding them in untestable prompts or route handlers.
Add timeouts, bounded retries, and idempotency keys to external calls; retries are not a complete error strategy.
Record a request id, latency, input version, model/index version, and outcome without logging sensitive raw content.
Use a small fixed regression set first, then monitor quality and cost with sampled production traffic.

Common mistakes

Drawing only the happy path and omitting timeouts, empty results, rate limits, and rollback paths.
Letting one function parse input, call providers, build prompts, and persist data.
Replacing typed contracts with string conventions that can only be verified by manual integration.

Production checklist

Inputs, outputs, and error responses have explicit schemas
External dependencies have timeouts, bounded retries, rate limits, and fallbacks
Logs, metrics, and traces can be correlated to one request
Critical paths have unit tests, integration tests, and offline evaluation samples
Secrets, user content, and provider responses follow least-privilege and privacy rules

Practice

Hands-on exercise

Add one read-only search tool and one side-effecting refund tool. Auto-run the first, return requires_confirmation for the second, and test that the agent cannot bypass confirmation.

Conclusion

An AI feature becomes maintainable when every arrow on the whiteboard maps to an input, an output, and a failure strategy.

OpenAI API Fundamentals: Requests, Messages, Parameters, and Reliability

Fri, 21 Aug 2026 00:00:00 +0000

Whiteboard: OpenAI — OpenAI API Fundamentals.

The core of model API integration is not memorizing an endpoint. Treat the network call as an unreliable dependency and design request contracts, timeouts, error classes, and usage tracking from day one.

Core mental model

A request contains system/developer rules, user input, and optional tools. The model output is a candidate result; the application must still validate, filter, and persist it.

Key mechanics

Separate 4xx input/auth errors, 429 rate limits, 5xx upstream failures, and local timeouts. Retry only transient classes with jittered exponential backoff and a total budget.

Python example

import asyncio, random

async def call_with_retry(client, request, attempts=3):
 for n in range(attempts):
 try:
 return await client.responses.create(**request, timeout=20)
 except (TimeoutError, RateLimitError):
 if n == attempts - 1: raise
 await asyncio.sleep((2 ** n) + random.random())

Course focus

Engineering practice

Keep business rules in the application layer instead of hiding them in untestable prompts or route handlers.
Add timeouts, bounded retries, and idempotency keys to external calls; retries are not a complete error strategy.
Record a request id, latency, input version, model/index version, and outcome without logging sensitive raw content.
Use a small fixed regression set first, then monitor quality and cost with sampled production traffic.

Common mistakes

Drawing only the happy path and omitting timeouts, empty results, rate limits, and rollback paths.
Letting one function parse input, call providers, build prompts, and persist data.
Replacing typed contracts with string conventions that can only be verified by manual integration.

Production checklist

Inputs, outputs, and error responses have explicit schemas
External dependencies have timeouts, bounded retries, rate limits, and fallbacks
Logs, metrics, and traces can be correlated to one request
Critical paths have unit tests, integration tests, and offline evaluation samples
Secrets, user content, and provider responses follow least-privilege and privacy rules

Practice

Hands-on exercise

Add request id, latency, input/output tokens, and error class logging. Use a fake client that emits 429 and 400 to verify only 429 is retried.

Conclusion

An AI feature becomes maintainable when every arrow on the whiteboard maps to an input, an output, and a failure strategy.

OpenAI Multimodal AI: Working with Text, Images, and Documents

Fri, 21 Aug 2026 00:00:00 +0000

Whiteboard: OpenAI — OpenAI Multimodal AI.

The hard part of multimodal applications is input governance, not uploading a file. Each media type needs type checks, size limits, safety screening, authorization, and traceable preprocessing.

Core mental model

The flow is Input → Normalize → Multimodal Model → Structured Output → Application. Images may need resizing, PDFs may need OCR/layout parsing, and audio may need transcription with timestamps.

Key mechanics

Decouple file storage from model requests: create a short-lived object reference, scan it, and send only the minimum resolution or pages needed. Store modality, preprocessing version, and evidence regions.

Python example

from pydantic import BaseModel, Field

class ImageInsight(BaseModel):
 objects: list[str] = Field(default_factory=list, max_length=20)
 summary: str = Field(max_length=1000)
 confidence: float = Field(ge=0, le=1)

def validate_upload(content_type: str, size: int) -> None:
 if content_type not in {"image/png", "image/jpeg", "application/pdf"}:
 raise ValueError("unsupported_media_type")
 if size > 10 * 1024 * 1024:
 raise ValueError("file_too_large")

Course focus

Engineering practice

Keep business rules in the application layer instead of hiding them in untestable prompts or route handlers.
Add timeouts, bounded retries, and idempotency keys to external calls; retries are not a complete error strategy.
Record a request id, latency, input version, model/index version, and outcome without logging sensitive raw content.
Use a small fixed regression set first, then monitor quality and cost with sampled production traffic.

Common mistakes

Drawing only the happy path and omitting timeouts, empty results, rate limits, and rollback paths.
Letting one function parse input, call providers, build prompts, and persist data.
Replacing typed contracts with string conventions that can only be verified by manual integration.

Production checklist

Inputs, outputs, and error responses have explicit schemas
External dependencies have timeouts, bounded retries, rate limits, and fallbacks
Logs, metrics, and traces can be correlated to one request
Critical paths have unit tests, integration tests, and offline evaluation samples
Secrets, user content, and provider responses follow least-privilege and privacy rules

Practice

Hands-on exercise

Build an invoice-image-to-JSON experiment. Test a clear image, rotated image, low-resolution image, and oversized PDF; record field accuracy, latency, and cost.

Conclusion

An AI feature becomes maintainable when every arrow on the whiteboard maps to an input, an output, and a failure strategy.

OpenAI Structured Outputs: Make Model Results Verifiable

Fri, 21 Aug 2026 00:00:00 +0000

Whiteboard: OpenAI — OpenAI Structured Outputs.

Free text is useful for display; structured output is useful for programs. Structured Outputs do not make a model infallible—they make success, refusal, and failure distinguishable to code.

Core mental model

A schema constrains types, required fields, and enums but cannot guarantee factual correctness. Business validation must still check ranges, permissions, and citation existence.

Key mechanics

Separate transport, schema, and domain validation. When the model refuses or returns an incomplete result, do not silently fill defaults and disguise uncertainty as fact.

Python example

from pydantic import BaseModel, Field

class Incident(BaseModel):
 severity: str = Field(pattern="^(low|medium|high)$")
 summary: str = Field(min_length=1, max_length=500)
 actions: list[str] = Field(min_length=1, max_length=5)

response = client.responses.parse(model="gpt-4o-mini", input="Turn this incident log into a structured summary", text_format=Incident)
if response.output_parsed is None: raise ValueError("model_refusal_or_parse_failure")

Course focus

Engineering practice

Keep business rules in the application layer instead of hiding them in untestable prompts or route handlers.
Add timeouts, bounded retries, and idempotency keys to external calls; retries are not a complete error strategy.
Record a request id, latency, input version, model/index version, and outcome without logging sensitive raw content.
Use a small fixed regression set first, then monitor quality and cost with sampled production traffic.

Common mistakes

Drawing only the happy path and omitting timeouts, empty results, rate limits, and rollback paths.
Letting one function parse input, call providers, build prompts, and persist data.
Replacing typed contracts with string conventions that can only be verified by manual integration.

Production checklist

Inputs, outputs, and error responses have explicit schemas
External dependencies have timeouts, bounded retries, rate limits, and fallbacks
Logs, metrics, and traces can be correlated to one request
Critical paths have unit tests, integration tests, and offline evaluation samples
Secrets, user content, and provider responses follow least-privilege and privacy rules

Practice

Hands-on exercise

Add a schema version and backward-compatible fields. Prepare normal, refusal, missing-field, and out-of-range fixtures and verify the API never returns half-valid JSON as success.

Conclusion

An AI feature becomes maintainable when every arrow on the whiteboard maps to an input, an output, and a failure strategy.

OpenAI Tool Calling: Schemas, Execution Loops, and Safety Boundaries

Fri, 21 Aug 2026 00:00:00 +0000

Whiteboard: OpenAI — OpenAI Tool Calling.

Tool Calling lets a model emit a function name and arguments; it does not execute the function. The application must check allowlists, arguments, and authorization before returning a tool result.

Core mental model

The loop is request → tool_call → validate → execute → tool_result → request. Bound every round, and never let a final answer bypass business authorization.

Key mechanics

A schema describes how to call; a policy decides whether the call is allowed. Read operations may be automatic, while writes need confirmation, idempotency, and audit logs.

Python example

def execute_tool(call, user):
 if call.name not in TOOL_ALLOWLIST:
 return {"ok": False, "error": "tool_not_allowed"}
 args = validate_args(call.name, call.arguments)
 authorize(user, call.name, args)
 if is_side_effecting(call.name) and not user.confirmed:
 return {"ok": False, "error": "confirmation_required"}
 return TOOL_REGISTRY[call.name](**args)

Course focus

Engineering practice

Keep business rules in the application layer instead of hiding them in untestable prompts or route handlers.
Add timeouts, bounded retries, and idempotency keys to external calls; retries are not a complete error strategy.
Record a request id, latency, input version, model/index version, and outcome without logging sensitive raw content.
Use a small fixed regression set first, then monitor quality and cost with sampled production traffic.

Common mistakes

Drawing only the happy path and omitting timeouts, empty results, rate limits, and rollback paths.
Letting one function parse input, call providers, build prompts, and persist data.
Replacing typed contracts with string conventions that can only be verified by manual integration.

Production checklist

Inputs, outputs, and error responses have explicit schemas
External dependencies have timeouts, bounded retries, rate limits, and fallbacks
Logs, metrics, and traces can be correlated to one request
Critical paths have unit tests, integration tests, and offline evaluation samples
Secrets, user content, and provider responses follow least-privilege and privacy rules

Practice

Hands-on exercise

Implement weather lookup and refund request tools. Let weather run automatically, but require confirmation, an idempotency key, and an audit log for refunds.

Conclusion

An AI feature becomes maintainable when every arrow on the whiteboard maps to an input, an output, and a failure strategy.

Optimizing RAG Retrievers: Top-K, Hybrid Search, and Reranking

Fri, 21 Aug 2026 00:00:00 +0000

Whiteboard: RAG — Optimizing RAG Retrievers.

The goal of retrieval optimization is not to retrieve as much as possible. It is to rank supporting evidence first within a context and latency budget.

Core mental model

Keyword search excels at exact terms while vector search captures semantics. Hybrid retrieval merges candidates, then a reranker scores the query-document pair.

Key mechanics

Tune chunk size, overlap, K, thresholds, and reranking on an offline set. Higher recall can add noise; evaluate nDCG, answer support rate, and end-to-end latency together.

Python example

def hybrid_retrieve(query: str, k: int = 20):
 dense = vector_store.search(query, k=k)
 lexical = bm25.search(query, k=k)
 candidates = deduplicate(dense + lexical)
 ranked = reranker.rank(query, candidates)
 return [item for item in ranked if item.score >= 0.35][:5]

Course focus

Engineering practice

Keep business rules in the application layer instead of hiding them in untestable prompts or route handlers.
Add timeouts, bounded retries, and idempotency keys to external calls; retries are not a complete error strategy.
Record a request id, latency, input version, model/index version, and outcome without logging sensitive raw content.
Use a small fixed regression set first, then monitor quality and cost with sampled production traffic.

Common mistakes

Drawing only the happy path and omitting timeouts, empty results, rate limits, and rollback paths.
Letting one function parse input, call providers, build prompts, and persist data.
Replacing typed contracts with string conventions that can only be verified by manual integration.

Production checklist

Inputs, outputs, and error responses have explicit schemas
External dependencies have timeouts, bounded retries, rate limits, and fallbacks
Logs, metrics, and traces can be correlated to one request
Critical paths have unit tests, integration tests, and offline evaluation samples
Secrets, user content, and provider responses follow least-privilege and privacy rules

Practice

Hands-on exercise

Build queries with abbreviations, numbers, and paraphrases. Compare vector-only, BM25-only, hybrid, and reranked variants with Recall@K and latency curves.

Conclusion

An AI feature becomes maintainable when every arrow on the whiteboard maps to an input, an output, and a failure strategy.

Production RAG Architecture: Permissions, Versions, and Observability

Fri, 21 Aug 2026 00:00:00 +0000

Whiteboard: RAG — Production RAG Architecture.

The gap between a RAG demo and production is mostly boundary conditions: who can see a document, how indexes update, how answers cite evidence, and what happens when an upstream is unavailable.

Core mental model

Separate ingestion, indexing, query serving, and evaluation planes. Online traffic reads only the active index while new versions build in the background and switch atomically.

Key mechanics

Enforce permissions during retrieval. Cache keys should include tenant, a permission digest, query-normalization version, and index version. Deletions must reach every replica.

Python example

from dataclasses import dataclass

@dataclass
class QueryContext:
 tenant_id: str
 allowed_collections: set[str]
 index_version: str

def cache_key(query: str, ctx: QueryContext) -> str:
 scopes = ",".join(sorted(ctx.allowed_collections))
 return f"rag:v2:{ctx.tenant_id}:{ctx.index_version}:{scopes}:{normalize(query)}"

Course focus

Engineering practice

Keep business rules in the application layer instead of hiding them in untestable prompts or route handlers.
Add timeouts, bounded retries, and idempotency keys to external calls; retries are not a complete error strategy.
Record a request id, latency, input version, model/index version, and outcome without logging sensitive raw content.
Use a small fixed regression set first, then monitor quality and cost with sampled production traffic.

Common mistakes

Drawing only the happy path and omitting timeouts, empty results, rate limits, and rollback paths.
Letting one function parse input, call providers, build prompts, and persist data.
Replacing typed contracts with string conventions that can only be verified by manual integration.

Production checklist

Inputs, outputs, and error responses have explicit schemas
External dependencies have timeouts, bounded retries, rate limits, and fallbacks
Logs, metrics, and traces can be correlated to one request
Critical paths have unit tests, integration tests, and offline evaluation samples
Secrets, user content, and provider responses follow least-privilege and privacy rules

Practice

Hands-on exercise

Design active and candidate indexes. Simulate a failed publish and a document deletion, verify traffic never receives unauthorized stale data, and persist evidence ids for every answer.

Conclusion

An AI feature becomes maintainable when every arrow on the whiteboard maps to an input, an output, and a failure strategy.

RAG Embeddings and Vector Databases: The Engineering Behind Similarity

Fri, 21 Aug 2026 00:00:00 +0000

Whiteboard: RAG — RAG Embeddings and Vector Databases.

A vector database does not understand your business automatically. It efficiently finds neighbors in a chosen vector space. The engineering questions are embedding versions, distance metrics, filters, and consistency.

Core mental model

Documents and queries need compatible embedding models and preprocessing. Index records should include embedding_model, dimensions, and corpus_version for rebuilds and rollback.

Key mechanics

Apply metadata filters before or as part of vector search so different tenants, languages, and permission scopes never share the candidate set.

Python example

from uuid import uuid4

record = {
 "id": str(uuid4()),
 "text": "A refund request needs an order id and a reason.",
 "vector": embed("A refund request needs an order id and a reason."),
 "metadata": {"tenant_id": "acme", "language": "en", "embedding_model": "text-embedding-3-small", "corpus_version": "2026-08-21"},
}
# Similarity is never an authorization check.

Course focus

Engineering practice

Keep business rules in the application layer instead of hiding them in untestable prompts or route handlers.
Add timeouts, bounded retries, and idempotency keys to external calls; retries are not a complete error strategy.
Record a request id, latency, input version, model/index version, and outcome without logging sensitive raw content.
Use a small fixed regression set first, then monitor quality and cost with sampled production traffic.

Common mistakes

Drawing only the happy path and omitting timeouts, empty results, rate limits, and rollback paths.
Letting one function parse input, call providers, build prompts, and persist data.
Replacing typed contracts with string conventions that can only be verified by manual integration.

Production checklist

Inputs, outputs, and error responses have explicit schemas
External dependencies have timeouts, bounded retries, rate limits, and fallbacks
Logs, metrics, and traces can be correlated to one request
Critical paths have unit tests, integration tests, and offline evaluation samples
Secrets, user content, and provider responses follow least-privilege and privacy rules

Practice

Hands-on exercise

Build two embedding versions from the same corpus. Record dimensions, index size, Top-K overlap, and Recall@K before deciding whether to switch.

Conclusion

An AI feature becomes maintainable when every arrow on the whiteboard maps to an input, an output, and a failure strategy.

The RAG Basics: From Documents to Cited Answers

Fri, 21 Aug 2026 00:00:00 +0000

Whiteboard: RAG — The RAG Basics.

RAG is not simply pasting a few passages into a prompt. It is a knowledge pipeline whose quality depends on parsing, chunking, recall, prompting, and answer validation.

Core mental model

The offline path is Load → Clean → Chunk → Embed → Index; the online path is Query → Retrieve → Rerank/Filter → Generate → Cite. Version the boundary between them.

Key mechanics

Store source, page, section, and a content hash with every chunk. Pass only context above a relevance threshold and require traceable citations.

Python example

from dataclasses import dataclass

@dataclass
class Chunk:
 text: str
 source: str
 page: int
 chunk_id: str

def make_context(chunks: list[Chunk]) -> str:
 return "\n\n".join(f"[{c.chunk_id}] {c.text} (source={c.source}, page={c.page})" for c in chunks)

Course focus

Engineering practice

Keep business rules in the application layer instead of hiding them in untestable prompts or route handlers.
Add timeouts, bounded retries, and idempotency keys to external calls; retries are not a complete error strategy.
Record a request id, latency, input version, model/index version, and outcome without logging sensitive raw content.
Use a small fixed regression set first, then monitor quality and cost with sampled production traffic.

Common mistakes

Drawing only the happy path and omitting timeouts, empty results, rate limits, and rollback paths.
Letting one function parse input, call providers, build prompts, and persist data.
Replacing typed contracts with string conventions that can only be verified by manual integration.

Production checklist

Inputs, outputs, and error responses have explicit schemas
External dependencies have timeouts, bounded retries, rate limits, and fallbacks
Logs, metrics, and traces can be correlated to one request
Critical paths have unit tests, integration tests, and offline evaluation samples
Secrets, user content, and provider responses follow least-privilege and privacy rules

Practice

Hands-on exercise

Create 30 questions with reference answers and sources. Measure retrieval hit rate, citation correctness, and abstention accuracy—not just whether the answer sounds plausible.

Conclusion

An AI feature becomes maintainable when every arrow on the whiteboard maps to an input, an output, and a failure strategy.

Building AI Agents with LangChain: Tool Integration and Multi-Turn Conversations

Fri, 10 Jul 2026 00:00:00 +0000

AI agents are revolutionizing how we build intelligent applications. Unlike simple chatbots, agents can use tools, maintain context, and make decisions. This guide covers building production-ready agents with LangChain.

Above: LangChain Agent architecture — User Input → Reasoning Loop → Tool Calling → Multi-turn Conversation

What are AI Agents?

Agents combine LLMs with tools and reasoning capabilities:

User Input → Agent (Reasoning) → Tool Selection → Tool Execution → Response

Key characteristics:

Tool Usage - Can interact with external systems
Reasoning - Decides which tools to use and when
Memory - Maintains context across interactions
Autonomy - Can chain multiple actions together

LangChain Agent Framework

LangChain provides a powerful framework for building agents:

from langchain.agents import create_openai_tools_agent
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

# Initialize LLM
llm = ChatOpenAI(model="gpt-4", temperature=0)

# Define prompt
prompt = ChatPromptTemplate.from_messages([
 ("system", "You are a helpful assistant with access to tools."),
 ("human", "{input}"),
 ("placeholder", "{agent_scratchpad}")
])

# Create agent
agent = create_openai_tools_agent(llm, tools, prompt)

Custom Tool Development

Build tools specific to your use case:

from langchain_core.tools import tool
from typing import Optional

@tool
def search_knowledge_base(query: str) -> str:
 """Search the private knowledge base for information."""
 # Implementation here
 results = vector_store.similarity_search(query, k=3)
 return "\n".join([doc.page_content for doc in results])

@tool
def get_product_info(product_id: str) -> str:
 """Get detailed product information by ID."""
 # Database query here
 product = db.get_product(product_id)
 return f"Product: {product.name}, Price: {product.price}"

# Register tools
tools = [search_knowledge_base, get_product_info]

Tool Best Practices

Clear Descriptions - Help the agent understand when to use each tool
Error Handling - Gracefully handle tool failures
Input Validation - Validate inputs before processing
Rate Limiting - Prevent abuse of external APIs

Memory Management

Implement conversation memory for context persistence:

from langchain.memory import ConversationBufferMemory
from langchain.chains import ConversationChain

# Initialize memory
memory = ConversationBufferMemory(return_messages=True)

# Create conversation chain
conversation = ConversationChain(
 llm=llm,
 memory=memory,
 verbose=True
)

# Use in agent
agent = create_openai_tools_agent(
 llm, tools, prompt,
 memory=memory
)

Memory Types

Type	Use Case	Trade-offs
Buffer	Simple conversations	Limited context
Summary	Long conversations	Information loss
Vector	Semantic search	Storage overhead
Entity	Entity tracking	Complexity

Multi-turn Conversations

Handle complex conversation flows:

from langchain.agents import AgentExecutor

# Create agent executor
agent_executor = AgentExecutor(
 agent=agent,
 tools=tools,
 verbose=True,
 max_iterations=10, # Prevent infinite loops
 handle_parsing_errors=True
)

# Conversation with context
def chat(user_input: str, conversation_id: str):
 # Load conversation history
 history = load_conversation_history(conversation_id)

 # Run agent
 result = agent_executor.invoke({
 "input": user_input,
 "chat_history": history
 })

 # Save to history
 save_conversation_history(conversation_id, user_input, result["output"])

 return result["output"]

Production Deployment

1. FastAPI Integration

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class ChatRequest(BaseModel):
 message: str
 conversation_id: str

class ChatResponse(BaseModel):
 response: str
 conversation_id: str

@app.post("/chat", response_model=ChatResponse)
async def chat_endpoint(request: ChatRequest):
 try:
 response = chat(request.message, request.conversation_id)
 return ChatResponse(
 response=response,
 conversation_id=request.conversation_id
 )
 except Exception as e:
 raise HTTPException(status_code=500, detail=str(e))

2. Streaming Responses

from fastapi.responses import StreamingResponse

@app.post("/chat/stream")
async def chat_stream(request: ChatRequest):
 async def generate():
 async for event in agent_executor.astream_events(
 {"input": request.message},
 version="v1"
 ):
 if event["event"] == "on_chat_model_stream":
 content = event["data"]["chunk"].content
 if content:
 yield f"data: {content}\n\n"
 yield "data: [DONE]\n\n"

 return StreamingResponse(generate(), media_type="text/event-stream")

3. Error Handling

@app.middleware("http")
async def error_handler(request, call_next):
 try:
 response = await call_next(request)
 return response
 except Exception as e:
 logger.error(f"Agent error: {e}")
 return JSONResponse(
 status_code=500,
 content={"error": "Internal server error"}
 )

Real-World Example: Agricultural Q&A Agent

Here’s how I built an agricultural knowledge base agent:

from langchain.agents import create_openai_tools_agent
from langchain.tools import Tool

# Define agricultural tools
tools = [
 Tool(
 name="SearchKnowledgeBase",
 func=search_agricultural_knowledge,
 description="Search private agricultural manuals for crop diseases, treatments, and best practices"
 ),
 Tool(
 name="GeneralAgriculturalKnowledge",
 func=get_general_knowledge,
 description="Get general agricultural information when private knowledge base doesn't have the answer"
 )
]

# System prompt emphasizing private data priority
system_prompt = """You are an agricultural expert assistant.

IMPORTANT: Always search the private knowledge base FIRST. Only use general knowledge if the private search returns no relevant results.

When answering:
1. Cite the source document when possible
2. Be specific about crop names, disease symptoms, and treatments
3. If unsure, say "I recommend consulting a local agricultural expert"
"""

Conclusion

Building AI agents requires:

Tool Design - Clear, well-documented tools
Memory Management - Appropriate memory strategy for your use case
Error Handling - Graceful failure management
User Experience - Streaming and clear feedback

The complete agricultural agent code is available on .

Questions? Reach out on or email me at !

Building a RAG Pipeline with LangChain: From Document Processing to Vector Search

Mon, 15 Jun 2026 00:00:00 +0000

Retrieval-Augmented Generation (RAG) has become the standard approach for building AI applications that need to access specific knowledge bases. This guide walks through building a complete RAG pipeline from scratch using LangChain.

Above: Production RAG Pipeline — Document Ingestion → Embedding → Retrieval → Augmented Generation → Output

What is RAG?

RAG combines the power of large language models with external knowledge retrieval:

User Query → Retrieval → Context + Query → LLM → Answer

This approach solves the core problem of LLMs: they can only answer based on their training data. RAG allows them to access up-to-date, domain-specific, or private information.

Document Processing

The first step is preparing your documents for retrieval:

from langchain.document_loaders import PyPDFLoader
from langchain.text_splitter import TokenTextSplitter

# Load documents
loader = PyPDFLoader("knowledge_base.pdf")
documents = loader.load()

# Split into chunks
text_splitter = TokenTextSplitter(
 chunk_size=500,
 chunk_overlap=50,
 encoding_name="cl100k_base" # OpenAI tokenizer
)

chunks = text_splitter.split_documents(documents)

Key Considerations

Chunk Size - Balance between context and retrieval accuracy
Overlap - Prevent important information from being split across chunks
Metadata - Preserve source information for attribution

Vector Storage

Store embeddings for efficient similarity search:

from langchain.embeddings import OpenAIEmbeddings
from langchain.vectorstores import Redis

# Initialize embeddings
embeddings = OpenAIEmbeddings()

# Create vector store
vector_store = Redis.from_documents(
 documents=chunks,
 embedding=embeddings,
 redis_url="redis://localhost:6379",
 index_name="knowledge_base"
)

Choosing a Vector Store

Store	Performance	Features	Best For
Redis	High	Real-time updates	Production
Pinecone	High	Managed service	Enterprise
FAISS	Medium	Local, free	Development
Chroma	Medium	Simple setup	Prototyping

Retrieval Strategies

Implement smart retrieval with LangChain:

from langchain.retrievers import ContextualCompressionRetriever
from langchain.retrievers.document_compressors import LLMChainExtractor

# Basic similarity search
retriever = vector_store.as_retriever(
 search_type="similarity",
 search_kwargs={"k": 5}
)

# Advanced: Contextual compression
compressor = LLMChainExtractor.from_llm(llm)
compression_retriever = ContextualCompressionRetriever(
 base_compressor=compressor,
 base_retriever=retriever
)

Hallucination Prevention

Critical for production RAG systems:

from langchain.prompts import ChatPromptTemplate

system_prompt = """You are an agricultural expert. Answer questions based ONLY on the provided context. If the context doesn't contain enough information, say "I don't have enough information to answer this question."

Context: {context}
"""

prompt = ChatPromptTemplate.from_messages([
 ("system", system_prompt),
 ("human", "{input}")
])

Three-Layer Prevention

Retrieval Filtering - Only pass high-relevance documents
Prompt Engineering - Force model to cite sources
Output Validation - Verify responses against source data

Streaming Interface

Implement real-time responses with FastAPI:

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import asyncio

app = FastAPI()

@app.post("/chat")
async def chat(query: str):
 async def generate():
 async for chunk in chain.astream({"input": query}):
 yield f"data: {chunk.content}\n\n"
 await asyncio.sleep(0.01) # Simulate typing
 yield "data: [DONE]\n\n"

 return StreamingResponse(
 generate(),
 media_type="text/event-stream"
 )

Production Considerations

1. Error Handling

try:
 response = await chain.ainvoke({"input": query})
except Exception as e:
 logger.error(f"RAG error: {e}")
 return {"error": "Failed to generate response"}

2. Caching

from langchain.cache import RedisCache

cache = RedisCache(redis_url="redis://localhost:6379")
llm = OpenAI(cache=cache)

3. Monitoring

Track key metrics:

Retrieval accuracy
Response latency
User satisfaction
Hallucination rate

Conclusion

Building a production RAG system requires attention to:

Document Quality - Good preprocessing is crucial
Retrieval Strategy - Balance precision and recall
Hallucination Prevention - Multi-layered approach
User Experience - Streaming and error handling

The complete code is available on .

Questions? Reach out on or email me at !