Python | 1byteone - Java Backend / AI Application Developer

AI Engineering with Python

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

Whiteboard note: the goal is not to memorize boxes, but to connect each arrow to a request, a contract, and an operational signal.

Start with a real scenario

Use this situation as the mental model: A support copilot answers only from authorized policy passages and returns a review state when evidence is weak.. A useful backend diagram answers four questions: where does input enter, who owns state, which boundary can fail, and how do we know the system is healthy? The flow is Application → Prompt / RAG / Tool → Model → Validated Result.

Deconstructing the architecture

Contract: define input, output, and error shape before adding implementation detail.
Mechanism: FastAPI → typed request / response; Retriever → evidence + ACL filter. This is the part that determines latency, throughput, and testability.
State and resources: Model call → timeout + retry budget; Tool → allowlist + argument validation. Explain creation, ownership, cleanup, and recovery.
Failure path: Structured output → schema parse; combine it with Trace → prompt version + cost + quality when choosing a fallback, retry, or rollback.

A small implementation boundary

The following sketch is intentionally small. It shows where a production implementation should place validation and ownership rather than pretending that a happy path is enough.

request → bounded resource → validated boundary → observable result

Keep external systems behind an adapter, repository, client, or gateway. The domain layer should depend on a stable contract so tests can use fakes and incidents can be isolated to one boundary.

Engineering decisions for the scenario

Protect dependencies first. Pools, queues, semaphores, caches, and worker counts need explicit limits. An unbounded queue only hides overload.
Preserve correctness. Use an idempotency key, transaction boundary, lock, version check, or schema validation where retries or concurrency can duplicate work.
Optimize with evidence. Use traces, slow-query data, GC pauses, queue depth, or p99 latency before choosing a cache, index, batch size, or concurrency setting.
Make recovery testable. Timeout, retry, rate limit, circuit breaking, rollback, and alerting should be exercised in a drill.

Common mistakes

Drawing only the happy path while omitting timeout, empty data, rejection, rollback, or replica lag.
Treating framework defaults as business contracts and discovering their limits after an upgrade.
Scaling machines before measuring pool exhaustion, lock contention, slow SQL, allocation, or event-loop blocking.
Treating logs as the only observability tool; metrics, traces, sampling, and redaction are also required.

Production checklist

Input, output, and error responses have explicit schemas
Dependencies have timeout, retry budgets, rate limits, and fallback behavior
Pools and queues expose capacity, waiting, and rejected-work metrics
Important state has idempotency, transaction, or recovery semantics
Logs, metrics, and traces share a request or correlation ID
Regression tests, load tests, and failure drills use production-like data

Summary

You understand this whiteboard when you can start from one request, explain every arrow’s contract, state how each risk is handled, and name the signal that would tell you to change the design.

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

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

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 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.

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.

Python asyncio & Concurrency

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

Whiteboard note: the goal is not to memorize boxes, but to connect each arrow to a request, a contract, and an operational signal.

Start with a real scenario

Use this situation as the mental model: A profile page fans out to several services while a semaphore protects the slowest dependency.. A useful backend diagram answers four questions: where does input enter, who owns state, which boundary can fail, and how do we know the system is healthy? The flow is Coroutine → Event Loop → Await I/O → Gather Results.

Deconstructing the architecture

Contract: define input, output, and error shape before adding implementation detail.
Mechanism: async def → coroutine object; create_task → scheduled work. This is the part that determines latency, throughput, and testability.
State and resources: await → yield while I/O is pending; gather / TaskGroup → coordinate tasks. Explain creation, ownership, cleanup, and recovery.
Failure path: Semaphore → bound downstream concurrency; combine it with Cancellation + timeout → cleanup path when choosing a fallback, retry, or rollback.

A small implementation boundary

The following sketch is intentionally small. It shows where a production implementation should place validation and ownership rather than pretending that a happy path is enough.

request → bounded resource → validated boundary → observable result

Keep external systems behind an adapter, repository, client, or gateway. The domain layer should depend on a stable contract so tests can use fakes and incidents can be isolated to one boundary.

Engineering decisions for the scenario

Protect dependencies first. Pools, queues, semaphores, caches, and worker counts need explicit limits. An unbounded queue only hides overload.
Preserve correctness. Use an idempotency key, transaction boundary, lock, version check, or schema validation where retries or concurrency can duplicate work.
Optimize with evidence. Use traces, slow-query data, GC pauses, queue depth, or p99 latency before choosing a cache, index, batch size, or concurrency setting.
Make recovery testable. Timeout, retry, rate limit, circuit breaking, rollback, and alerting should be exercised in a drill.

Common mistakes

Drawing only the happy path while omitting timeout, empty data, rejection, rollback, or replica lag.
Treating framework defaults as business contracts and discovering their limits after an upgrade.
Scaling machines before measuring pool exhaustion, lock contention, slow SQL, allocation, or event-loop blocking.
Treating logs as the only observability tool; metrics, traces, sampling, and redaction are also required.

Production checklist

Input, output, and error responses have explicit schemas
Dependencies have timeout, retry budgets, rate limits, and fallback behavior
Pools and queues expose capacity, waiting, and rejected-work metrics
Important state has idempotency, transaction, or recovery semantics
Logs, metrics, and traces share a request or correlation ID
Regression tests, load tests, and failure drills use production-like data

Summary

You understand this whiteboard when you can start from one request, explain every arrow’s contract, state how each risk is handled, and name the signal that would tell you to change the design.

Python Data Structures & Decorators

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

Whiteboard note: the goal is not to memorize boxes, but to connect each arrow to a request, a contract, and an operational signal.

Start with a real scenario

Use this situation as the mental model: An ETL job streams a large CSV, deduplicates IDs with a set, and wraps retries without hiding failures.. A useful backend diagram answers four questions: where does input enter, who owns state, which boundary can fail, and how do we know the system is healthy? The flow is Choose the right container; wrap behavior explicitly.

Deconstructing the architecture

Contract: define input, output, and error shape before adding implementation detail.
Mechanism: list → ordered mutable sequence; tuple → immutable record-like value. This is the part that determines latency, throughput, and testability.
State and resources: dict → keyed lookup + explicit schema; set → membership / deduplication. Explain creation, ownership, cleanup, and recovery.
Failure path: Decorator → wrapper preserves contract; combine it with Generator → lazy iteration + bounded memory when choosing a fallback, retry, or rollback.

A small implementation boundary

The following sketch is intentionally small. It shows where a production implementation should place validation and ownership rather than pretending that a happy path is enough.

request → bounded resource → validated boundary → observable result

Keep external systems behind an adapter, repository, client, or gateway. The domain layer should depend on a stable contract so tests can use fakes and incidents can be isolated to one boundary.

Engineering decisions for the scenario

Protect dependencies first. Pools, queues, semaphores, caches, and worker counts need explicit limits. An unbounded queue only hides overload.
Preserve correctness. Use an idempotency key, transaction boundary, lock, version check, or schema validation where retries or concurrency can duplicate work.
Optimize with evidence. Use traces, slow-query data, GC pauses, queue depth, or p99 latency before choosing a cache, index, batch size, or concurrency setting.
Make recovery testable. Timeout, retry, rate limit, circuit breaking, rollback, and alerting should be exercised in a drill.

Common mistakes

Drawing only the happy path while omitting timeout, empty data, rejection, rollback, or replica lag.
Treating framework defaults as business contracts and discovering their limits after an upgrade.
Scaling machines before measuring pool exhaustion, lock contention, slow SQL, allocation, or event-loop blocking.
Treating logs as the only observability tool; metrics, traces, sampling, and redaction are also required.

Production checklist

Input, output, and error responses have explicit schemas
Dependencies have timeout, retry budgets, rate limits, and fallback behavior
Pools and queues expose capacity, waiting, and rejected-work metrics
Important state has idempotency, transaction, or recovery semantics
Logs, metrics, and traces share a request or correlation ID
Regression tests, load tests, and failure drills use production-like data

Summary

You understand this whiteboard when you can start from one request, explain every arrow’s contract, state how each risk is handled, and name the signal that would tell you to change the design.

Python Runtime & Basics

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

Whiteboard note: the goal is not to memorize boxes, but to connect each arrow to a request, a contract, and an operational signal.

Start with a real scenario

Use this situation as the mental model: A data pipeline validates records at its boundary and uses profiling to find the real CPU hotspot.. A useful backend diagram answers four questions: where does input enter, who owns state, which boundary can fail, and how do we know the system is healthy? The flow is Python Code → Parser → AST → Bytecode → Interpreter.

Deconstructing the architecture

Contract: define input, output, and error shape before adding implementation detail.
Mechanism: Source → tokens → AST; AST → bytecode instructions. This is the part that determines latency, throughput, and testability.
State and resources: Interpreter loop executes bytecode; int / str / list / dict are objects. Explain creation, ownership, cleanup, and recovery.
Failure path: Dynamic typing resolves at runtime; combine it with Reference counting + cyclic GC reclaim objects when choosing a fallback, retry, or rollback.

A small implementation boundary

The following sketch is intentionally small. It shows where a production implementation should place validation and ownership rather than pretending that a happy path is enough.

request → bounded resource → validated boundary → observable result

Keep external systems behind an adapter, repository, client, or gateway. The domain layer should depend on a stable contract so tests can use fakes and incidents can be isolated to one boundary.

Engineering decisions for the scenario

Protect dependencies first. Pools, queues, semaphores, caches, and worker counts need explicit limits. An unbounded queue only hides overload.
Preserve correctness. Use an idempotency key, transaction boundary, lock, version check, or schema validation where retries or concurrency can duplicate work.
Optimize with evidence. Use traces, slow-query data, GC pauses, queue depth, or p99 latency before choosing a cache, index, batch size, or concurrency setting.
Make recovery testable. Timeout, retry, rate limit, circuit breaking, rollback, and alerting should be exercised in a drill.

Common mistakes

Drawing only the happy path while omitting timeout, empty data, rejection, rollback, or replica lag.
Treating framework defaults as business contracts and discovering their limits after an upgrade.
Scaling machines before measuring pool exhaustion, lock contention, slow SQL, allocation, or event-loop blocking.
Treating logs as the only observability tool; metrics, traces, sampling, and redaction are also required.

Production checklist

Input, output, and error responses have explicit schemas
Dependencies have timeout, retry budgets, rate limits, and fallback behavior
Pools and queues expose capacity, waiting, and rejected-work metrics
Important state has idempotency, transaction, or recovery semantics
Logs, metrics, and traces share a request or correlation ID
Regression tests, load tests, and failure drills use production-like data

Summary

You understand this whiteboard when you can start from one request, explain every arrow’s contract, state how each risk is handled, and name the signal that would tell you to change the design.

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.

Three-Layer Hallucination Prevention in RAG Systems: A Practical Guide

Wed, 05 Aug 2026 00:00:00 +0000

Hallucination is one of the biggest challenges in deploying LLMs for production use. This guide presents a practical three-layer approach to prevent hallucinations in RAG systems.

Above: Three-layer defense architecture for RAG hallucination prevention — Retrieval Filtering → Prompt Engineering → Output Validation

Understanding Hallucination

Hallucination occurs when LLMs generate plausible-sounding but factually incorrect information. In RAG systems, this typically happens when:

Retrieved context is irrelevant or insufficient
LLMs prioritize their training data over provided context
Models “fill in gaps” with fabricated information

Common Scenarios

Product Information - LLMs inventing prices, specifications, or availability
Medical/Agricultural Advice - Generating incorrect dosages or treatments
Legal/Financial - Creating non-existent regulations or policies

Layer 1: Retrieval Filtering

Ensure only relevant information reaches the LLM:

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

class RetrievalFilter:
 def __init__(self, vector_store, llm):
 self.vector_store = vector_store
 self.llm = llm

 def filter_documents(self, query: str, threshold: float = 0.7):
 """Filter retrieved documents by relevance score."""
 # Get initial results
 results = self.vector_store.similarity_search_with_score(query, k=10)

 # Filter by score threshold
 filtered = [
 (doc, score)
 for doc, score in results
 if score >= threshold
 ]

 # Rerank using LLM
 reranked = self.rerank_with_llm(query, filtered)

 return reranked

 def rerank_with_llm(self, query: str, documents):
 """Use LLM to rerank documents by relevance."""
 prompt = f"""Rank these documents by relevance to the query: {query}

Documents:
{[doc.page_content for doc, _ in documents]}

Return the most relevant document indices (comma-separated):"""

 response = self.llm.predict(prompt)
 # Parse and return top documents
 # Implementation details...

Filtering Strategies

Score Thresholding - Remove low-relevance documents
Diversity Filtering - Ensure varied perspectives
Source Verification - Prioritize authoritative sources
Freshness Filtering - Prefer recent information

Layer 2: Prompt Engineering

Design prompts that constrain LLM behavior:

HALLUCINATION_PREVENTION_PROMPT = """You are a helpful assistant. Answer the question based ONLY on the provided context.

Rules:
1. If the context doesn't contain enough information, say "I don't have enough information to answer this question."
2. Never make up information not present in the context.
3. Always cite the source document when possible.
4. If multiple sources conflict, present both perspectives.
5. For numerical data, quote exact figures from the context.

Context:
{context}

Question: {input}

Answer:"""

Prompt Templates by Domain

E-Commerce Products:

ECOMMERC_PROMPT = """You are a product expert. Answer questions about products using ONLY the provided product information.

Rules:
1. Never invent prices, specifications, or availability
2. If product info is incomplete, say "I don't have complete information about this product"
3. Always mention the product name and key features from the data
4. For comparisons, stick strictly to the provided data

Product Information:
{context}

Question: {input}
"""

Agricultural Knowledge:

AGRICULTURAL_PROMPT = """You are an agricultural expert. Answer farming questions using ONLY the provided knowledge base.

Rules:
1. Never invent pesticide dosages or treatment methods
2. If the knowledge base doesn't cover the specific crop/disease, recommend consulting a local expert
3. Always cite the source manual when possible
4. For safety-critical advice, include appropriate warnings

Knowledge Base:
{context}

Question: {input}
"""

Layer 3: Output Validation

Verify LLM responses against source data:

import re
from typing import Dict, List, Tuple

class OutputValidator:
 def __init__(self, llm):
 self.llm = llm

 def validate_response(self, response: str, context: str) -> Dict:
 """Validate LLM response against source context."""
 validation_results = {
 "is_valid": True,
 "issues": [],
 "corrected_response": response
 }

 # Check 1: Numerical claims
 numerical_issues = self.check_numerical_claims(response, context)
 if numerical_issues:
 validation_results["issues"].extend(numerical_issues)

 # Check 2: Entity verification
 entity_issues = self.verify_entities(response, context)
 if entity_issues:
 validation_results["issues"].extend(entity_issues)

 # Check 3: Source citation
 citation_issues = self.check_citations(response, context)
 if citation_issues:
 validation_results["issues"].extend(citation_issues)

 # If issues found, generate corrected response
 if validation_results["issues"]:
 validation_results["corrected_response"] = self.generate_corrected_response(
 response, validation_results["issues"], context
 )
 validation_results["is_valid"] = False

 return validation_results

 def check_numerical_claims(self, response: str, context: str) -> List[str]:
 """Verify numerical values in response exist in context."""
 issues = []

 # Extract numbers from response
 numbers = re.findall(r'\b\d+(?:\.\d+)?(?:%|元|kg|ml)?\b', response)

 for number in numbers:
 if number not in context:
 issues.append(f"Numerical value '{number}' not found in source context")

 return issues

 def verify_entities(self, response: str, context: str) -> List[str]:
 """Verify product/entity names exist in context."""
 issues = []

 # Simple entity extraction (can be enhanced with NER)
 entities = re.findall(r'[A-Z][a-z]+(?:\s[A-Z][a-z]+)*', response)

 for entity in entities:
 if entity.lower() not in context.lower():
 issues.append(f"Entity '{entity}' not found in source context")

 return issues

Implementation Example

Complete three-layer prevention system:

from langchain.chains import LLMChain
from langchain.prompts import ChatPromptTemplate

class HallucinationPreventionSystem:
 def __init__(self, vector_store, llm):
 self.vector_store = vector_store
 self.llm = llm
 self.retrieval_filter = RetrievalFilter(vector_store, llm)
 self.output_validator = OutputValidator(llm)

 def query(self, user_input: str) -> Dict:
 """Process query with three-layer hallucination prevention."""

 # Layer 1: Filter retrieval
 filtered_docs = self.retrieval_filter.filter_documents(user_input)
 context = "\n\n".join([doc.page_content for doc in filtered_docs])

 # Layer 2: Generate response with constrained prompt
 prompt = ChatPromptTemplate.from_template(HALLUCINATION_PREVENTION_PROMPT)
 chain = LLMChain(llm=self.llm, prompt=prompt)
 response = chain.invoke({"context": context, "input": user_input})

 # Layer 3: Validate output
 validation = self.output_validator.validate_response(
 response["text"], context
 )

 return {
 "response": validation["corrected_response"],
 "is_valid": validation["is_valid"],
 "issues": validation["issues"],
 "sources": [doc.metadata.get("source") for doc in filtered_docs]
 }

Measuring Effectiveness

Track key metrics to evaluate your prevention system:

class HallucinationMetrics:
 def __init__(self):
 self.metrics = {
 "total_queries": 0,
 "hallucinations_detected": 0,
 "false_positives": 0,
 "retrieval_accuracy": 0
 }

 def evaluate_response(self, response: str, context: str, ground_truth: str):
 """Evaluate response quality and hallucination presence."""
 self.metrics["total_queries"] += 1

 # Check for hallucinations
 if self.detect_hallucination(response, context):
 self.metrics["hallucinations_detected"] += 1

 # Compare with ground truth
 accuracy = self.calculate_accuracy(response, ground_truth)
 self.metrics["retrieval_accuracy"] += accuracy

 def detect_hallucination(self, response: str, context: str) -> bool:
 """Simple hallucination detection."""
 # Check if response contains information not in context
 response_words = set(response.lower().split())
 context_words = set(context.lower().split())

 # Words in response but not in context
 novel_words = response_words - context_words

 # If too many novel words, likely hallucination
 return len(novel_words) > len(response_words) * 0.3

Metrics Dashboard

Metric	Description	Target
Hallucination Rate	% of responses with hallucinations	< 5%
Retrieval Accuracy	% of relevant documents retrieved	> 90%
Response Quality	User satisfaction score	> 4.5/5
Latency	Response time including validation	< 2s

Conclusion

Preventing hallucinations in RAG systems requires a multi-layered approach:

Retrieval Filtering - Ensure only relevant information reaches the LLM
Prompt Engineering - Constrain LLM behavior with clear instructions
Output Validation - Verify responses against source data

The complete implementation is available on .

Questions? Reach out on or email me at !

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 !

Agri-QA-Assistant

Fri, 20 Mar 2026 00:00:00 +0000

Agricultural Intelligent Q&A Prototype System based on LangGraph Goal-Oriented Agent Architecture.

Project Overview

Agri-QA-Assistant is a production-grade prototype for agricultural knowledge retrieval and question answering. It combines Retrieval-Augmented Generation (RAG) with a goal-oriented agent architecture to provide accurate, context-aware answers about crop cultivation, pest management, fertilization, and agricultural policy.

Core Features

Feature	Description
🌱 Domain-Specific RAG	ChromaDB vector store with curated agricultural knowledge base covering crops, pests, fertilizers, soil, and machinery
🧠 Multi-turn Memory	SQLite-backed conversation history with context continuity across sessions
🎯 Intent-Aware Routing	LangGraph agent routes queries to RAG, general knowledge, or tool-augmented paths
📊 Evidence Grounding	Citation-backed responses with source attribution and faithfulness scoring
🔧 MCP Integration	Open MCP servers for web fetch, temporal queries, and extensible tool use
🎨 Apple Liquid Glass UI	Frosted glass effects, translucent layers, iOS-style animations with Tailwind CSS

Technical Architecture

┌─────────────────────────────────────────────────────────────────┐
│ Frontend: Next.js 14 + Radix UI │
│ Apple Liquid Glass Chat Interface │
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────────┐ │
│ │ Chat Panel │ │ Knowledge │ │ Generative UI │ │
│ │ + Streaming │ │ Panel │ │ (Crop Diagnosis, etc.) │ │
│ └─────────────┘ └──────────────┘ └─────────────────────────┘ │
└────────────────────────────┬────────────────────────────────────┘
 │ HTTP / SSE
┌────────────────────────────▼────────────────────────────────────┐
│ Backend: FastAPI + LangGraph │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────────────────┐ │
│ │ Intent Router │ │ RAG Pipeline │ │ Tool Executor │ │
│ │ (LangGraph) │ │ (ChromaDB) │ │ (MCP Servers) │ │
│ └──────────────┘ └──────────────┘ └────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Technical Highlights

1. Goal-Oriented Agent Architecture

Built on LangGraph’s agent framework, the system dynamically routes queries based on user intent:

RAG Path: Retrieves information from agricultural knowledge base
General Knowledge Path: Calls general LLM for answers
Tool-Augmented Path: Integrates external tools for real-time data

2. Evidence Grounding & Faithfulness Scoring

Each response includes source citations
Faithfulness scoring ensures information reliability
Users can verify response sources

3. Apple Liquid Glass UI

Modern frosted glass effect interface
iOS-style animations and interactions
Responsive design for multi-device support

4. MCP Server Integration

Open tool-calling architecture
Supports web fetch, temporal queries, and extensions
Pluggable tool ecosystem

Project Results

Accuracy: 95%+ agricultural knowledge Q&A accuracy
Usability: Multi-turn conversation context retention
Experience: Modern Apple Liquid Glass UI
Extensibility: MCP tool integration architecture

Project Status: ✅ Completed
GitHub: