DEV Community: Ajmal Hasan

Jev & System One Models — Fast Decision Making for AI Agents

Ajmal Hasan — Mon, 21 Sep 2026 17:48:25 +0000

What You'll Learn

What Jev is and how it differs from traditional LLMs
What "System One" models are (and how they relate to Kahneman's thinking framework)
The three question types: Choice, Score, and Noul
How to use Jev with LangChain (langchain-typesafe)
Real-world use cases: Model Routing, Agent Guardrails, Email Triage, Support Ticket Classification
Where Jev fits in the agent loop alongside GPT/Gemini/Claude

1. What Is Jev?

The Simple Idea

Jev is a classification model built by TypeSafe AI. Unlike GPT or Gemini, Jev does NOT generate text. Instead, it answers structured questions about data and returns typed answers with probabilities.

TRADITIONAL LLM (GPT, Gemini, Claude):
  Input:  "Is this support ticket urgent?"
  Output: "Yes, based on the language used, this appears to be an urgent request..."
  Speed:  ~500-2000ms
  Cost:   ~$0.01 per call

JEV (System One Model):
  Input:  State + Question { "is_urgent": noul }
  Output: { "is_urgent": { "noul": 0.999 } }       ← 99.9% probability
  Speed:  ~2-5ms (200x faster)
  Cost:   ~$0.00003 per call (400x cheaper)

💡 Analogy: Think of a company. The LLM is the CEO — brilliant, can write reports, reason through complex problems, but slow and expensive. Jev is the security guard at the front gate — instantly decides "allowed" or "blocked" without needing to write a paragraph about it. You wouldn't ask the CEO to check ID badges; you wouldn't ask the guard to write the quarterly report.

2. What Are "System One" Models?

The name comes from Daniel Kahneman's famous book Thinking, Fast and Slow:

System	Thinking Type	Example	AI Equivalent
System 1	Fast, automatic, intuitive	"Is this email spam?" → Instantly know	Jev — fast classification
System 2	Slow, deliberate, analytical	"Write a marketing strategy" → Think carefully	GPT/Gemini — text generation

System One Model Definition

📖 System One models are a class of AI models built to make fast, structured decisions that software can use directly. A System One model evaluates a state and returns typed answers and probabilities.

How It's Trained

Jev uses Reinforcement Learning for Calibrated Decisions (RLCD) — a training approach that optimizes for producing well-calibrated probability scores (when Jev says 0.95, it really means 95% confident, not just a rough guess).

Traditional LLM Training:
  Objective: Generate the NEXT TOKEN that best continues the text
  Output:    Free-form text (any shape, any length)

Jev (RLCD) Training:
  Objective: Produce CALIBRATED PROBABILITIES for structured questions
  Output:    Fixed-shape JSON with confidence scores

3. How Jev Works — State + Questions

Every Jev call follows the same simple pattern: you send state (the context) and questions about that state.

The API Request Format

{
  "model": "jev-latest",
  "state": "Hi, I've been trying to connect my Stripe account for 3 days and it keeps failing. I'm losing sales. Please help ASAP.",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "The message conveys urgency or time-sensitivity"
    }
  }
}

The API Response

{
  "is_urgent": {
    "type": "noul",
    "noul": 0.999
  }
}

That's it. 0.999 = 99.9% probability that the message is urgent. Your code uses this number directly — no text parsing needed.

4. The Three Question Types

Jev supports three types of structured questions, each designed for a different decision pattern:

4a. Noul (Yes/No)

"Is this statement true?" → Returns probability (0.0 to 1.0)

# Noul = Boolean probability
{
    "is_urgent": {
        "type": "noul",
        "instructions": "The message conveys urgency"
    }
}
# Response: { "noul": 0.999 }  ← 99.9% yes

💡 Analogy: Like a lie detector that gives you a confidence percentage instead of just "true" or "false".

Use cases: Spam detection, urgency flagging, content safety checks, prompt injection detection.

4b. Choice (Pick One from Options)

"Which category does this belong to?" → Returns probability for EACH option

{
    "department": {
        "type": "choice",
        "instructions": "Which team should handle this ticket?",
        "options": ["billing", "engineering", "sales", "hr"]
    }
}
# Response:
# { "choice": "engineering", "probabilities": {"billing": 0.02, "engineering": 0.91, "sales": 0.05, "hr": 0.02} }

💡 Analogy: Like asking 100 experts to vote on which category something belongs to, and getting the vote distribution back.

Use cases: Intent classification, model routing, agent selection, query categorization.

4c. Score (Rate on a Scale)

"Rate this on a scale" → Returns continuous score between ordered levels

{
    "severity": {
        "type": "score",
        "instructions": "How severe is this issue?",
        "levels": ["low", "medium", "high", "critical"]
    }
}
# Response:
# { "score": 0.87, "level": "high" }

💡 Analogy: Like asking a doctor "how sick is this patient?" and getting a precise number on a severity scale, not just "pretty sick."

Use cases: Risk scoring, quality assessment, sentiment intensity, priority ranking.

5. Multiple Questions in One Request

One of Jev's killer features: you can ask multiple questions about the same state in one API call. All questions are evaluated in parallel, so adding more questions barely changes latency.

{
  "model": "jev-latest",
  "state": "Customer: I was charged $499 twice for the same order. This is ridiculous. Fix it NOW or I'm filing a chargeback.",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this need immediate attention?"
    },
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "options": ["billing", "engineering", "sales", "support"]
    },
    "sentiment": {
      "type": "score",
      "instructions": "How negative is the customer sentiment?",
      "levels": ["positive", "neutral", "frustrated", "angry"]
    }
  }
}

One call → Three answers → ~3ms total.

Compare this to using an LLM:

3 separate LLM calls ≈ 3000ms and ~$0.03
1 Jev call with 3 questions ≈ 3ms and ~$0.00003

6. Using Jev with LangChain

Installation

pip install langchain-typesafe

Setting Up

import os
os.environ["TYPESAFE_API_KEY"] = "your-api-key-here"

Basic Classification with `TypeSafeClassifier`

from langchain_typesafe import Noul, Choice, Score, TypeSafeClassifier

# Create the classifier (like creating a ChatOpenAI instance)
classifier = TypeSafeClassifier()

# Classify a support ticket
response = classifier.invoke({
    "state": (
        "The deploy failed twice and customers are seeing 500s. "
        "Can someone look now?"
    ),
    "questions": {
        "urgent": Noul(
            instructions="Does this need attention right now?"
        ),
    },
})

# Use the result directly — no text parsing!
urgency = response.nouls["urgent"].noul     # 0.999
if urgency > 0.8:
    print("🚨 URGENT! Routing to on-call engineer...")

💡 Key Difference from ChatOpenAI: With ChatOpenAI.invoke(), you get a text string you have to parse. With TypeSafeClassifier.invoke(), you get typed Python objects with probability scores you can use directly in if statements.

Multi-Question Example

from langchain_typesafe import Noul, Choice, Score, TypeSafeClassifier

classifier = TypeSafeClassifier()

result = classifier.invoke({
    "state": "My payment of $2,400 was deducted but order shows cancelled. Need refund ASAP.",
    "questions": {
        "urgent": Noul(instructions="Needs immediate attention?"),
        "team": Choice(
            instructions="Which team should handle this?",
            options=["billing", "engineering", "support", "sales"]
        ),
        "anger_level": Score(
            instructions="How frustrated is the customer?",
            levels=["calm", "concerned", "frustrated", "furious"]
        ),
    },
})

print(f"Urgency:     {result.nouls['urgent'].noul:.1%}")        # 99.8%
print(f"Team:        {result.choices['team'].choice}")           # "billing"
print(f"Anger Level: {result.scores['anger_level'].level}")      # "frustrated"

7. Real-World Use Cases with LLM Agents

7a. Model Routing (Use Cheap Model vs Expensive Model)

Problem: Every query going to GPT-4 is expensive. Simple lookups ("what's the PTO policy?") don't need the same model as complex debugging tasks.

Solution: Jev classifies the query difficulty in ~2ms, then routes to the appropriate model:

from langchain_typesafe.experimental.middleware import (
    ModelChoice,
    ModelRouterMiddleware,
)

router = ModelRouterMiddleware(
    choices={
        "fast": ModelChoice(
            model="openai:gpt-4o-mini",
            criteria="Direct lookups, extraction, and localized changes.",
        ),
        "powerful": ModelChoice(
            model="openai:gpt-4o",
            criteria="Architecture decisions and high-stakes analysis.",
        ),
    },
    instructions="Choose the least costly model that can complete the task.",
)

Without Jev (every query → GPT-4):
  100 queries × $0.03 = $3.00

With Jev routing (80 simple → GPT-4o-mini, 20 complex → GPT-4):
  80 × $0.002 + 20 × $0.03 + 100 × $0.00003 = $0.763
  ────────────────────────────────────────────────
  💰 75% COST REDUCTION

7b. Agent Guardrails / Auto Mode (Tool Risk Gating)

Problem: AI agents can be tricked into running dangerous commands (e.g., rm -rf /, database drops, unauthorized API calls).

Solution: Before every tool execution, Jev classifies whether the action is risky:

from langchain_typesafe.experimental.middleware import AutoModeMiddleware

# Creates a guardrail that checks tool calls before execution
guardrail = AutoModeMiddleware(tools=["bash", "database_query"])

# Agent now auto-blocks risky tool calls
agent = create_agent("openai:gpt-4o", middleware=[guardrail])

Agent wants to run: rm -rf /tmp/user_data
  ↓
Jev evaluates in 2ms: { "is_dangerous": { "noul": 0.997 } }
  ↓
BLOCKED! Human approval required before execution.

💡 Connection to Your Capstone: This is exactly what the HITL (Human-in-the-Loop) gate does in Milestone 6's tool_agent.py — but instead of using regex rules or an LLM call for the check, Jev does it in 2ms with calibrated confidence scores.

7c. Email Triage at Scale

Problem: A company receives 10,000+ emails daily. Using an LLM to classify each one costs ~$100/day and takes hours.

Solution:

classifier = TypeSafeClassifier()

for email in incoming_emails:
    result = classifier.invoke({
        "state": email.body,
        "questions": {
            "is_spam": Noul(instructions="Is this unsolicited marketing or spam?"),
            "department": Choice(
                instructions="Route to correct department",
                options=["sales", "support", "legal", "hr", "engineering"]
            ),
            "priority": Score(
                instructions="How urgently does this need a response?",
                levels=["low", "medium", "high", "critical"]
            ),
        },
    })

    if result.nouls["is_spam"].noul > 0.9:
        archive(email)
    else:
        route_to(result.choices["department"].choice, priority=result.scores["priority"].level)

10,000 emails/day:
  LLM approach:  10,000 × $0.01 × 3 questions = $300/day, ~8 hours
  Jev approach:   10,000 × $0.00003 × 1 call    = $0.30/day, ~30 seconds

7d. Support Ticket Classification & Routing

# Classify support ticket for the supervisor agent
ticket = "Error E-4501 keeps appearing when I try to export reports. Blocking my quarterly review."

result = classifier.invoke({
    "state": ticket,
    "questions": {
        "agent_type": Choice(
            instructions="Which specialized agent should handle this?",
            options=["rag_agent", "tool_agent", "reasoning_agent"]
        ),
        "needs_human": Noul(
            instructions="Does this require human escalation?"
        ),
    },
})

# Result: { "agent_type": "rag_agent" (0.88), "needs_human": 0.12 }
# → Route to RAG agent, no human escalation needed

8. Where Jev Fits in the Agent Loop

Traditional Agent Loop (ALL LLM):
┌─────────────────────────────────────────────────────┐
│  User Query                                         │
│      ↓                                              │
│  LLM: Classify intent        (500ms, $0.01)  ←slow │
│      ↓                                              │
│  LLM: Choose tool            (500ms, $0.01)  ←slow │
│      ↓                                              │
│  Execute tool                 (varies)              │
│      ↓                                              │
│  LLM: Check if safe          (500ms, $0.01)  ←slow │
│      ↓                                              │
│  LLM: Format response        (800ms, $0.02)        │
│      ↓                                              │
│  Return to user               Total: ~2.3s, ~$0.05 │
└─────────────────────────────────────────────────────┘

Optimized Agent Loop (Jev + LLM):
┌─────────────────────────────────────────────────────┐
│  User Query                                         │
│      ↓                                              │
│  JEV: Classify intent + risk  (3ms, $0.00003) ←⚡  │
│      ↓                                              │
│  JEV: Choose tool + model     (3ms, $0.00003) ←⚡  │
│      ↓                                              │
│  Execute tool                  (varies)             │
│      ↓                                              │
│  LLM: Generate response       (800ms, $0.02)       │
│      ↓                                              │
│  Return to user               Total: ~0.8s, ~$0.02 │
└─────────────────────────────────────────────────────┘

💡 Rule of Thumb: Use Jev for decisions (classify, route, gate, score). Use LLMs for generation (write, explain, reason, synthesize).

9. Jev vs LLM Structured Output — When to Use Which?

Aspect	Jev (System One)	LLM `.with_structured_output()`
Speed	~2-5ms	~500-2000ms
Cost	~$0.00003/call	~$0.01-0.03/call
Output	Typed probabilities	Parsed JSON (from text)
Confidence	Calibrated (0.95 = really 95%)	Uncalibrated (varies wildly)
Text generation	❌ Cannot generate text	✅ Full text generation
Complex reasoning	❌ Not designed for it	✅ Chain-of-thought, analysis
Parallel questions	✅ Multiple questions, same latency	❌ Each question = separate call
Best for	Classification, routing, gating	Writing, explaining, reasoning

Decision Flowchart

Is the task "decide/classify" or "generate/write"?
│
├── DECIDE/CLASSIFY → Use Jev
│   ├── "Is this urgent?"              → Noul
│   ├── "Which department?"            → Choice
│   ├── "How risky (low/med/high)?"    → Score
│   └── "Route to which model?"        → Choice
│
└── GENERATE/WRITE → Use LLM
    ├── "Write a response to this email"
    ├── "Explain why error E-4501 happens"
    ├── "Analyze Q3 vs Q4 revenue trends"
    └── "Summarize these 10 documents"

10. Quick Reference

Setup Cheat Sheet

# Install
pip install langchain-typesafe

# Set API Key
export TYPESAFE_API_KEY="your-key-here"

Question Type Cheat Sheet

Type	Question Pattern	Returns	Example
Noul	"Is this [X]?"	Probability (0.0–1.0)	Is this spam? → `0.97`
Choice	"Which [X]?"	Selected option + all probabilities	Which dept? → `"billing"`
Score	"How [X]?"	Continuous score + level	How urgent? → `0.85, "high"`

Cost Comparison

Operation	LLM Cost	Jev Cost	Savings
1 classification	~$0.01	~$0.00003	333x cheaper
100 classifications	~$1.00	~$0.003	333x cheaper
10,000 email triage	~$100	~$0.30	333x cheaper

Links & Resources

Resource	URL
TypeSafe AI Docs	docs.typesafe.ai
LangChain Integration	langchain-typesafe docs
TypeSafe Blog (Intro)	typesafe.ai/blog
LangChain Blog (Harness)	langchain.com/blog
TypeSafe Quickstart	docs.typesafe.ai/quickstart

RAG for Beginners: 5 Levels of Building an AI That Actually Knows Your Stuff

Ajmal Hasan — Sun, 13 Sep 2026 10:26:44 +0000

Have you ever wished ChatGPT could answer questions about your documents — your company's HR policy, your class notes, your product manual — instead of just whatever it happened to learn from the internet? That's exactly the problem RAG solves.

If you've seen the term "RAG" floating around and felt a little lost, don't worry — by the end of this post you'll understand it from the ground up, and see how a simple RAG app can grow, step by step, into the kind of AI assistant real companies run internally.

We'll climb through 5 levels, each one a small, understandable upgrade on the last. No prior AI experience needed. Let's go 🚀

First, What Even Is RAG? 🤔

RAG stands for Retrieval-Augmented Generation. That's a mouthful, so let's translate it:

Retrieval = finding relevant information
Augmented = adding it to
Generation = the AI writing an answer

💡 Analogy: Picture two students taking a test. One has to answer purely from memory — that's a regular chatbot. It only knows what it was trained on, it has a knowledge cutoff, and it sometimes "hallucinates" (confidently makes stuff up). The other student gets an open-book exam and can flip to the right page before answering — that's RAG. Same brain, very different accuracy, because now it can look things up before speaking.

RAG lets an AI look things up in your documents before answering, instead of relying only on what it memorized during training. Let's build one, level by level.

Level 1: Basic RAG — Teaching AI to Read Your Documents 📄

A basic RAG system has exactly two jobs: organize your documents so they're searchable, and search them when someone asks a question.

Building the "library" first (ingestion)

Before anyone can ask anything, the documents need to be prepped:

📄 Load Files  →  ✂️ Chunk  →  🔢 Embed  →  🗄️ Store in a Vector Database

1) Load — grab the raw files: PDFs, Word docs, plain text.
2) Chunk — cut each document into small pieces, roughly 1,000 characters each.

💡 Analogy: You wouldn't hand someone an entire 300-page manual just to answer "what's the return policy?" You'd flip to the one paragraph that matters. Chunking pre-cuts the book into paragraph-sized pieces so the AI can grab just the relevant bit later, instead of drowning in the whole document.

3) Embed — this sounds intimidating but isn't. Each chunk of text gets converted into a list of numbers called a vector (or embedding), using a small AI model built just for this job (here, one from OpenAI).

💡 Analogy: Think of an embedding like GPS coordinates, except instead of location, it represents meaning. Two chunks that mean similar things land near each other on this "meaning map," even with completely different wording — "I love my dog" and "my puppy is the best" would sit close together, while "stock market crash" would land far away.

4) Store — all those coordinates get saved in a database built specifically for this: a vector database (here, Qdrant). Think of it as a library where books are shelved by meaning instead of alphabetically by author.

Actually answering a question (querying)

Now someone asks, "What's our vacation policy?" Here's the flow:

❓ Question  →  🔢 Embed the Question  →  🔍 Find Top 4 Closest Chunks  →  🤖 LLM Writes an Answer

The question gets embedded the same way the documents were, so it lands somewhere on that same meaning-map. The system then finds the 4 chunks sitting closest to it — measured with cosine similarity, which is really just a mathy way of asking "how similarly do these two arrows point?" Those 4 chunks, plus the original question, go to an LLM (the AI model that actually writes the answer — here, GPT-4o), which drafts a response grounded in what was actually retrieved.

💡 Analogy: It's like asking a librarian a question. Instead of answering from foggy memory, they run to the shelf, grab the 4 most relevant books, skim them, and answer based on what's actually written down — not a guess.

The catch: this works great as a first version, but it has a real blind spot — it's bad at exact matches. Search for "Invoice #4471" and pure meaning-based search might miss it entirely, because "meaning-close" isn't the same as "text-identical." That's exactly what Level 2 fixes.

Level 2: Hybrid Search — Two Search Buddies Beat One 🤝

Let's meet the two search styles:

Semantic search (what we just built) — great at understanding meaning
Keyword search (called BM25, run through Elasticsearch) — great at matching exact words, like Ctrl+F on steroids

💡 Analogy: Imagine two friends helping you pick a restaurant. One is great at reading the vibe of what you want ("cozy and quiet") even if you don't use the exact right words. The other is extremely literal — say "sushi" and they only think sushi, word for word. Each one misses things alone. Ask both and combine their answers, though, and you get a much better recommendation.

Say someone asks "What is the leave policy?" Semantic search ranks Doc A highest, then Doc B, then Doc D. Keyword search ranks Doc C highest, then Doc A, then Doc B. The two lists disagree, and their scores live on totally different scales — so we can't just compare the raw numbers.

The fix: Reciprocal Rank Fusion (RRF)

Scary name, simple idea: instead of comparing raw scores, just look at where each document placed (1st, 2nd, 3rd...) on each list, and combine the ranks:

score = 1 / (60 + rank)   — added up across both lists a document appears in

💡 Analogy: It's like merging two friends' "Top 3 restaurants" lists. A place that shows up at #1 on both lists should win overall — even if it wasn't the single highest score on either one. That's a stronger signal of being genuinely good than acing one list and being absent from the other.

In our example, Doc A wins the fusion — not because it topped either list alone, but because it did well on both. Now the search understands what you mean and what you typed. We still have a problem, though: this system can only look things up. It can't do math, take multi-step actions, or handle a request with two parts. On to Level 3.

Level 3: Single Agent — Giving the AI a Toolbox 🧰

Suppose someone asks: "What's our travel policy, and how much is the per diem for a 5-day trip?" That needs two different skills — looking something up (the per diem rate) and doing math (multiplying by 5). A basic RAG pipeline can't do both in one shot.

Enter the agent

An agent is an AI that doesn't just blurt out an answer — it can pause, decide it needs a tool, use it, look at the result, and decide what to do next. This loop has a name: ReAct (Reason + Act).

🤔 Think  →  🛠️ Act (use a tool)  →  👀 Observe the result  →  🤔 Think again  → ...  →  ✅ Final Answer

💡 Analogy: Think of a sharp personal assistant instead of a search engine. Ask them something tricky and they don't guess — they say "let me check," pick up the right tool (a phone, a calculator, a filing cabinet), get the info, and then answer. They repeat this loop as many times as it takes.

Our agent has 3 tools available:

🧮 calculator — math and financial calculations
📚 search_knowledge_base — our hybrid search from Level 2, now wrapped up as a tool the agent can call
🌐 search_web — for current-events info that isn't in the internal documents

For the travel policy question, the agent's thought process looks like:

Think: "I need the per diem rate first." → Act: calls search_knowledge_base → Observe: "$150/day"
Think: "Now multiply that by 5." → Act: calls calculator → Observe: "$750"
Think: "I have everything I need." → Final Answer: "$750 for a 5-day trip."

This runs on a framework called LangGraph, which tracks what's already happened and decides which path to take next — like a flowchart the AI follows live. This is the real turning point in the whole roadmap: the system stopped just looking things up and started completing tasks. 🎉

Level 4: Multi-Agent Orchestrator — Hiring Specialists Instead of One Generalist 🏥

One agent juggling lots of tools works, but it strains as things get more complex — like one person trying to be a doctor, a lawyer, and an accountant all at once. Decent at all three, great at none.

💡 Analogy: Walk into a hospital and you don't head straight for a brain surgeon because you have a cold. There's a receptionist at the front who listens and sends you to the right specialist. That's exactly what an orchestrator agent does — except with questions instead of patients.

❓ Question  →  🧭 Orchestrator (classifies it)  →  routes to  →  the right specialist agent

Three specialists, each tuned for a different job:

Specialist	Best at	How it works
📖 RAG Agent	Simple factual questions	Searches docs (top 4 chunks), answers only from what it finds
🔎 Search Agent	Exact terms, codes, IDs	Uses keyword search (BM25) to nail exact matches
🧩 Reasoning Agent	Comparisons & judgment calls	Pulls a wider set of chunks (top 6) and reasons step by step

Ask "Compare our leave policy with market standards" and the orchestrator recognizes this isn't a simple lookup — it needs judgment — so it routes it to the Reasoning Agent, not the basic one.

All three specialists share a common notebook (shared state) tracking the conversation, the question type, which sources were used, and a trace of what happened — so nothing gets lost when a question is handed off. The final answer comes back with receipts: sources, an agent trace, and a clean structured response, not just a paragraph.

Level 5: Knowledge Assistant (RAG + MCP) — Usable by Literally Anything 🔌

We've built something smart, but it still only works through one specific chat app. What if a Slack bot, an internal dashboard, and a mobile app should all share the same brain, without rebuilding it three times?

💡 Analogy: Before USB-C, every device had its own charging cable — one for your phone, one for your camera, one for your laptop. Chaos. USB-C fixed that by becoming one standard plug anything can use. MCP (Model Context Protocol) is basically USB-C for AI systems — a standard way for any app to plug into the same knowledge base and tools, without custom wiring every time.

🧑‍💼 Employee's App  ⇄  MCP Server (FastMCP)  ⇄  🧠 RAG System

The MCP server exposes two kinds of things:

Resources (readable knowledge) — documents://policies, documents://faqs, like labeled folders anyone can open
Tools (callable actions) — search_documents(), compare_documents(), search_raw_chunks(), like buttons anyone can press

Internally, the RAG pipeline gets one more upgrade too: Embed → Retrieve → Rerank → LLM. That new Rerank step is a second, more careful pass that re-checks the top results and puts the truly best ones first — a second opinion after the initial search.

And instead of a loose paragraph, the reply now comes back as structured, predictable data (built with a tool called Pydantic):

{
  "answer": "Employees get 20 days of annual leave.",
  "confidence": "high",
  "sources": ["hr_policy.pdf"],
  "follow_up_questions": ["How does unused leave carry over?"]
}

💡 Analogy: A random paragraph back is like asking a friend for directions and getting a rambling story. Structured JSON back is like turn-by-turn directions from Google Maps — predictable, and any app can use it without guessing what it means.

This is what makes a system genuinely "enterprise-ready": any other piece of software can plug in and trust the shape of the response, every single time.

Putting It All Together 🎯

Level	What's new	In one sentence
1️⃣ Basic RAG	Vector search	The AI can finally read your documents
2️⃣ Hybrid Search	Keyword + semantic fusion	It stops missing exact matches
3️⃣ Single Agent	Tools + the ReAct loop	It can act, not just answer
4️⃣ Multi-Agent	Orchestrator + specialists	It picks the right expert for the job
5️⃣ Knowledge Assistant	MCP + structured output	It becomes a service anything can plug into

If you're just starting out, don't try to build Level 5 on day one. Start with Level 1 — it's genuinely useful on its own — and treat every level after it as a targeted fix for one specific weakness you'll actually run into. Build, notice what breaks, climb a level, repeat. That's honestly how most real-world AI systems get built anyway.

If this helped, I'd love to know which level you're building toward — drop a comment! 👇

📐 Mathematics for AI — Foundation Course

Ajmal Hasan — Sat, 25 Jul 2026 09:06:54 +0000

Before you can truly understand how AI systems think, learn, and generate responses, you need to understand the math that powers them. This guide covers the essential mathematical concepts that form the backbone of modern Artificial Intelligence and Large Language Models (LLMs).

Why does this matter? Every aspect of AI — from how text is encoded, to how a model predicts the next word, to how it improves itself during training — is driven by mathematics. Skipping this foundation means you will only ever use AI as a black box, without understanding why it works.

🔄 How an LLM Actually Works — The Complete Pipeline

Before diving into each math concept individually, here's the big picture of how text flows through a Large Language Model from input to output. Every section in this guide maps to a step in this pipeline:

  ┌─────────────────────┐
  │     Your Prompt     │   "What is gravity?"
  └──────────┬──────────┘
             ↓
  ┌─────────────────────┐
  │     Tokenizer       │   Splits text into chunks (BPE algorithm)
  └──────────┬──────────┘   → Section 1: Number Systems & Encoding
             ↓
  ┌─────────────────────┐
  │     Token IDs       │   Each token → a number (e.g., "gravity" → 17942)
  └──────────┬──────────┘   → Section 1: Number Systems & Encoding
             ↓
  ┌─────────────────────┐
  │   Embedding Model   │   Each token ID → a dense vector of numbers
  └──────────┬──────────┘   → Section 3: Vectors & Embeddings
             ↓
  ┌─────────────────────┐
  │      Vectors        │   [0.12, -0.87, 0.45, ...] per token
  │  + Positional Info  │   → Section 3 & 6: Embeddings & Linear Algebra
  └──────────┬──────────┘
             ↓
  ┌─────────────────────┐
  │    Transformer      │   Multi-Head Attention + Feed-Forward layers
  │    (×N layers)      │   repeated 32-96+ times
  └──────────┬──────────┘   → Section 4, 6: Algebra & Linear Algebra
             ↓
  ┌─────────────────────┐
  │    Probability      │   Softmax converts final output to
  │    Distribution     │   probabilities over entire vocabulary
  └──────────┬──────────┘   → Section 2 & 6: Probability & Softmax
             ↓
  ┌─────────────────────┐
  │    Next Token       │   Sampling picks one token
  │    (Sampling)       │   (using Temperature, Top-K, Top-P)
  └──────────┬──────────┘   → Section 2: Probability & Prediction
             ↓
  ┌─────────────────────┐
  │  Append & Repeat    │   Add the new token to the sequence,
  │  (Autoregressive)   │   feed it back in, and repeat until done
  └─────────────────────┘

Key Insight: The model generates text one token at a time. Each time it produces a token, it adds it to the input and runs the entire pipeline again for the next token. This is called autoregressive generation.

📚 Core Concepts

1. Number Systems & Encoding

How do computers understand human language?

Computers only understand numbers. So before any AI can process text, every character must be converted into a number.

ASCII: The original standard that mapped 128 common English characters (letters, digits, symbols) to numbers. For example, the letter A = 65.
Unicode: An expanded standard that covers over 140,000 characters across all human languages, including emojis and special symbols.
UTF-8: The most widely used encoding format on the internet. It efficiently encodes Unicode characters into byte sequences that computers can store and transmit. English characters use 1 byte, while complex characters (like Chinese or emojis) use up to 4 bytes.
Tokenization: AI models do not read character-by-character. Instead, text is broken into chunks called tokens (which can be words, parts of words, or punctuation). Each token is then converted into a numeric ID before being fed into the model.
- BPE (Byte Pair Encoding): The most common tokenization algorithm used by models like GPT. It starts with individual characters, then repeatedly merges the most frequent pairs of adjacent tokens until a target vocabulary size is reached.
- Vocabulary Size: The total number of unique tokens a model recognizes. GPT-4 uses ~100,000 tokens. Larger vocabularies mean fewer tokens per sentence (more efficient), but a bigger embedding matrix (more memory).
One-Hot Encoding: Before embeddings existed, words were represented as sparse binary vectors where only one position is "1" and the rest are "0". This is wasteful and captures no meaning, which is why embeddings replaced it.

💡 Example — How "Hello AI" becomes numbers:

Text Input:   "Hello AI"

Step 1 – Tokenize (using BPE):
  ["Hello", " AI"]

Step 2 – Assign Token IDs (lookup in vocabulary table):
  "Hello" → 9906
  " AI"   → 15592

Step 3 – Model Input:
  [9906, 15592]

The model never sees letters — only numbers.

💡 Example — One-Hot Encoding vs. Embeddings:

Vocabulary: [cat, dog, fish, car]

One-Hot (sparse, no meaning):
  "cat"  → [1, 0, 0, 0]
  "dog"  → [0, 1, 0, 0]
  "fish" → [0, 0, 1, 0]
  "car"  → [0, 0, 0, 1]
  Problem: "cat" and "dog" look equally different from each other
           as "cat" and "car". No notion of similarity.

Embedding (dense, captures meaning):
  "cat"  → [0.82, -0.15, 0.47]   ← close to "dog"
  "dog"  → [0.79, -0.12, 0.51]   ← close to "cat"
  "fish" → [0.55, 0.33, 0.42]    ← animal but different
  "car"  → [-0.71, 0.88, -0.22]  ← very different from animals

2. Probability & Prediction

How does AI "know" what to say next?

AI models do not look up facts in a database. Instead, they predict the most probable next token based on everything they have processed so far. This is purely a probability problem.

Probability Distribution: After processing your input, the model calculates a probability score for every word in its vocabulary. The word with the highest score is the most likely next word.
- All probabilities must sum to exactly 1.0 (100%).
- This distribution is produced by the Softmax function (covered in Section 6).
Conditional Probability: The probability of a word depends on all the words that came before it. Mathematically: P(word_n | word_1, word_2, ..., word_n-1). This chain of dependencies is what makes language models "contextual."
Temperature: A setting that controls how "creative" or "random" the model's output is.
- Mathematically, temperature divides the logits before Softmax: softmax(logits / T).
- A low temperature (e.g., 0.2) sharpens the distribution — the top word dominates.
- A high temperature (e.g., 1.5) flattens the distribution — more words become viable.
- Temperature = 0 → always picks the single most probable word (called greedy decoding).
Top-K Sampling: Instead of considering all possible words, the model only picks from the top K most likely words. This prevents very unlikely words from ever being chosen.
Top-P (Nucleus) Sampling: Instead of a fixed count like Top-K, the model picks from the smallest group of words whose combined probability adds up to P (e.g., 90%). This is a more flexible and nuanced approach.
Greedy vs. Beam Search:
- Greedy Decoding: Always pick the single most probable token at each step. Fast, but can miss globally optimal sequences.
- Beam Search: Keep track of the top N best partial sequences at each step and choose the best overall. Slower, but often produces higher-quality output for tasks like translation.

💡 Example — Predicting the next word for "The sky is ___":
Model's probability scores:
  "blue"     → 55%
  "clear"    → 25%
  "cloudy"   → 15%
  "falling"  →  3%
  "delicious"→  0.1%

Temperature = 0.2 (low) → almost always picks "blue"  (safe, predictable)
Temperature = 1.5 (high) → might pick "cloudy" or even "falling" (creative)
Top-K = 2               → only considers "blue" and "clear"
Top-P = 0.80            → only considers "blue" + "clear" (80% combined)
📊 Top-k vs. Top-p Comparison:

Aspect Top-k Top-p (Nucleus)

Selection method Fixed number of tokens Dynamic (based on probability mass)

Adaptability Poor Excellent

When model is confident Still forces k tokens Uses very few tokens

When model is uncertain Limits to k tokens Can use many tokens

Risk of bad tokens Medium Lower

Best for Simple control Natural, high-quality text

💡 Example — Greedy vs. Beam Search:
Input: "I want to"

Greedy (pick best at each step):
  Step 1: "go" (40%)  → "I want to go"
  Step 2: "to" (35%)  → "I want to go to"
  Step 3: "the" (50%) → "I want to go to the"
  Result: "I want to go to the" — decent but narrow

Beam Search (track top 3 paths):
  Path A: "go"   (40%) → "go home"    (18%) → score: 7.2
  Path B: "eat"  (30%) → "eat dinner" (25%) → score: 7.5  ← winner
  Path C: "know" (20%) → "know more"  (15%) → score: 3.0
  Result: "I want to eat dinner" — better overall sentence

Aspect	Top-k	Top-p (Nucleus)
Selection method	Fixed number of tokens	Dynamic (based on probability mass)
Adaptability	Poor	Excellent
When model is confident	Still forces k tokens	Uses very few tokens
When model is uncertain	Limits to k tokens	Can use many tokens
Risk of bad tokens	Medium	Lower
Best for	Simple control	Natural, high-quality text

3. Vectors & Embeddings

How does AI understand meaning, not just words?

A computer cannot inherently understand that "King" and "Queen" are related, or that "cat" and "dog" are both animals. Embeddings solve this problem.

What is a Vector? A vector is simply a list of numbers (e.g., [0.2, -0.5, 0.8, ...]). In AI, every word or concept is converted into a vector with hundreds or thousands of numbers. Each number in the vector represents some learned aspect of the word's meaning.
Dimensionality: The number of values in a vector. GPT-3 uses 12,288 dimensions per token. Higher dimensions can capture more nuance but require more computation.
Embeddings: These are vector representations where words with similar meanings end up having mathematically similar vectors (i.e., they are "close" to each other in vector space). Embeddings are learned during training — the model figures out the best numerical representation for each word.
Types of Embeddings:
- Word Embeddings: Each word gets a single fixed vector (e.g., Word2Vec, GloVe). Limitation: "bank" has the same vector whether it means "river bank" or "financial bank."
- Contextual Embeddings: Each word gets a different vector depending on its context (e.g., BERT, GPT). This solved the ambiguity problem.
- Sentence / Document Embeddings: Entire sentences or documents are represented as a single vector, useful for search and comparison.
Cosine Similarity: The most common way to measure how similar two vectors are. It calculates the angle between them. A cosine similarity of 1.0 means identical direction (very similar), 0 means unrelated, and -1 means opposite.
Semantic Similarity: Because embeddings capture meaning, an AI can calculate that "Paris" - "France" + "Germany" ≈ "Berlin". This is how AI understands relationships between concepts.
Why this matters for RAG: Vector databases store these embeddings, allowing an AI to semantically search your documents — finding related content even if the exact words don't match.

💡 Example — Words as coordinates in space:

Imagine a 2D map where similar words are placed close together:

       [Royalty Axis]
            ↑
   Queen •  | • King
            |
  ──────────┼──────────→ [Gender Axis]
            |
   Woman •  | • Man
            |

"King" - "Man" + "Woman" ≈ "Queen"
The math works because similar concepts cluster together in vector space.

💡 Example — Cosine Similarity in practice:

Embedding for "dog":    [0.8,  0.3, -0.1]
Embedding for "puppy":  [0.75, 0.35, -0.05]
Embedding for "laptop": [-0.2, 0.9,  0.6]

cosine_similarity("dog", "puppy")  = 0.99  → very similar ✓
cosine_similarity("dog", "laptop") = 0.12  → very different ✗

This is how a search engine knows that a query for "puppy care"
should also return results about "dog health" — even though the
exact words don't match.

4. Algebra & Model Formulas

The math inside a neural network.

At its core, a neural network is just a series of mathematical functions applied one after another.

The Core Formula: The fundamental building block of a neural network is: y = wx + b
- x = the input (your data)
- w = weights (values the model learns during training to adjust its behavior)
- b = bias (an offset value that helps the model fit the data better)
- y = the output (the model's prediction)
With Multiple Inputs: In real networks, a neuron has many inputs: y = w₁x₁ + w₂x₂ + w₃x₃ + ... + b
Summation (Σ): Neurons in a network receive multiple inputs and add them all together (as a weighted sum) before passing the result forward: y = Σ(wᵢxᵢ) + b
Activation Functions: After the summation, a non-linear function is applied to the result. This is what allows the network to learn complex, non-linear patterns in data. Without activation functions, a neural network would just be a linear equation, no matter how many layers you stack.

Common Activation Functions:

| Function | Formula | Range | Used For |
|---|---|---|---|
| ReLU | max(0, x) | [0, ∞) | Hidden layers (most common) |
| Sigmoid | 1 / (1 + e⁻ˣ) | (0, 1) | Binary classification outputs |
| Tanh | (eˣ - e⁻ˣ) / (eˣ + e⁻ˣ) | (-1, 1) | Hidden layers, LSTMs |
| Softmax | eˣⁱ / Σeˣʲ | (0, 1), sums to 1 | Multi-class outputs |
| GELU | x · Φ(x) | (-0.17, ∞) | Transformers (GPT, BERT) |

Layers: A neural network is made of stacked layers. Each layer applies its own wx + b + activation. The output of one layer becomes the input to the next.
- Input Layer: Receives the raw data.
- Hidden Layers: The layers between input and output where the actual "learning" happens. More layers = deeper network = ability to learn more complex patterns.
- Output Layer: Produces the final prediction.

💡 Example — Predicting house price (y = wx + b):

Input (x):   150  (house size in m²)
Weight (w):  0.5  (learned: each m² adds $500)
Bias (b):    20   (learned: base price is $20k)

y = 0.5 × 150 + 20 = 95  → Predicted price: $95,000

During training, 'w' and 'b' are adjusted thousands of times
until predictions match the real prices in the dataset.

💡 Example — Why non-linearity (activation) matters:

Without activation (just stacking y = wx + b):
  Layer 1: y = 2x + 1
  Layer 2: y = 3(2x + 1) + 5 = 6x + 8
  → Still just a straight line! No matter how many layers.

With ReLU activation:
  Layer 1: y = ReLU(2x + 1) = max(0, 2x + 1)
  Layer 2: y = 3 · max(0, 2x + 1) + 5
  → Now the network can model curves, bends, and complex shapes!

This is why we need activation functions — they let the network
learn patterns that are NOT simple straight lines.

5. Statistics

Understanding the shape of your data.

Statistics are used to analyze and understand the data that is used to train AI models. Knowing the statistical properties of your data directly impacts model quality.

Mean (Average): The central value of a dataset. Calculated by summing all values and dividing by the count. In AI, model weights are often initialized near a mean of 0.
Variance: The average of the squared differences from the mean. Tells you how much the data values vary. High variance in training data can make a model unstable.
Normal Distribution (Bell Curve): Many real-world datasets follow this pattern, where most values cluster around the average (mean) and fewer values exist at the extremes.
- 68-95-99.7 Rule: In a normal distribution, 68% of data falls within 1 standard deviation of the mean, 95% within 2, and 99.7% within 3.
Standard Deviation (σ): The square root of variance. A more intuitive measure of spread because it's in the same unit as the data.
- A low σ means data points are clustered close to the mean.
- A high σ means they are spread out widely.
Skewness: A measure of how asymmetric a distribution is. Understanding skewness is critical for identifying and fixing data quality issues before training a model.
- Right-skewed: Tail extends to the right (e.g., income data — most people earn average, few earn millions).
- Left-skewed: Tail extends to the left (e.g., age at retirement — most retire at 60-65, few retire at 30).
Normalization & Standardization: Techniques to scale data before training:
- Min-Max Normalization: Scales values to a [0, 1] range. x_new = (x - min) / (max - min)
- Z-Score Standardization: Scales values to have mean=0 and σ=1. x_new = (x - mean) / σ
- Why it matters: If one input feature ranges from 0-1 and another from 0-1,000,000, the model will be overwhelmed by the larger feature. Normalization puts all features on an equal footing.
Batch Normalization: A technique used inside neural networks that normalizes the output of each layer before passing it to the next. This dramatically speeds up training and makes networks more stable.

💡 Example — Normal Distribution of user response lengths:

       Most users write medium-length messages
                        ↓
   |         ▂▄█▄▂
   |       ▂██████▂
   |     ▄██████████▄
   |___▄████████████████▄___
       5  10  20  30  40  (words)
       ↑                ↑
     Very           Very long
     short         (rare)
     (rare)

68-95-99.7 Rule:
  68% of messages are 15-25 words  (within 1σ of mean=20)
  95% of messages are 10-30 words  (within 2σ)
  99.7% are 5-35 words             (within 3σ)

💡 Example — Why Normalization matters:

Raw Features for a model predicting salary:
  Age:              [25, 30, 45, 50]         ← range: 25-50
  Years of Exp:     [2, 5, 18, 22]           ← range: 2-22
  GitHub Commits:   [100, 500, 8000, 12000]  ← range: 100-12000

Without normalization: the model thinks "GitHub Commits" is
240x more important than "Age" just because the numbers are bigger!

After Min-Max Normalization (all become 0-1):
  Age:              [0.0, 0.2, 0.8, 1.0]
  Years of Exp:     [0.0, 0.15, 0.8, 1.0]
  GitHub Commits:   [0.0, 0.034, 0.66, 1.0]

Now all features are on equal footing ✓

6. Matrices & Linear Algebra

How AI handles data at massive scale.

Training AI on millions of data points simultaneously requires extremely efficient computation. Matrices make this possible.

Scalar, Vector, Matrix, Tensor:
- Scalar: A single number (e.g., 5).
- Vector: A 1D array of numbers (e.g., [1, 2, 3]).
- Matrix: A 2D grid of numbers (rows × columns).
- Tensor: A generalization — can be any number of dimensions. A 3D tensor is a "stack of matrices." All data in deep learning frameworks (PyTorch, TensorFlow) is represented as tensors.
Matrix Multiplication: The core operation in neural networks. When a model processes a batch of inputs through a layer, it's performing matrix multiplication: Output = Input × Weights + Bias.
- Rule: To multiply matrix A (m×n) by matrix B (n×p), the inner dimensions must match. The result is (m×p).
GPU Parallelism: Graphics Processing Units (GPUs) are extremely efficient at performing thousands of matrix operations simultaneously (in parallel), which is why they are essential for AI training. A CPU processes operations one-by-one; a GPU processes entire matrices at once.
Dot Product: The sum of element-wise multiplication of two vectors. It measures how "aligned" two vectors are. This is the fundamental building block of attention.
- [1, 2, 3] · [4, 5, 6] = (1×4) + (2×5) + (3×6) = 32
Transpose: Flipping a matrix so rows become columns and vice versa. Written as Aᵀ. Essential for many neural network operations (e.g., computing attention scores).
Softmax Function: A function applied to the final output layer of a model that converts a list of raw scores (logits) into a probability distribution (all values sum to 1), making it easy to select the most likely prediction.
Attention Mechanism (Query, Key, Value): The core of the Transformer architecture. This is perhaps the most important concept in modern AI.
- How it works: For each token, the model creates three vectors:
- Query (Q): "What am I looking for?"
- Key (K): "What information do I have?"
- Value (V): "What is the actual content I will use?"
- The Attention Formula: Attention(Q, K, V) = softmax(QKᵀ / √dₖ) × V
- QKᵀ = dot product of queries and keys → produces attention scores (how relevant is each token to every other token)
- / √dₖ = scaling factor to prevent scores from getting too large (dₖ = dimension of key vectors)
- softmax(...) = normalizes scores to probabilities
- × V = weighted sum of values using those probabilities
- Multi-Head Attention: Instead of computing attention once, the model does it N times in parallel with different learned projections ("heads"), then concatenates the results. This lets the model focus on different types of relationships simultaneously (e.g., one head tracks grammar, another tracks meaning, another tracks position).
Positional Encoding: Since Transformers process all tokens simultaneously (not sequentially like RNNs), they have no inherent sense of word order. Positional encodings are special vectors added to the input embeddings to tell the model the position of each token in the sequence.

💡 Example — Matrix Multiplication in a neural network layer:

Input batch (2 sentences, 3 features each):     Weights (3 inputs → 2 outputs):

X = | 1  2  3 |                                  W = | 0.5  0.1 |
    | 4  5  6 |                                      | 0.3  0.7 |
    (2×3)                                            | 0.8  0.2 |
                                                     (3×2)
Output = X × W

  | (1×0.5+2×0.3+3×0.8)  (1×0.1+2×0.7+3×0.2) |     | 3.5  2.1 |
  | (4×0.5+5×0.3+6×0.8)  (4×0.1+5×0.7+6×0.2) |  =  | 8.3  5.1 |
  (2×2)                                              (2×2)

Both sentences processed AT THE SAME TIME — this is why GPUs are fast.

💡 Example — Softmax converting raw scores to probabilities:

Raw model scores (logits):
  "cat"  →  3.2
  "dog"  →  1.8
  "car"  →  0.5

After Softmax:
  "cat"  → 68%  ← highest probability, model picks this
  "dog"  → 26%
  "car"  →  6%
  Total  = 100% ✓

💡 Example — Attention in the sentence "The animal didn't cross the street because **it was too tired":**

When the model processes "it", attention helps it look back:

  "The"(2%) "animal"(60%) "didn't"(3%) "cross"(5%)
  "the"(2%) "street"(8%) "because"(5%) "it"(15%)

The model correctly identifies "it" = "animal", not "street"
— because attention assigns higher weight to "animal".

💡 Example — Multi-Head Attention (simplified):

Sentence: "The bank was flooded after the river overflowed"

Head 1 (Grammatical):  "bank" attends to → "was" (subject-verb)
Head 2 (Semantic):     "bank" attends to → "river" (meaning = river bank)
Head 3 (Positional):   "bank" attends to → "The" (nearby context)

Combined: The model understands "bank" = river bank, not financial bank.
Multiple perspectives = better understanding.

7. Calculus & Optimization

How does a model actually learn?

Learning in AI is the process of gradually adjusting the model's internal parameters (weights) to make better predictions. Calculus is the tool used to determine how to adjust them.

Loss Function: A formula that measures how wrong the model's prediction is compared to the actual correct answer. The goal of training is to minimize this value.

Common Loss Functions:

| Loss Function | Used For | What It Measures |
|---|---|---|
| MSE (Mean Squared Error) | Regression (predicting numbers) | Average of squared differences |
| Cross-Entropy Loss | Classification (predicting categories) | Difference between predicted and actual probability distributions |
| Binary Cross-Entropy | Yes/No classification | Cross-Entropy for 2 classes |
| Contrastive Loss | Embedding models | Distance between similar vs. dissimilar pairs |

Derivative / Gradient: The derivative tells us the rate of change — how much the loss changes if we slightly adjust a weight. The gradient is a vector of all partial derivatives across all weights.
- If the gradient is positive → the weight is making the loss go up → decrease it.
- If the gradient is negative → the weight is making the loss go down → increase it.
Backpropagation: The algorithm that efficiently calculates gradients for every weight in the network by working backward from the output layer to the input layer, using the chain rule of calculus.
- The Chain Rule: If y = f(g(x)), then dy/dx = f'(g(x)) × g'(x). In a deep network with many layers, the chain rule is applied repeatedly to propagate the error signal back through each layer.
Gradient Descent: The core optimization algorithm. After calculating the gradients, we take a small step in the direction that reduces the loss. Repeat this process millions of times, and the model progressively improves.

Variants of Gradient Descent:

| Variant | Description | Pros/Cons |
|---|---|---|
| Batch GD | Uses ALL training data per step | Accurate but very slow on large datasets |
| Stochastic GD (SGD) | Uses ONE random sample per step | Very fast but noisy/unstable |
| Mini-Batch GD | Uses a small batch (e.g., 32 samples) | Best balance — standard in practice |
| Adam | Adaptive learning rate per parameter | Most popular optimizer; fast convergence |

Learning Rate (α): A hyperparameter that controls how large each step in gradient descent is. Too large, and the model overshoots and may never converge. Too small, and training is extremely slow.
- Learning Rate Scheduling: Strategies to change the learning rate during training:
- Warmup: Start with a very small LR, then gradually increase. Prevents early instability.
- Decay: Gradually reduce LR as training progresses to fine-tune final weights.
- Cosine Annealing: LR follows a cosine curve — starts high, smoothly decreases, optionally restarts.
Vanishing / Exploding Gradients: In very deep networks, gradients can become extremely small (vanishing) or extremely large (exploding) as they pass through many layers during backpropagation.
- Vanishing: Early layers stop learning because the gradient signal is too weak.
- Exploding: Weights blow up to infinity, causing NaN errors.
- Solutions: ReLU activation (prevents vanishing), gradient clipping (prevents exploding), residual connections (Skip connections, as used in Transformers).

💡 Example — Gradient Descent as rolling a ball downhill:

Imagine a valley (the loss landscape):

  Loss
   |  \         /
   |   \       /
   |    \     /
   |     \   /
   |      \_/   ← Minimum loss (best model weights)
   └──────────────── Weights

The "ball" = model's current weights
Gradient   = slope at the ball's current position (which way is "down"?)
Step size  = Learning Rate

Too large a step → overshoots the valley, bounces around forever
Too small a step → takes forever to reach the bottom
Just right       → smoothly rolls to the minimum ✓

💡 Example — Backpropagation (Chain Rule applied to a 3-layer network):

Forward Pass:
  Input → [Layer 1] → [Layer 2] → [Layer 3] → Prediction → Loss = 5.2

Backward Pass (backpropagation):
  Loss = 5.2
  ← How much did Layer 3 contribute to this error?  → adjust Layer 3 weights
  ← How much did Layer 2 contribute?                → adjust Layer 2 weights
  ← How much did Layer 1 contribute?                → adjust Layer 1 weights

Each layer's contribution is calculated using the Chain Rule:
  ∂Loss/∂w₁ = ∂Loss/∂Layer3 × ∂Layer3/∂Layer2 × ∂Layer2/∂w₁

This is how error signals "propagate back" through the network.

8. Information Theory

Measuring uncertainty in AI.

Information theory provides mathematical tools to quantify how much uncertainty exists in a probability distribution — crucial for evaluating model quality.

Entropy (H): Measures the average amount of uncertainty or "randomness" in a system.
- Formula: H(X) = -Σ p(x) × log₂(p(x))
- A high-entropy model is very uncertain about its predictions.
- A low-entropy model is very confident.
- Maximum entropy = uniform distribution (all outcomes equally likely).
- Practical use: During training, you want the model's entropy on correct answers to decrease (becoming more confident about the right answer).
Cross-Entropy: Measures the difference between the true distribution and the predicted distribution. This is the most commonly used loss function for classification tasks and language models.
- Formula: H(P, Q) = -Σ p(x) × log₂(q(x)) where P is the true distribution and Q is the predicted.
- A perfect model has cross-entropy equal to the true entropy.
- A bad model has much higher cross-entropy.
Perplexity: A direct measure of how well a language model predicts a sample of text. Mathematically, it's 2^(cross-entropy).
- A lower perplexity score means the model is better at predicting the text and is less "surprised" by it.
- Intuition: A perplexity of 10 means the model is as confused as if it had to choose uniformly among 10 options at each step. A perplexity of 100 means it's choosing among 100 options. Lower is better.
KL Divergence (Kullback-Leibler Divergence): Measures the difference between two probability distributions. It is NOT symmetric: KL(P||Q) ≠ KL(Q||P).
- Formula: KL(P||Q) = Σ p(x) × log(p(x) / q(x))
- Use in RLHF: When fine-tuning a model with Reinforcement Learning from Human Feedback, KL divergence is used as a penalty to prevent the model from changing too much from its original behavior.
- Use in VAEs: Variational Autoencoders use KL divergence to ensure the learned data representation stays close to a normal distribution.
Mutual Information: Measures how much knowing one variable tells you about another. If two variables share a lot of mutual information, they are strongly related. Used in feature selection and understanding what a model has learned.

💡 Example — Entropy comparison:

Fair coin flip:
  P(heads) = 0.5, P(tails) = 0.5
  H = -(0.5 × log₂(0.5) + 0.5 × log₂(0.5)) = 1.0 bit
  → Maximum uncertainty (could be either outcome)

Biased coin:
  P(heads) = 0.99, P(tails) = 0.01
  H = -(0.99 × log₂(0.99) + 0.01 × log₂(0.01)) = 0.08 bits
  → Very low uncertainty (almost always heads)

AI Application: When a model is well-trained, its predictions
should have LOW entropy on correct answers.

💡 Example — Perplexity comparison:

Sentence: "The cat sat on the ___"

Good Model (low perplexity):
  "mat" → 60%, "floor" → 20%, "roof" → 10% ...
  Model is NOT surprised. Perplexity ≈ 5

Bad Model (high perplexity):
  "mat" → 8%, "democracy" → 7%, "blue" → 6% ...
  Model is very confused. Perplexity ≈ 500

Lower perplexity = better language understanding ✓

💡 Example — KL Divergence in RLHF:

Original Model (before fine-tuning):
  P("thank you") = 30%, P("thanks") = 25%, P("ok") = 20%

Fine-tuned Model (after RLHF):
  Q("thank you") = 80%, Q("thanks") = 15%, Q("ok") = 2%

KL(P||Q) = 0.82  → Significant drift from original behavior

If KL > threshold → apply penalty to prevent the model from
becoming too different (could lose general capabilities)

🧠 The Complete Training Loop

Putting it all together — how a model actually trains from start to finish.

Understanding each math concept individually is important, but the real power comes from seeing how they all work together in the training loop:

┌─────────────────────────────────────────────────────────────────┐
│                     THE TRAINING LOOP                           │
│                                                                 │
│  1. INPUT                                                       │
│     Raw text → Tokenize → Token IDs → Embeddings (vectors)     │
│     (Encoding)  (BPE)      (Lookup)    (Learned vectors)        │
│                                                                 │
│  2. FORWARD PASS                                                │
│     Embeddings + Positional Encoding                            │
│        → Multi-Head Attention (Q, K, V + Softmax)               │
│        → Feed-Forward layers (wx + b → Activation → wx + b)    │
│        → Repeat N times (e.g., 96 layers for GPT-4)            │
│        → Final Softmax → Probability distribution over vocab    │
│     (Linear Algebra + Algebra + Probability)                    │
│                                                                 │
│  3. COMPUTE LOSS                                                │
│     Compare prediction vs. actual next token                    │
│     Loss = Cross-Entropy(predicted_probs, actual_token)         │
│     (Information Theory + Statistics)                            │
│                                                                 │
│  4. BACKWARD PASS (Backpropagation)                             │
│     Calculate gradients for ALL weights using Chain Rule         │
│     ∂Loss/∂w for every weight in every layer                    │
│     (Calculus)                                                  │
│                                                                 │
│  5. UPDATE WEIGHTS                                              │
│     w_new = w_old - learning_rate × gradient                    │
│     (Using Adam or SGD optimizer)                               │
│     (Gradient Descent / Optimization)                           │
│                                                                 │
│  6. REPEAT steps 1-5 for millions of batches                    │
│     until loss is sufficiently low                              │
└─────────────────────────────────────────────────────────────────┘

⚠️ Common Pitfalls in Model Training

Understanding these common issues will save you hours of debugging:

Overfitting vs. Underfitting

Concept	What Happens	Symptom	Solution
Overfitting	Model memorizes the training data instead of learning general patterns	Training loss ↓, Validation loss ↑	Dropout, Data Augmentation, Early Stopping, Regularization
Underfitting	Model is too simple to capture the patterns in the data	Both training and validation loss remain high	Increase model size, Train longer, Better features

💡 Example — Overfitting vs. Underfitting:

Imagine fitting a curve through data points:

Underfitting:                     Good Fit:                    Overfitting:
 (straight line through           (smooth curve through        (wiggly line through
  scattered points)                the general trend)           EVERY point exactly)

   •  •                              •  •                       •──•
    ───────── •                    ╱  ╲                        ╱    ╲ •
   •     •                       •     •                     •      ╲╱
                                                                    •
   "Too simple"                  "Just right"                "Memorized noise"
   High train error              Low train error              Zero train error
   High test error               Low test error               High test error

Regularization Techniques

L1 Regularization (Lasso): Adds the sum of absolute weights to the loss. Encourages many weights to become exactly 0 (sparse model). Useful for feature selection.
L2 Regularization (Ridge): Adds the sum of squared weights to the loss. Encourages all weights to be small but non-zero. Most common.
Dropout: During training, randomly "turn off" a percentage of neurons in each layer (e.g., 20%). This forces the network to not rely on any single neuron and builds redundancy. Turned off during inference.
Early Stopping: Monitor validation loss during training. If it starts going up while training loss keeps going down → stop training. You've found the sweet spot before overfitting begins.

💡 Example — Dropout:

Normal forward pass:          With Dropout (20%):

 [N1]──[N4]──[N7]             [N1]──[  ]──[N7]     ← N4 turned off
 [N2]──[N5]──[N8]             [  ]──[N5]──[N8]     ← N2 turned off
 [N3]──[N6]──[N9]             [N3]──[N6]──[  ]     ← N9 turned off

Each training step randomly disables different neurons.
This prevents the network from "memorizing" via specific neurons
and forces it to learn more robust, general patterns.

💡 Key Takeaways

Concept	What it powers in AI
Number Systems & Encoding	How text is converted into data a model can process
Probability	How models generate and sample their responses
Vectors & Embeddings	How AI understands semantic meaning and similarity
Algebra & Activation	The core computations inside every neural network layer
Statistics & Normalization	Analyzing data quality and ensuring stable training
Linear Algebra & Attention	Enabling massively parallel GPU computation and context understanding
Calculus & Optimization	How models learn from mistakes and improve over time
Information Theory	Measuring and evaluating model confidence and quality
Training Loop	How all concepts connect into an end-to-end learning system
Regularization	Preventing models from memorizing data instead of learning

For Aspiring AI Engineers: Mastering these fundamentals is more important than jumping directly into complex model architectures. Once you understand why the math works, complex topics like Transformers and fine-tuning become significantly easier to learn.

🚀 Advanced Roadmap (Next Steps)

Once you are comfortable with the concepts above, consider exploring these more advanced mathematical topics used in AI research:

Eigenvalues & Eigenvectors: Used in dimensionality reduction and understanding how data transforms through a network. An eigenvector is a direction that remains unchanged when a matrix transformation is applied; the eigenvalue tells you by how much it was scaled.
Principal Component Analysis (PCA): A technique to reduce the number of features in a dataset while retaining the most important information. Uses eigenvalues to find the directions of maximum variance.
Singular Value Decomposition (SVD): A factorization technique that decomposes any matrix into three simpler matrices. Used in recommendation systems (like Netflix), data compression, and LoRA (Low-Rank Adaptation for efficient LLM fine-tuning).
Matrix Factorization: A method used in recommendation systems and for compressing large model weights into smaller, faster representations.
Fourier Transforms: Used in signal processing and some attention variants to efficiently capture patterns at different frequency scales.
Bayesian Statistics: A framework for updating beliefs based on new evidence. Used in uncertainty estimation and some reinforcement learning algorithms.
Markov Chains & Monte Carlo Methods: Used in sampling algorithms, reinforcement learning, and some text generation strategies.
Convex Optimization: The mathematical theory behind why gradient descent works for certain types of problems and what can go wrong in non-convex landscapes (like deep learning).

🐍 Python Essentials for GenAI

Ajmal Hasan — Sun, 21 Jun 2026 17:01:32 +0000

Everything a JS/React Native Developer Needs to Know

Audience: You know JavaScript/TypeScript. This guide maps Python concepts to what you already know.

Goal: Get comfortable with Python patterns used heavily in LangChain, LangGraph, and GenAI tooling.

1. JavaScript → Python Mental Model

Syntax Cheat Sheet

# ─────────────────────────────────────────────────
# JS/TS → Python Translation Table
# ─────────────────────────────────────────────────

# Variables
name = "Ajmal"              # let name = "Ajmal"
age: int = 28               # let age: number = 28
PI = 3.14159                # const PI = 3.14159 (convention: UPPERCASE = constant)

# Strings (f-strings = template literals)
greeting = f"Hello, {name}" # `Hello, ${name}`

# Multiline strings
text = """
This is a
multiline string
"""                          # Same as backtick strings in JS

# Boolean
is_active = True             # true → True, false → False, null → None

# None (like null/undefined)
value = None                 # let value = null

# Print
print("Hello")              # console.log("Hello")
print(f"Name: {name}")      # console.log(`Name: ${name}`)

Indentation = Curly Braces

# Python uses INDENTATION instead of {}
# This is the #1 thing to get used to

# JavaScript:
# if (age > 18) {
#     console.log("Adult");
# } else {
#     console.log("Minor");
# }

# Python:
if age > 18:
    print("Adult")
else:
    print("Minor")

# Functions
def greet(name: str) -> str:    # function greet(name: string): string
    return f"Hello, {name}!"

# For loops
for i in range(5):              # for (let i = 0; i < 5; i++)
    print(i)

for item in my_list:            # for (const item of myList)
    print(item)

# While loops
while count > 0:                # while (count > 0) {
    count -= 1                  #     count--;
                                # }

Truthiness Differences

# Python falsy values:
# False, None, 0, 0.0, "", [], {}, set()

# ⚠️ Key difference from JS:
# JS:  [] is truthy     → if ([]) { "runs!" }
# Py:  [] is falsy      → if []:   "NEVER runs"

# JS:  {} is truthy     → if ({}) { "runs!" }
# Py:  {} is falsy      → if {}:   "NEVER runs"

# Check for None specifically:
if value is None:        # NOT: if value == None
    print("No value")

if value is not None:    # NOT: if value != None
    print("Has value")

2. Data Structures

Lists (= JavaScript Arrays)

# Creating lists
fruits = ["apple", "banana", "cherry"]    # const fruits = ["apple", "banana", "cherry"]
empty = []                                 # const empty = []

# Accessing
first = fruits[0]          # fruits[0]
last = fruits[-1]          # fruits[fruits.length - 1]  ← Python has negative indexing!

# Slicing (Python superpower — no equivalent in JS)
fruits[1:3]                # ["banana", "cherry"]  — from index 1 up to (not including) 3
fruits[:2]                 # ["apple", "banana"]   — first 2
fruits[1:]                 # ["banana", "cherry"]  — from index 1 to end
fruits[-2:]                # ["banana", "cherry"]  — last 2

# Adding
fruits.append("date")              # fruits.push("date")
fruits.insert(0, "avocado")        # fruits.unshift("avocado")
fruits.extend(["fig", "grape"])    # fruits.push(...["fig", "grape"])

# Removing
fruits.remove("banana")           # const i = fruits.indexOf("banana"); fruits.splice(i,1)
fruits.pop()                       # fruits.pop()
fruits.pop(0)                      # fruits.shift()

# Checking
"apple" in fruits                  # fruits.includes("apple")
len(fruits)                        # fruits.length

# Iterating
for fruit in fruits:               # for (const fruit of fruits)
    print(fruit)

for i, fruit in enumerate(fruits): # fruits.forEach((fruit, i) => ...)
    print(f"{i}: {fruit}")

List Comprehensions (Python Superpower)

# JS: const doubled = numbers.map(n => n * 2)
doubled = [n * 2 for n in numbers]

# JS: const evens = numbers.filter(n => n % 2 === 0)
evens = [n for n in numbers if n % 2 == 0]

# JS: const results = numbers.filter(n => n > 5).map(n => n * 2)
results = [n * 2 for n in numbers if n > 5]

# Nested comprehension
# JS: matrix.flat().map(x => x * 2)
flat = [x * 2 for row in matrix for x in row]

# Dict comprehension
# JS: Object.fromEntries(items.map(item => [item.id, item]))
lookup = {item.id: item for item in items}

Dictionaries (= JavaScript Objects)

# Creating dicts
person = {
    "name": "Ajmal",
    "age": 28,
    "skills": ["Python", "React Native"],
}

# ⚠️ Keys MUST be strings (or other hashable types) — no unquoted keys like JS

# Accessing
person["name"]                    # person.name or person["name"]
person.get("name")                # Same, but returns None instead of KeyError
person.get("email", "N/A")       # Default value if key missing

# Setting
person["email"] = "a@b.com"      # person.email = "a@b.com"

# Checking
"name" in person                  # "name" in person (same!)

# Iterating
for key in person:                     # for (const key in person)
    print(key)

for key, value in person.items():      # Object.entries(person).forEach(([k,v]) => ...)
    print(f"{key}: {value}")

# Merging (Python 3.9+)
merged = {**dict1, **dict2}            # const merged = {...obj1, ...obj2}
merged = dict1 | dict2                 # Python 3.9+ pipe merge operator

# Destructuring
name = person["name"]                  # const { name } = person
# Python doesn't have object destructuring like JS
# But you can unpack dicts to function kwargs:
def greet(name, age, **kwargs):
    print(f"{name}, {age}")

greet(**person)                        # Unpacks dict as keyword arguments

Tuples (Immutable Lists — No JS Equivalent)

# Tuples are like frozen arrays — can't modify after creation
point = (10, 20)
rgb = (255, 128, 0)

x, y = point           # Destructuring! → x=10, y=20

# Used for: returning multiple values, dict keys, immutable sequences
def get_user():
    return "Ajmal", 28  # Returns a tuple

name, age = get_user()  # Destructure the return value

# ⚠️ Single-element tuple needs trailing comma:
single = (42,)          # This is a tuple
not_tuple = (42)        # This is just the number 42

Sets (= JavaScript Sets)

unique = {1, 2, 3}                     # const unique = new Set([1, 2, 3])
unique.add(4)                           # unique.add(4)
unique.discard(2)                       # unique.delete(2)

# Set operations (Python is way better than JS here)
a = {1, 2, 3}
b = {2, 3, 4}
a | b           # Union: {1, 2, 3, 4}
a & b           # Intersection: {2, 3}
a - b           # Difference: {1}
a ^ b           # Symmetric diff: {1, 4}

# Great for deduplication
unique_items = list(set(items_with_dupes))

3. Functions

Function Definitions

# Basic function
def add(a: int, b: int) -> int:
    """Add two numbers."""          # Docstring (like JSDoc but built-in)
    return a + b

# Default parameters
def greet(name: str, greeting: str = "Hello") -> str:
    return f"{greeting}, {name}!"

# *args — like ...rest in JS
def sum_all(*numbers):              # function sumAll(...numbers)
    return sum(numbers)

sum_all(1, 2, 3, 4)  # 10

# **kwargs — named rest parameters (no JS equivalent)
def create_user(**kwargs):
    print(kwargs)  # {"name": "Ajmal", "age": 28}

create_user(name="Ajmal", age=28)

# Combining *args and **kwargs
def flexible(required, *args, **kwargs):
    print(f"Required: {required}")
    print(f"Extra positional: {args}")
    print(f"Extra keyword: {kwargs}")

flexible("hello", 1, 2, 3, debug=True, verbose=False)
# Required: hello
# Extra positional: (1, 2, 3)
# Extra keyword: {"debug": True, "verbose": False}

Lambda Functions (= Arrow Functions)

# JS: const double = (x) => x * 2
double = lambda x: x * 2

# JS: items.sort((a, b) => a.name.localeCompare(b.name))
items.sort(key=lambda x: x["name"])

# JS: items.filter(item => item.active)
active = list(filter(lambda item: item.active, items))

# ⚠️ Lambdas are single-expression only. For multi-line, use def.

Higher-Order Functions

# map, filter, reduce exist but list comprehensions are more Pythonic

# map
# JS:  numbers.map(n => n * 2)
# Py:  list(map(lambda n: n * 2, numbers))        ← works but ugly
# Py:  [n * 2 for n in numbers]                    ← Pythonic ✓

# filter
# JS:  numbers.filter(n => n > 5)
# Py:  list(filter(lambda n: n > 5, numbers))      ← works but ugly
# Py:  [n for n in numbers if n > 5]               ← Pythonic ✓

# reduce
from functools import reduce
# JS:  numbers.reduce((acc, n) => acc + n, 0)
total = reduce(lambda acc, n: acc + n, numbers, 0)
# Or just: total = sum(numbers)                    ← Pythonic ✓

4. Object-Oriented Python

Classes

# ─────────────────────────────────────────────────
# JS Class → Python Class
# ─────────────────────────────────────────────────

# JavaScript:
# class User {
#     constructor(name, email) {
#         this.name = name;
#         this.email = email;
#     }
#     greet() {
#         return `Hello, ${this.name}`;
#     }
# }

# Python:
class User:
    """A user in our system."""

    def __init__(self, name: str, email: str):   # constructor
        self.name = name                          # this.name = name
        self.email = email                        # this.email = email

    def greet(self) -> str:                       # methods always take 'self'
        return f"Hello, {self.name}"

    def __str__(self) -> str:                     # toString() equivalent
        return f"User({self.name}, {self.email})"

    def __repr__(self) -> str:                    # Developer-friendly string
        return f"User(name='{self.name}', email='{self.email}')"

user = User("Ajmal", "a@b.com")
print(user.greet())
print(user)         # Calls __str__

Inheritance

class Animal:
    def __init__(self, name: str):
        self.name = name

    def speak(self) -> str:
        raise NotImplementedError       # Abstract method

class Dog(Animal):                      # class Dog extends Animal
    def speak(self) -> str:
        return f"{self.name} says Woof!"

class Cat(Animal):
    def speak(self) -> str:
        return f"{self.name} says Meow!"

dog = Dog("Rex")
print(dog.speak())  # "Rex says Woof!"

Dataclasses (Like TypeScript Interfaces + Auto-Constructor)

from dataclasses import dataclass

# Instead of writing boilerplate __init__, __repr__, __eq__:
@dataclass
class Document:
    content: str
    source: str
    page: int = 0                    # Default value
    score: float = 0.0

# Auto-generates __init__, __repr__, __eq__
doc = Document(content="Hello", source="test.pdf", page=1)
print(doc)  # Document(content='Hello', source='test.pdf', page=1, score=0.0)

Pydantic (⭐ Critical for LangChain)

Pydantic is used everywhere in LangChain for data validation:

from pydantic import BaseModel, Field
from typing import Optional

class UserProfile(BaseModel):
    """User profile with validation."""
    name: str
    email: str
    age: int = Field(ge=0, le=150, description="User's age")
    bio: Optional[str] = None

# Valid — works fine
user = UserProfile(name="Ajmal", email="a@b.com", age=28)

# Invalid — raises ValidationError automatically!
try:
    bad = UserProfile(name="Ajmal", email="a@b.com", age=-5)
except Exception as e:
    print(e)  # age must be >= 0

# Parse from dict (like JSON deserialization)
data = {"name": "Ajmal", "email": "a@b.com", "age": 28}
user = UserProfile.model_validate(data)

# Parse from JSON string
json_str = '{"name": "Ajmal", "email": "a@b.com", "age": 28}'
user = UserProfile.model_validate_json(json_str)

# Convert to dict/JSON
user.model_dump()            # {"name": "Ajmal", "email": "a@b.com", ...}
user.model_dump_json()       # '{"name": "Ajmal", ...}'

# Get JSON schema (used by LLM structured output!)
UserProfile.model_json_schema()

Why Pydantic matters in GenAI:

LangChain tools use Pydantic for input schemas
Structured output from LLMs is validated with Pydantic
State definitions in LangGraph often use Pydantic
Configuration objects use Pydantic

5. Type Hints (= TypeScript Types)

from typing import (
    Optional,       # string | undefined
    Union,          # string | number
    Literal,        # "a" | "b" | "c"
    TypedDict,      # { name: string; age: number }
    Annotated,      # Used in LangGraph for state reducers
)

# Basic types
name: str = "Ajmal"
age: int = 28
score: float = 95.5
active: bool = True
items: list[str] = ["a", "b"]
lookup: dict[str, int] = {"a": 1}

# Optional (value or None)
email: Optional[str] = None          # string | undefined

# Union (multiple types)
id: Union[str, int] = "abc"          # string | number
# Python 3.10+: id: str | int = "abc"

# Literal (specific values only)
status: Literal["active", "inactive", "pending"] = "active"

# TypedDict (typed dictionaries — used in LangGraph state!)
class AgentState(TypedDict):
    messages: list
    query_type: str
    sources: list[str]

# Annotated (adds metadata to types — used in LangGraph!)
from langgraph.graph.message import add_messages

class State(TypedDict):
    messages: Annotated[list, add_messages]  # The add_messages is a "reducer"

# Function type hints
def process(data: list[str], limit: int = 10) -> dict[str, int]:
    ...

# Callable type (function as parameter)
from typing import Callable
def apply(func: Callable[[int], int], value: int) -> int:
    return func(value)

6. Decorators (Used Everywhere in GenAI)

# ─────────────────────────────────────────────────
# Decorators = Higher-order functions that wrap other functions
# Like HOCs in React, but for functions
# ─────────────────────────────────────────────────

# Basic decorator
def log_calls(func):
    """Log every time a function is called."""
    def wrapper(*args, **kwargs):
        print(f"Calling {func.__name__}...")
        result = func(*args, **kwargs)
        print(f"Done: {result}")
        return result
    return wrapper

@log_calls                    # Same as: greet = log_calls(greet)
def greet(name: str) -> str:
    return f"Hello, {name}"

greet("Ajmal")
# Output:
# Calling greet...
# Done: Hello, Ajmal

# ─────────────────────────────────────────────────
# REAL-WORLD: LangChain @tool decorator
# ─────────────────────────────────────────────────
from langchain_core.tools import tool

@tool
def calculator(expression: str) -> str:
    """Evaluate a math expression. Use for calculations."""
    return str(eval(expression))

# The @tool decorator:
# 1. Reads the function name → tool.name = "calculator"
# 2. Reads the docstring → tool.description = "Evaluate a math..."
# 3. Reads the type hints → tool.args = {"expression": {"type": "string"}}
# 4. Wraps the function so LangChain agents can call it

# ─────────────────────────────────────────────────
# Other decorators you'll see:
# ─────────────────────────────────────────────────
@property           # Getter (like a computed property in Vue)
@staticmethod       # No 'self' parameter (like static in JS)
@classmethod        # Takes 'cls' instead of 'self'
@dataclass          # Auto-generate __init__, __repr__, etc.
@pytest.fixture     # Test fixtures
@app.get("/")       # FastAPI route handlers

7. Generators & Iterators (For Streaming LLM Responses)

# Generators produce values lazily (one at a time)
# Critical for: streaming LLM tokens, processing large files

# Generator function (uses yield instead of return)
def count_up(n: int):
    """Generate numbers 0 to n-1."""
    i = 0
    while i < n:
        yield i      # Pauses here, returns i, resumes on next()
        i += 1

# Using a generator
for num in count_up(5):
    print(num)  # 0, 1, 2, 3, 4

# ─────────────────────────────────────────────────
# REAL-WORLD: Streaming LLM responses
# ─────────────────────────────────────────────────
# LangChain uses generators for streaming:

for chunk in llm.stream("Tell me a story"):
    print(chunk.content, end="", flush=True)

# Behind the scenes, this is a generator yielding tokens one by one

# Generator expression (like list comprehension, but lazy)
squares = (x**2 for x in range(1_000_000))  # No memory allocated for all values
first_10 = [next(squares) for _ in range(10)]

8. Context Managers (with statement)

# Context managers handle setup/cleanup automatically
# Like try-finally, but cleaner

# ─────────────────────────────────────────────────
# File I/O (most common use)
# ─────────────────────────────────────────────────

# ❌ Without context manager:
f = open("data.txt", "r")
content = f.read()
f.close()                  # Easy to forget!

# ✅ With context manager:
with open("data.txt", "r") as f:
    content = f.read()
# File is automatically closed, even if an exception occurs

# Writing files
with open("output.txt", "w") as f:
    f.write("Hello, World!\n")

# Reading JSON
import json
with open("config.json", "r") as f:
    config = json.load(f)

# Writing JSON
with open("output.json", "w") as f:
    json.dump(data, f, indent=2)

# ─────────────────────────────────────────────────
# You'll see context managers with:
# - Database connections
# - HTTP sessions
# - Temporary files
# - Lock management
# ─────────────────────────────────────────────────

9. Error Handling

# ─────────────────────────────────────────────────
# try/except (= try/catch in JS)
# ─────────────────────────────────────────────────

try:
    result = 10 / 0
except ZeroDivisionError:                    # catch specific error
    print("Can't divide by zero!")
except (ValueError, TypeError) as e:         # catch multiple
    print(f"Error: {e}")
except Exception as e:                       # catch-all (like catch(e) in JS)
    print(f"Unexpected error: {e}")
else:                                        # Runs if NO exception (no JS equivalent)
    print(f"Result: {result}")
finally:                                     # Always runs (same as JS)
    print("Done")

# ─────────────────────────────────────────────────
# Raising exceptions (= throw in JS)
# ─────────────────────────────────────────────────

def validate_age(age: int):
    if age < 0:
        raise ValueError(f"Age cannot be negative: {age}")
    return age

# Custom exceptions
class DocumentNotFoundError(Exception):
    """Raised when a document cannot be found in the knowledge base."""
    pass

# Real-world: LLM API error handling
from openai import RateLimitError, APIError
import time

def safe_llm_call(prompt: str, max_retries: int = 3) -> str:
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="gpt-4o-mini",
                messages=[{"role": "user", "content": prompt}],
            )
            return response.choices[0].message.content
        except RateLimitError:
            wait = 2 ** attempt
            print(f"Rate limited, waiting {wait}s...")
            time.sleep(wait)
        except APIError as e:
            if attempt == max_retries - 1:
                raise
            print(f"API error: {e}, retrying...")
    raise Exception("Max retries exceeded")

10. Async/Await (Same Concept as JS!)

import asyncio

# ─────────────────────────────────────────────────
# Python async is very similar to JS async/await
# ─────────────────────────────────────────────────

# JS:
# async function fetchData(url) {
#     const response = await fetch(url);
#     return await response.json();
# }

# Python:
async def fetch_data(url: str) -> dict:
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as response:
            return await response.json()

# Running async code
async def main():
    result = await fetch_data("https://api.example.com/data")
    print(result)

asyncio.run(main())

# ─────────────────────────────────────────────────
# Concurrent execution (like Promise.all)
# ─────────────────────────────────────────────────

async def process_batch():
    # JS: await Promise.all([task1(), task2(), task3()])
    results = await asyncio.gather(
        fetch_data("url1"),
        fetch_data("url2"),
        fetch_data("url3"),
    )
    return results

# ─────────────────────────────────────────────────
# LangChain async (used for parallel LLM calls)
# ─────────────────────────────────────────────────

# Most LangChain classes have async versions:
result = await llm.ainvoke(messages)          # Async invoke
results = await chain.abatch([input1, input2]) # Batch process
async for chunk in chain.astream(input):       # Async streaming
    print(chunk)

11. Modules & Imports

# ─────────────────────────────────────────────────
# Python imports vs JS imports
# ─────────────────────────────────────────────────

# JS: import { useState, useEffect } from 'react'
from langchain_openai import ChatOpenAI, OpenAIEmbeddings

# JS: import React from 'react'
import langchain

# JS: import * as utils from './utils'
from langchain import agents  # Access: agents.create_react_agent(...)

# JS: import { default as MyComponent } from './Component'
from langchain_openai import ChatOpenAI as LLM   # Alias

# Relative imports (within your project)
from .agents import orchestrator        # from ./agents import ...
from ..config import settings           # from ../config import ...

# ─────────────────────────────────────────────────
# __init__.py = index.js
# ─────────────────────────────────────────────────
# A folder with __init__.py is a Python "package" (like having index.js)
# src/
# ├── __init__.py          ← Makes 'src' importable
# ├── agents/
# │   ├── __init__.py      ← Makes 'agents' importable
# │   ├── rag_agent.py
# │   └── search_agent.py
# └── config.py

# ─────────────────────────────────────────────────
# if __name__ == "__main__": (entry point guard)
# ─────────────────────────────────────────────────
# This runs ONLY when the file is executed directly (not imported)

def main():
    print("Running as main script")

if __name__ == "__main__":
    main()
# Like: if (require.main === module) { main() }

12. Environment & Package Management

Virtual Environments (Like node_modules, but Cleaner)

# Create virtual environment
python -m venv .venv

# Activate (macOS/Linux)
source .venv/bin/activate

# Activate (Windows)
.venv\Scripts\activate

# Deactivate
deactivate

# ⚠️ ALWAYS activate venv before pip install
# Otherwise packages install globally (bad!)

pip (Like npm)

# npm install langchain    →    pip install langchain
# npm install              →    pip install -r requirements.txt
# npm install --save       →    pip install langchain && pip freeze > requirements.txt
# package.json             →    requirements.txt (or pyproject.toml)
# node_modules/            →    .venv/lib/

# Install specific version
pip install langchain==0.2.0

# Install from requirements.txt
pip install -r requirements.txt

# See installed packages
pip list

# Generate requirements.txt from current environment
pip freeze > requirements.txt

.env Files

# Install: pip install python-dotenv

# .env file:
# OPENAI_API_KEY=sk-your-key-here
# QDRANT_URL=http://localhost:6333

# Load in Python:
from dotenv import load_dotenv
import os

load_dotenv()  # Reads .env file into environment variables

api_key = os.getenv("OPENAI_API_KEY")
qdrant_url = os.getenv("QDRANT_URL", "http://localhost:6333")  # With default

13. Common Patterns in GenAI Code

Pattern 1: Method Chaining with LCEL (Pipe Operator)

# LangChain Expression Language uses | (pipe) like Unix pipes
# Similar to RxJS pipe() or lodash chain()

chain = prompt | llm | output_parser

# This means: prompt.invoke() → pass result to llm.invoke() → pass to parser
# Like: prompt.pipe(llm).pipe(output_parser)

Pattern 2: TypedDict for State (LangGraph)

from typing import TypedDict, Annotated

class AgentState(TypedDict):
    messages: Annotated[list, add_messages]  # Reducer: append new messages
    query_type: str                           # Replace on update

# This is like defining a Redux state shape with reducers

Pattern 3: Factory Functions

# Functions that create and return configured objects
def create_rag_chain(model: str = "gpt-4o", k: int = 4):
    llm = ChatOpenAI(model=model, temperature=0)
    retriever = vector_store.as_retriever(search_kwargs={"k": k})

    return (
        {"context": retriever | format_docs, "question": RunnablePassthrough()}
        | prompt
        | llm
        | StrOutputParser()
    )

chain = create_rag_chain(model="gpt-4o-mini", k=6)

Pattern 4: Callback / Event Handlers

# LangChain uses callbacks for logging, streaming, etc.
from langchain_core.callbacks import BaseCallbackHandler

class MyHandler(BaseCallbackHandler):
    def on_llm_start(self, serialized, prompts, **kwargs):
        print(f"LLM starting with {len(prompts)} prompts")

    def on_llm_end(self, response, **kwargs):
        print(f"LLM finished")

    def on_tool_start(self, serialized, input_str, **kwargs):
        print(f"Tool called: {serialized['name']}")

# Attach to LLM
llm = ChatOpenAI(model="gpt-4o", callbacks=[MyHandler()])

14. Essential Standard Library

# ─────────────────────────────────────────────────
# Modules you'll use constantly in GenAI work
# ─────────────────────────────────────────────────

import os                 # Environment vars, file paths
import json               # Parse/generate JSON
import time               # Sleep, timing
import logging            # Production logging
import hashlib            # Hashing (for caching)
from pathlib import Path  # Modern file path handling
from typing import *      # Type hints
from datetime import datetime  # Timestamps
from collections import defaultdict, Counter  # Useful data structures
from functools import reduce, lru_cache       # Functional utils + caching
from dataclasses import dataclass, field      # Data classes
import re                 # Regex
import uuid               # Unique IDs (for thread_ids, collection names)
import asyncio            # Async programming

# ─────────────────────────────────────────────────
# pathlib.Path (modern file handling)
# ─────────────────────────────────────────────────
from pathlib import Path

# Old way: os.path.join("data", "docs", "file.pdf")
# New way:
path = Path("data") / "docs" / "file.pdf"

path.exists()         # Does it exist?
path.is_file()        # Is it a file?
path.is_dir()         # Is it a directory?
path.suffix           # ".pdf"
path.stem             # "file"
path.parent           # Path("data/docs")
path.read_text()      # Read file contents as string
path.write_text(data) # Write string to file

# List all PDFs in a directory
pdfs = list(Path("docs").glob("**/*.pdf"))

15. Quick Reference Card

JS/TS	Python	Notes
`const` / `let`	just assign	No const keyword; UPPER_CASE = convention for constants
`===`	`==`	Python `==` compares values (like JS `===`)
`null` / `undefined`	`None`	Only one "nothing" value
`true` / `false`	`True` / `False`	Capitalized!
`console.log()`	`print()`
`typeof x`	`type(x)`
`x instanceof Y`	`isinstance(x, Y)`
`Array.isArray()`	`isinstance(x, list)`
`JSON.parse()`	`json.loads()`
`JSON.stringify()`	`json.dumps()`
`async/await`	`async/await`	Same concepts! Need `asyncio.run()` to start
`try/catch/finally`	`try/except/finally`	`catch` → `except`
`throw new Error()`	`raise Exception()`	`throw` → `raise`
`import { x } from 'y'`	`from y import x`	Reversed order
`export`	No keyword needed	Everything is importable by default
`this`	`self`	Must explicitly pass `self` to methods
`...spread`	`args` / `*kwargs`	`` for positional, `*` for keyword
Template literals	f-strings	`${x}` → `f"{x}"`
`.map()`	list comprehension	`[f(x) for x in items]`
`.filter()`	list comprehension	`[x for x in items if cond]`
`.forEach()`	`for x in items:`
`Promise.all()`	`asyncio.gather()`
`npm`	`pip`
`node_modules/`	`.venv/`
`package.json`	`requirements.txt`

How to Use React Native Best Practices Agent Skills

Ajmal Hasan — Thu, 22 Jan 2026 05:07:14 +0000

Introduction

React Native performance optimization can be complex, with many pitfalls that affect FPS, bundle size, memory usage, and startup time. The react-native-best-practices skill package provides AI coding agents with comprehensive guidelines to automatically detect, suggest, and implement performance optimizations in React Native and Expo applications.

These best practices are packaged as Agent skills that integrate seamlessly into Cursor and other AI-powered coding agents.

When your agent reviews, optimizes, or develops a React Native codebase, it can automatically reference these patterns and suggest fixes based on proven optimization techniques from Callstack's "Ultimate Guide to React Native Optimization."

For detailed information, refer to the official announcement: Announcing: React Native Best Practices for AI Agents

What Are Agent Skills?

Agent skills are knowledge packages that enhance AI coding assistants with domain-specific expertise. Instead of manually searching documentation or remembering optimization patterns, your AI assistant can:

Automatically detect performance issues in your code
Suggest specific fixes based on proven patterns
Reference detailed guides when working on optimization tasks
Apply best practices without you having to prompt for each one

The react-native-best-practices skill contains:

1 main SKILL.md file with quick references and problem mappings
28 detailed reference files covering JavaScript, Native, and Bundling optimizations
Priority-ordered guidelines (CRITICAL → HIGH → MEDIUM impact)
Code examples showing incorrect vs. correct patterns

Installation

For Cursor

Install the skill package using npm:

npx add-skill callstackincubator/agent-skills

This command will:

Download the skill package
Install it into your agent's skill directory (typically .agents/skills/ or .windsurf/skills/)
Make it available for automatic reference during coding sessions

How It Works

Automatic Activation

The skill is automatically activated when your AI assistant detects tasks related to:

Performance Issues

"App feels slow/janky"
"Animation drops frames"
"List scroll is laggy"
"Too many re-renders"
"FPS is low"

Bundle & App Size

"Bundle size is too large"
"App size optimization"
"Reduce bundle size"
"Tree shaking issues"

Memory Problems

"Memory leaks"
"Memory growing over time"
"App crashes due to memory"

Startup Time

"Slow app startup"
"TTI (Time to Interactive) optimization"
"Cold start performance"

Native Modules

"Native module performance"
"Turbo Modules"
"Bridge overhead"
"Android 16KB alignment"

Specific Technologies

FlashList optimization
Hermes optimization
React Native profiling
Reanimated worklets

Example: Automatic Detection

You ask:

"My FlatList is scrolling slowly, how can I optimize it?"

The agent automatically:

Recognizes this as a performance issue
References js-lists-flatlist-flashlist.md from the skill
Suggests replacing FlatList with FlashList
Provides code examples and migration steps
Explains the performance benefits

You ask:

"My bundle size is 15MB, how can I reduce it?"

The agent automatically:

Detects bundle size optimization need
References multiple bundle-related skills:
- bundle-analyze-js.md (to analyze current bundle)
- bundle-barrel-exports.md (to fix barrel imports)
- bundle-tree-shaking.md (to enable tree shaking)
Provides step-by-step optimization plan
Shows before/after code examples

What's Included

Priority-Ordered Guidelines

The skill organizes optimizations by impact:

Priority	Category	Impact	Examples
1	FPS & Re-renders	CRITICAL	FlashList, React Compiler, atomic state
2	Bundle Size	CRITICAL	Barrel exports, tree shaking, R8
3	TTI Optimization	HIGH	Hermes mmap, native navigation
4	Native Performance	HIGH	Turbo Modules, threading
5	Memory Management	MEDIUM-HIGH	Memory leak detection
6	Animations	MEDIUM	Reanimated worklets

Reference Files

JavaScript/React (`js-*`)

js-lists-flatlist-flashlist.md - Replace ScrollView with virtualized lists
js-profile-react.md - React DevTools profiling
js-measure-fps.md - FPS monitoring
js-memory-leaks.md - JS memory leak detection
js-atomic-state.md - Jotai/Zustand patterns
js-concurrent-react.md - useDeferredValue, useTransition
js-react-compiler.md - Automatic memoization
js-animations-reanimated.md - Reanimated worklets
js-uncontrolled-components.md - TextInput optimization

Native (`native-*`)

native-turbo-modules.md - Building fast native modules
native-sdks-over-polyfills.md - Native vs JS libraries
native-measure-tti.md - TTI measurement
native-threading-model.md - Turbo Module threads
native-profiling.md - Xcode/Android Studio profiling
native-memory-leaks.md - Native memory leak detection
native-android-16kb-alignment.md - Google Play alignment

Bundling (`bundle-*`)

bundle-barrel-exports.md - Avoid barrel imports
bundle-analyze-js.md - JS bundle visualization
bundle-tree-shaking.md - Dead code elimination
bundle-r8-android.md - Android code shrinking
bundle-hermes-mmap.md - Disable bundle compression

Real-World Usage Examples

Example 1: Fixing Slow List Scrolling

Before (without skill):
You might manually search for "React Native list optimization" and try various solutions.

With skill:

// Agent automatically suggests:
// ❌ Current code
<ScrollView>
  {items.map(item => <Item key={item.id} />)}
</ScrollView>

// ✅ Optimized code
import { FlashList } from '@shopify/flash-list';

<FlashList
  data={items}
  renderItem={({ item }) => <Item item={item} />}
  estimatedItemSize={100}
/>

The agent explains:

Why FlashList is better than FlatList/ScrollView
How to estimate item sizes
Performance improvements (often 2-3x faster)

Example 2: Reducing Bundle Size

With skill, the agent automatically:

Analyzes your imports
Detects barrel exports
Suggests direct imports

// ❌ Barrel import (bundles everything)
import { Button, Card, Modal } from './components';

// ✅ Direct imports (only bundles what you use)
import Button from './components/Button';
import Card from './components/Card';

Example 3: Memory Leak Detection

You mention: "My app's memory keeps growing"

Agent automatically:

References js-memory-leaks.md
Suggests profiling steps
Identifies common leak patterns:
- Event listeners not cleaned up
- Timers/intervals not cleared
- Subscriptions not unsubscribed
Provides fix examples

Problem → Skill Mapping

The skill includes a built-in mapping so agents know which reference to use:

Problem	Agent References
App feels slow/janky	`js-measure-fps.md` → `js-profile-react.md`
Too many re-renders	`js-profile-react.md` → `js-react-compiler.md`
Slow startup (TTI)	`native-measure-tti.md` → `bundle-analyze-js.md`
Large app size	`bundle-analyze-app.md` → `bundle-r8-android.md`
Memory growing	`js-memory-leaks.md` or `native-memory-leaks.md`
Animation drops frames	`js-animations-reanimated.md`
List scroll jank	`js-lists-flatlist-flashlist.md`
TextInput lag	`js-uncontrolled-components.md`
Native module slow	`native-turbo-modules.md` → `native-threading-model.md`

Benefits

1. Automatic Pattern Recognition

No need to remember all optimization patterns. The agent recognizes issues and suggests fixes automatically.

2. Proven Solutions

Based on Callstack's comprehensive optimization guide, tested in real-world applications.

3. Context-Aware Suggestions

The agent understands your specific problem and provides relevant solutions, not generic advice.

4. Code Examples

Each skill includes before/after code examples, making implementation straightforward.

5. Priority Guidance

CRITICAL issues are addressed first, ensuring maximum impact.

6. Comprehensive Coverage

28 reference files cover JavaScript, Native, and Bundling optimizations.

Best Practices for Using the Skill

1. Be Specific About Problems

Instead of "my app is slow," say:

"My FlatList scrolls at 30 FPS"
"App startup takes 5 seconds"
"Bundle size is 20MB"

2. Let the Agent Analyze First

Ask the agent to:

"Analyze my codebase for performance issues"
"Check for barrel imports"
"Review my list components"

3. Follow the Suggestions

The agent provides prioritized fixes. Start with CRITICAL items first.

4. Measure Before and After

Use the profiling tools mentioned in the skills to verify improvements:

FPS monitoring
Bundle analysis
Memory profiling
TTI measurement

Integration with Your Workflow

During Code Review

The agent automatically flags:

ScrollView usage (should be FlashList)
Barrel imports
Missing memoization
Inline styles (if using Unistyles)

During Development

The agent suggests:

Better component patterns
Performance optimizations
Memory-efficient implementations

During Optimization

The agent provides:

Step-by-step optimization plans
Measurement tools
Before/after comparisons

Troubleshooting

Skill Not Activating?

Check Installation

   ls .agents/skills/react-native-best-practices/
   # or
   ls .windsurf/skills/react-native-best-practices/

Use Specific Keywords
- "performance"
- "optimization"
- "bundle size"
- "memory leak"
- "FPS"
Be Explicit
- "Use react-native-best-practices to optimize this"
- "Check this code against performance best practices"

Skill Suggestions Not Relevant?

The skill is designed for React Native/Expo apps. For other frameworks, different skills may be needed.

Conclusion

The react-native-best-practices agent skill transforms your AI coding assistant into a React Native performance expert. By automatically detecting issues and suggesting proven optimizations, it helps you:

Build faster apps with better FPS and responsiveness
Reduce bundle sizes for faster downloads
Prevent memory leaks that cause crashes
Optimize startup time for better user experience

Install it once, and your agent will continuously help you write performant React Native code.

Additional Resources

Official Announcement: Announcing: React Native Best Practices for AI Agents
Source Guide: Based on Callstack's Ultimate Guide to React Native Optimization
Skill Repository: callstackincubator/agent-skills
Installation: npx add-skill callstackincubator/agent-skills

Happy Optimizing! 🚀

Lightning-Fast In-App Debugging with React Native BugBubble

Ajmal Hasan — Mon, 05 Jan 2026 07:05:58 +0000

If you want real-time visibility into network calls, WebSocket events, console logs, and analytics without leaving your app, @lokal-dev/react-native-bugbubble is a lightweight drop-in debugger for React Native.

DEMO

Why BugBubble?

Floating debug bubble you can drag and tap to open the debugger UI.
Tracks network, WebSocket, console, and analytics events out of the box.
Zero native setup; pure JS/TS with sensible defaults.
Configurable log limits, button position, and per-signal tracking.

Installation

yarn add @lokal-dev/react-native-bugbubble
# or
npm install @lokal-dev/react-native-bugbubble

Minimal Integration

Add the component at your app root so it mounts once:

import { BugBubbleProvider } from '@components/global/BugBubbleProvider';

export default function App() {
  return (
    <>
      <YourApp />
      <BugBubbleProvider />
    </>
  );
}

Configuring the Debugger

You can tune log limits, bubble position, and tracking switches:

import { BugBubble } from '@lokal-dev/react-native-bugbubble';

const IS_BUG_BUBBLE_ENABLED = Keys.ENV !== 'production';

/**
 * BugBubble configuration options
 */
const bugBubbleConfig = {
  maxLogs: 100, // Maximum number of logs to store
  floatingButtonPosition: {
    top: 150,
    right: 30,
  },
  trackingOptions: {
    enabled: true,
    options: {
      console: true, // Track console logs
      network: true, // Track network requests
      websocket: true, // Track websocket connections
      analytics: true, // Disable analytics tracking
    },
  },
  ignoreUrls: [/symbolicate/, /generate_204/, /clients3\.google\.com/], // optional: hide unwanted urls
};

export const BugBubbleProvider = () => {
  if (!IS_BUG_BUBBLE_ENABLED) {
    return null;
  }

  return <BugBubble config={bugBubbleConfig} />;
};

Notes:

Config is read on mount; remount to change it.
Disabling a log type hides its tab and stops interceptors for that type.

Manual Logging (Optional)

If you need to log custom events:

import { BugBubbleLogger } from '@lokal-dev/react-native-bugbubble';

BugBubbleLogger.logAnalytics('user_login', { method: 'email' });
BugBubbleLogger.logNetwork('POST', 'https://api.example.com/users', 201);
BugBubbleLogger.logWebSocket('message', 'wss://api.example.com/ws', { ping: true });
BugBubbleLogger.logConsole('warn', 'Deprecated API used');

When to Use It

QA builds to inspect API traffic without remote tools.
Investigating flaky WebSocket or console noise in CI-only environments.
Lightweight alternative to heavier remote debuggers.

For full API details and examples, see the project repo: react-native-bugbubble on GitHub.

Knip: Dead Code Detector for JavaScript & TypeScript Projects

Ajmal Hasan — Tue, 23 Dec 2025 19:51:53 +0000

Every mature codebase has dead code. That utility function someone wrote "just in case." The component from a feature that was scrapped. The npm package installed for a spike that never went anywhere.

ESLint can catch unused variables and imports within a file, but what about:

Files that are never imported anywhere?
Exported functions that no one uses?
Dependencies in package.json you forgot to remove?
Types and interfaces defined but never referenced?

This is where Knip comes in.

What Knip Detects

Category	Description
🗂️ Unused Files	Source files that aren't imported anywhere
📦 Unused Dependencies	Packages in `package.json` that aren't used
📤 Unused Exports	Functions, classes, types exported but never imported
🔧 Unused Dev Dependencies	Dev packages that aren't needed
❓ Unlisted Dependencies	Packages used in code but missing from `package.json`
🔗 Unresolved Imports	Imports pointing to non-existent modules

Getting Started

Installation

# npm
npm install -D knip

# yarn
yarn add -D knip

# pnpm
pnpm add -D knip

Basic Usage

Just run it:

npx knip

That's it! Knip will analyze your project and output all the unused code it finds.

Configuration

For most projects, Knip works out of the box. But for complex setups (monorepos, custom entry points, etc.), you'll want a config file.

Create knip.json in your project root:

{
  "$schema": "https://unpkg.com/knip@5/schema.json",
  "entry": ["src/index.ts", "src/App.tsx"],
  "project": ["src/**/*.{ts,tsx}"],
  "ignore": [
    "**/__tests__/**",
    "**/__mocks__/**",
    "**/node_modules/**"
  ],
  "ignoreDependencies": [
    "prettier",
    "husky"
  ]
}

Key Configuration Options

Option	Description
`entry`	Entry point files where Knip starts tracing
`project`	Files to analyze
`ignore`	Files/patterns to skip
`ignoreDependencies`	Dependencies to skip (useful for config-only packages)
`ignoreExportsUsedInFile`	Don't report exports used only in the same file

React Native Example

For React Native projects, you'll need to account for native tooling and development dependencies:

{
  "$schema": "https://unpkg.com/knip@5/schema.json",
  "entry": ["src/App.tsx", "index.js"],
  "project": ["src/**/*.{ts,tsx}"],
  "ignore": [
    "**/__tests__/**",
    "**/__mocks__/**",
    "android/**",
    "ios/**"
  ],
  "ignoreDependencies": [
    "@react-native/metro-config",
    "@react-native/typescript-config",
    "@react-native/babel-preset",
    "patch-package",
    "husky",
    "reactotron-react-native"
  ],
  "ignoreExportsUsedInFile": true
}

Real-World Results

I ran Knip on a production React Native app, and here's what it found:

Unused files (73)
src/components/map/index.tsx
src/components/views/NotificationMenuButton.tsx
src/models/requests/auth/authRequests.ts
src/utils/helpers/contactHelper.ts
... and 69 more

Unused dependencies (1)
@react-native-firebase/perf

Unused devDependencies (4)
@babel/preset-env
@testing-library/jest-native
@types/react-native-get-random-values
eslint-plugin-react-you-might-not-need-an-effect

Unlisted dependencies (2)
credit-card-type  src/features/paymentMethods/addNewCard/index.tsx

Unused exports (74)
translations        src/config/localization/languages.ts
defaultAddressForm  src/features/addressBook/addressTypes.ts
... and more

73 unused files! That's potentially thousands of lines of dead code that:

Increases bundle size
Confuses new developers
Creates maintenance burden
Shows up in search results, wasting time

iOS Bridging Header Setup for React Native

Ajmal Hasan — Tue, 16 Dec 2025 18:51:43 +0000

A bridging header allows Swift code to access Objective-C libraries and native modules. Here's how to set it up.

Setup Steps

Step 1: Create the Bridging Header File

Right-click on your project folder in Xcode
Select New File from Template
Choose Header file

Step 2: Configure the File

Click Header file template
Name it: YourAppName-Bridging-Header.h
Select all targets (main app, development, production)
Click Create

Step 3: Set the Bridging Header Path

For each target:

Go to Build Settings
Search for "Objective-C Bridging Header"
Set path: YourAppName/YourAppName-Bridging-Header.h

Step 4: Import Your Headers

Open the bridging header and import what you need:

// React Native Config
#import "RNCConfig.h"

// Google Maps
#import <GoogleMaps/GoogleMaps.h>

// Your custom modules
#import "CustomNativeModule.h"

Step 5: Use in AppDelegate.Swift

import UIKit

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, 
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        // Access environment variables
        if let apiKey = RNCConfig.env(for: "API_KEY") {
            GMSServices.provideAPIKey(apiKey)
        }

        // Initialize Firebase
        FirebaseApp.configure()

        return true
    }
}

Step 6: Clean and Build

Clean: Cmd + Shift + K
Build: Cmd + B
Run: Cmd + R

Project Structure

YourAppName/
├── ios/
│   ├── YourAppName/
│   │   ├── AppDelegate.swift
│   │   ├── YourAppName-Bridging-Header.h  ✅
│   │   └── Info.plist
│   └── Pods/
└── package.json

Found this helpful? Drop a ❤️ below! 🚀

ReactNative #iOS #Swift #MobileDevelopment

Stop Fighting React Native Dependency Hell — Use This Microsoft Tool

Ajmal Hasan — Mon, 08 Dec 2025 14:18:07 +0000

The Problem Every React Native Dev Knows

You've been there. You run yarn install, everything looks fine, then boom — runtime crashes, red screens, or mysterious build failures. The culprit? Incompatible package versions.

React Native's ecosystem moves fast. Package A needs React Native 0.81, but Package B was last tested on 0.79. Figuring out which versions play nice together? A nightmare.

Enter `@rnx-kit/align-deps`

Microsoft built a tool that solves this: align-deps. It automatically checks and fixes your dependencies to ensure they're compatible with your React Native version.

Quick Setup (2 minutes)

1. Install it:

yarn add @rnx-kit/align-deps --dev

2. Add these scripts to package.json:

{
  "scripts": {
    "check-dependencies": "rnx-align-deps",
    "fix-dependencies": "rnx-align-deps --write"
  }
}

3. Initialize for your RN version:

npx rnx-align-deps --init app

4. Fix any issues:

yarn fix-dependencies

That's it. The tool scans your dependencies and adjusts versions to ones known to work together.

Upgrading React Native? Here's Your Toolkit

Upgrading React Native involves two things: dependencies and native files. You need different tools for each.

Step 1: Align Your Dependencies

Use align-deps to update all your JS dependencies to compatible versions:

npx @rnx-kit/align-deps --requirements react-native@0.81 --write

This updates all your React Native-related packages to versions known to work with RN 0.81. No more guessing which version of react-native-screens or react-native-reanimated, etc you need.

Step 2: Update Native Files (iOS/Android)

Dependencies are only half the battle. React Native upgrades often require changes to native files like AppDelegate.swift, build.gradle, Podfile, etc.

👉 Use the React Native Upgrade Helper

This tool shows you a visual diff of all native file changes between your current version and your target version.

How to use it:

Go to react-native-community.github.io/upgrade-helper
Select your current RN version (e.g., 0.79.0)
Select your target RN version (e.g., 0.81.0)
Review the diff and apply changes to your ios/ and android/ folders

Pro Tip: Use Both Together

Task	Tool
Update JS dependencies	`@rnx-kit/align-deps`
Update native files	Upgrade Helper

This combo makes React Native upgrades dramatically less painful.

What align-deps Actually Does

When I ran fix-dependencies on my project, it:

⬇️ Downgraded some packages to stable, compatible versions
🔓 Added flexibility (^) to some pinned versions
📋 Generated config tracking which "capabilities" my app uses

For example, it changed:

react-native-modal: ^14.0.0-rc.1 → ^13.0.0 (stable over RC)
react-native-screens: 4.16.0 → ^4.11.1 (known compatible)

Should You Use It?

Yes, if:

You maintain a production React Native app
You've wasted time debugging version conflicts
You want safer React Native upgrades
You work in a team and need consistent dependencies

Maybe not if:

You need bleeding-edge package versions
You have a simple app with few dependencies

⚠️ Important: Always Review Changes

The tool modifies your package.json automatically. Always:

Review the diff (git diff package.json)
Test your app thoroughly
Check if any downgraded packages break features you need

Resources

📚 align-deps Documentation
🔄 React Native Upgrade Helper

Have you tried these tools? Did they help or cause issues? Drop a comment below! 👇

Debugging Native Code in React Native: A Step-by-Step Guide (Android & iOS)

Ajmal Hasan — Sun, 07 Dec 2025 18:06:21 +0000

As React Native developers, we're comfortable with JavaScript debugging—Chrome DevTools, console logs, the usual suspects. But native code? That's where things get intimidating.

Here's what I learned about debugging Kotlin/Swift code in React Native apps, and why it's not as scary as you think.

Why Bother with Native Debugging?

Third-party library crashes: That cryptic native error? Step through the actual code to see what's breaking.
Custom native modules: Debug your bridge code properly instead of littering it with log statements.
Performance issues: JavaScript profiling won't show native rendering bottlenecks.
Platform-specific bugs: That Android 12-only crash? See exactly where and why it fails.

The Debugging Tools

Android Studio (Kotlin/Java)

Android Studio is your IDE for the Android native side. It's built on IntelliJ, so if you've used WebStorm or other JetBrains tools, the interface will feel familiar.

Key debugging shortcuts:

F8 - Step Over (execute current line, move to next)
F7 - Step Into (dive into function call)
Shift+F8 - Step Out (finish current function, return to caller)
F9 - Resume (continue until next breakpoint)
Cmd+F8 - Toggle breakpoint

Xcode (Swift/Objective-C)

Xcode is Apple's IDE for iOS development. It has powerful debugging tools, though the keyboard shortcuts differ from Android Studio.

Key debugging shortcuts:

F6 - Step Over
F7 - Step Into
F8 - Step Out
Control button (or Ctrl+Cmd+Y) - Continue/Resume
Cmd+\ - Toggle breakpoint

Setting Up: My Practice Code

To really learn debugging, I added sample code to both platforms with common patterns you'll encounter. Here's what I created:

Android (MainActivity.kt)

private fun debugBreakpointDemo() {
    val userName = "ReactNativeDev"
    val userAge = 28
    val isActive = true

    val items = listOf("Apple", "Banana", "Cherry", "Date", "Elderberry")

    for ((index, item) in items.withIndex()) {
        Log.d("BreakpointDemo", "Item $index: $item")

        if (index == 2) {
            val specialItem = item.uppercase()
            Log.d("BreakpointDemo", "Special item found: $specialItem")
        }
    }

    val result = performCalculation(10, 20)
    Log.d("BreakpointDemo", "Calculation result: $result")
}

private fun performCalculation(a: Int, b: Int): Int {
    val sum = a + b
    val multiplied = sum * 2
    return multiplied
}

iOS (AppDelegate.swift)

func debugBreakpointDemo() {
    let userName = "ReactNativeDev"
    let userAge = 28
    let isActive = true

    let items = ["Apple", "Banana", "Cherry", "Date", "Elderberry"]

    for (index, item) in items.enumerated() {
        print("Item \(index): \(item)")

        if index == 2 {
            let specialItem = item.uppercased()
            print("Special item found: \(specialItem)")
        }
    }

    let result = performCalculation(a: 10, b: 20)
    print("Calculation result: \(result)")
}

func performCalculation(a: Int, b: Int) -> Int {
    let sum = a + b
    let multiplied = sum * 2
    return multiplied
}

Hands-On: Your First Native Debugging Session

Let me walk you through a practice session. This is how I learned, and it demystified native debugging completely.

Step 1: Set Your First Breakpoint

Android Studio:

Open android/app/src/main/java/.../MainActivity.kt
Find the line val userName = "ReactNativeDev"
Click the gray gutter area to the left of the line number
A red dot appears—that's your breakpoint

Xcode:

Open ios/YourApp/AppDelegate.swift
Find the line let userName = "ReactNativeDev"
Click the gray gutter to the left
A blue arrow appears—that's your breakpoint

Step 2: Run in Debug Mode

Android Studio:

Click the bug icon 🪲 in the toolbar (or press Shift+F9)
The app launches and immediately pauses at your breakpoint
The IDE highlights the current line in blue

Xcode:

Press Cmd+R or click the Play button
The app pauses at your breakpoint
The current line is highlighted with a green overlay

Step 3: Explore the Variables Panel

This is where the magic happens. Look at the bottom of your IDE.

You'll see a "Variables" panel showing:

userName = "ReactNativeDev"
userAge = <not initialized yet>
isActive = <not initialized yet>

Why aren't the others initialized? Because breakpoints pause before executing the line. The line is about to run but hasn't yet.

Step 4: Step Over (F8 or F6)

Press F8 (Android Studio) or F6 (Xcode) a few times. Watch as:

userName appears in variables
Next step: userAge appears
Next step: isActive appears
The list items gets created

You're executing line by line. This is stepping over—you execute the current line and move to the next one without diving into function internals.

Step 5: Step Into a Function (F7)

Keep stepping until you reach the line:

val result = performCalculation(10, 20)

Now instead of pressing F8/F6, press F7.

Boom! You're now inside the performCalculation function. The IDE jumped you to its definition. This is stepping into—diving into the implementation of a function call.

Step over a couple of times inside this function. Watch sum and multiplied appear in the variables panel.

Step 6: Step Out (Shift+F8 or F8)

You've seen enough inside performCalculation. Press Shift+F8 (Android Studio) or F8 (Xcode).

The function completes, and you're back where you called it from. The result variable now contains the return value (60). This is stepping out—finishing the current function and returning to the caller.

Step 7: Resume Execution (F9 or Continue Button)

Press F9 (Android Studio) or click the Continue button (Xcode) to let the app run normally until it hits another breakpoint (or finishes).

Advanced Techniques I Use Daily

Conditional Breakpoints

Right-click a breakpoint and add a condition. For example, only break when index == 2 in a loop. This saved me hours when debugging issues that only occurred on the 100th iteration.

Android Studio: Right-click breakpoint → More → Condition
Xcode: Right-click breakpoint → Edit Breakpoint → Condition

Expression Evaluation

While paused, you can evaluate any expression on the fly.

Android Studio:

Select an expression in code
Right-click → Evaluate Expression (or Alt+F8)
Try: items.filter { it.startsWith("A") }

Xcode:

In the debug console, type: po items.filter { $0.hasPrefix("A") }
po means "print object"

Call Stack Navigation

The call stack shows how you got to the current line. Click any frame to jump to that context and see its variables. Invaluable when you're deep in a chain of function calls.

Watch Variables

Add variables to your watch list to track them across function calls. They persist even when out of scope.

Android Studio: Right-click variable → Add to Watches
Xcode: Right-click variable → Watch "variableName"

Real-World Example: Debugging a Crash

Last week, my app crashed when users tapped a button. JavaScript logs showed nothing. Here's how native debugging saved me:

Android Studio: Set breakpoint in onClick handler
Run in debug mode, tap the button
Step through the native code
Found the crash: accessing an ArrayList index that didn't exist
The issue: JavaScript sent wrong array length to native

Without stepping through with breakpoints, I'd have spent hours adding log statements and rebuilding.

Tips from the Trenches

Start simple: Don't try to debug react-native core libraries on day one. Practice with your own simple native code first.

Use both IDEs: I have both Android Studio and Xcode open when working on RN. Debug both platforms regularly—they have different bugs.

Combine with JS debugging: Use both Chrome DevTools for JS and native debuggers. Some bugs span both layers.

Read the call stack: When you hit a breakpoint, spend time reading the call stack. Understanding how you got there is as important as where you are.

Don't fear native code: It's just code. Kotlin and Swift are actually quite pleasant languages. The debugging process is identical to JavaScript debugging, just different tools.

Practice Challenge

Here's what I recommend: spend 30 minutes today just stepping through the sample code I showed above. Don't try to fix anything, just explore:

Set breakpoints in loops
Step into and out of functions
Watch variables change
Evaluate expressions
Add conditional breakpoints

This low-pressure practice builds the muscle memory. When you hit a real bug, you'll know exactly what to do.

Resources That Helped Me

Conclusion

Native debugging isn't scary—it's empowering. As React Native developers, we shouldn't fear diving into the native layer. These tools are powerful, learnable, and absolutely essential for professional RN development.

The difference between a good RN developer and a great one? Great ones are comfortable in all three worlds: JavaScript, Android native, and iOS native.

Start small, practice deliberately, and soon you'll wonder how you ever developed without native debugging.

Happy debugging! 🐛🔍

What native debugging techniques have you found helpful? Share your experiences in the comments below!

How I Reduced My React Native 0.81 APK Size by 50% (Without Breaking Anything)

Ajmal Hasan — Fri, 05 Dec 2025 21:38:01 +0000

A large APK size can slow down downloads, increase install drop-offs, and impact user experience — especially in regions with slower internet connections.

In this post, I'll walk you through the exact steps I used to reduce a production React Native 0.81 app's APK size by ~50%, while maintaining full functionality and security.

📊 The Results

Before	After	Reduction
~85 MB	~42 MB	~50%

🛠️ Step 1: Build Only for arm64-v8a Architecture

Most optimization guides tell you to split APKs by CPU architecture. But here's the thing: if your minSdkVersion is 29+ (Android 10+), you only need arm64-v8a.

Why? Because:

✅ All Android 10+ devices support 64-bit (arm64-v8a)
✅ Google Play Store requires 64-bit support
✅ 95%+ of active Android devices use arm64-v8a
❌ armeabi-v7a is for 32-bit devices (pre-2014)
❌ x86/x86_64 is for Intel devices (<1% market share)

Implementation

In your android/app/build.gradle:

// Enable separate builds per CPU architecture
def enableSeparateBuildPerCPUArchitecture = true

android {
    // ... existing config ...

    splits {
        abi {
            reset()
            enable enableSeparateBuildPerCPUArchitecture
            universalApk false  // No universal APK needed
            include "arm64-v8a"  // Only modern 64-bit devices
        }
    }
}

> 💡 Pro tip: Set universalApk false to skip building a fat universal APK — it's unnecessary when targeting a single architecture.

🌍 Step 2: Keep Only Necessary Languages

Your app probably only supports a few languages, but by default, Android bundles resources for ALL languages from your dependencies (like Google Play Services).

Implementation

In android/app/build.gradle, inside defaultConfig:

defaultConfig {
    // ... existing config ...

    // Keep only necessary languages to reduce APK size
    resConfigs "ar", "en", "fr"  // Add your supported languages
}

This single line can remove several megabytes of unused language resources!

📦 Step 3: Enable Resource Shrinking & PNG Compression

Enable these in your release build type:

buildTypes {
    release {
        signingConfig signingConfigs.release
        debuggable false
        minifyEnabled true          // Code shrinking (already enabled)
        shrinkResources true        // Remove unused resources
        crunchPngs true             // Extra PNG compression
        zipAlignEnabled true        // Memory optimization
        proguardFiles getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro"
    }
}

What Each Does:

Option	Benefit
`minifyEnabled true`	Removes unused code, obfuscates names
`shrinkResources true`	Removes unused drawables, layouts, etc.
`crunchPngs true`	Additional PNG compression
`zipAlignEnabled true`	Optimizes APK for memory-mapped reading

🔐 Step 4: Optimize ProGuard Rules

ProGuard (or R8) is powerful but can break your app if not configured correctly. Here's a comprehensive, battle-tested configuration for React Native 0.81:

`android/app/proguard-rules.pro`

# ========== STANDARD OPTIMIZATIONS ==========
-optimizationpasses 3
-allowaccessmodification
-overloadaggressively
-repackageclasses ''
-dontusemixedcaseclassnames
-dontpreverify

# Remove debug logging in production (keeps error logs)
-assumenosideeffects class android.util.Log {
    public static *** d(...);
    public static *** v(...);
    public static *** i(...);
    public static *** w(...);
}

# Keep crash reporting info
-keepattributes SourceFile,LineNumberTable
-renamesourcefileattribute SourceFile
-keepattributes Signature, *Annotation*

# ========== REACT NATIVE CORE ==========
-keep class com.facebook.hermes.** { *; }
-keep class com.facebook.hermes.unicode.** { *; }
-keep class com.facebook.react.** { *; }
-keep class com.facebook.jni.** { *; }
-keep class com.facebook.soloader.** { *; }

# Bridge & Native Modules
-keep public class * extends com.facebook.react.bridge.NativeModule { *; }
-keep class com.facebook.react.bridge.** { *; }
-keepclassmembers class * { 
    @com.facebook.react.bridge.ReactMethod *; 
}
-keepclassmembers class * {
    @com.facebook.proguard.annotations.DoNotStrip *;
}

# UI Manager & View System
-keep @com.facebook.react.uimanager.annotations.ReactProp class * { *; }
-keep @com.facebook.react.uimanager.annotations.ReactPropGroup class * { *; }
-keep class * extends com.facebook.react.uimanager.ViewManager { *; }
-keep class com.facebook.react.uimanager.** { *; }

# TurboModules (New Architecture)
-keep class com.facebook.react.turbomodule.** { *; }
-keep class com.facebook.react.animated.** { *; }
-keep class com.facebook.react.common.** { *; }

# ========== COMMON LIBRARIES ==========
# Reanimated
-keep class com.swmansion.reanimated.** { *; }
-keep class com.swmansion.** { *; }
-dontwarn com.swmansion.**

# SVG
-keep public class com.horcrux.svg.** { *; }

# Fast Image
-keep class com.dylanvann.fastimage.** { *; }

# Firebase
-keep class com.google.firebase.** { *; }
-dontwarn com.google.firebase.**

# OkHttp
-keep class okhttp3.** { *; }
-keep interface okhttp3.** { *; }
-dontwarn okhttp3.**
-dontwarn okio.**### Why This Works:

-optimizationpasses 3 — Multiple optimization passes for maximum shrinkage
Log removal — Strips debug/verbose/info/warning logs (keeps errors for debugging)
-keepattributes SourceFile,LineNumberTable — Preserves stack traces for crash reporting
Comprehensive -keep rules — Protects all React Native internals and common libraries

✅ Step 5: Verify Hermes is Enabled

Hermes is React Native's optimised JavaScript engine. It should be enabled by default in RN 0.81, but verify in your android/gradle.properties:

hermesEnabled=true
Hermes provides:

✅ Faster app startup
✅ Smaller JS bundle size
✅ Lower memory usage

🧪 Testing Your Build

After applying all optimisations:

Clean previous builds

cd android && ./gradlew clean

Build release APK

./gradlew assembleRelease

Check APK size

ls -lh app/build/outputs/apk//release/.apk---

📋 Complete Checklist

[ ] Set enableSeparateBuildPerCPUArchitecture = true
[ ] Include only arm64-v8a architecture (if minSdk 29+)
[ ] Set universalApk false
[ ] Add resConfigs for your supported languages
[ ] Enable shrinkResources true
[ ] Enable crunchPngs true
[ ] Enable zipAlignEnabled true
[ ] Add comprehensive ProGuard rules
[ ] Verify Hermes is enabled
[ ] Test on real devices before release!

🎯 Summary

Optimization	APK Size Impact
Single architecture (arm64-v8a)	-30-40%
Resource shrinking	-5-10%
Language filtering	-2-5%
ProGuard optimizations	-5-10%
PNG compression	-1-3%

⚠️ Important Notes

Always test on real devices after applying these optimizations
Keep error logs — don't strip Log.e() for production debugging
Firebase Crashlytics still works — we preserved SourceFile,LineNumberTable
Play Store accepts single-architecture APKs — they'll deliver the right one to users

Hope this helps you ship a lighter, faster React Native app! 🚀

Got questions or improvements? Drop them in the comments! 👇

Found this useful? Follow me for more React Native optimization tips!

Setting Up SonarQube Locally for React Native & MERN Projects

Ajmal Hasan — Sat, 08 Nov 2025 16:12:05 +0000

As a React Native and MERN developer, I recently integrated SonarQube into my local workflow using Docker. Here's a straightforward guide to get you started.

What is SonarQube?

SonarQube automatically scans your code to find:

Bugs and potential errors
Security vulnerabilities
Code smells (maintainability issues)
Test coverage gaps
Duplicate code

Prerequisites

Install Docker Desktop:

brew install --cask docker

Open Docker Desktop from Applications and make sure it's running.

Setup Steps (project👨‍💻)

1. Create Docker Compose File

Create docker-compose.yml in your project root:

services:
  sonarqube:
    image: sonarqube:community
    container_name: sonarqube-local
    ports:
      - "9000:9000"
    environment:
      - SONAR_ES_BOOTSTRAP_CHECKS_DISABLE=true
    volumes:
      - sonarqube_data:/opt/sonarqube/data
      - sonarqube_extensions:/opt/sonarqube/extensions
      - sonarqube_logs:/opt/sonarqube/logs
    networks:
      - sonarqube-network

volumes:
  sonarqube_data:
  sonarqube_extensions:
  sonarqube_logs:

networks:
  sonarqube-network:
    driver: bridge

2. Add Scripts to package.json

{
  "scripts": {
    "sonar": "sonar-scanner",
    "sonar:start": "docker-compose up -d",
    "sonar:stop": "docker-compose stop",
    "sonar:down": "docker-compose down",
    "sonar:logs": "docker-compose logs -f sonarqube"
  }
}

3. Create SonarQube Configuration

Create sonar-project.properties:

# Project identification
sonar.projectKey=my-app
sonar.projectName=My App
sonar.projectVersion=1.0.0

# Source code location
sonar.sources=src
sonar.tests=__tests__

# Exclude directories
sonar.exclusions=\
  **/node_modules/**,\
  **/android/**,\
  **/ios/**,\
  **/vendor/**,\
  **/coverage/**,\
  **/__mocks__/**,\
  **/build/**,\
  **/*.spec.ts,\
  **/*.spec.tsx,\
  **/*.test.ts,\
  **/*.test.tsx,\
  **/assets/**,\
  **/*.config.js,\
  **/*.config.ts,\
  **/*.config.mjs,\
  **/babel.config.js,\
  **/metro.config.js,\
  **/jest.config.js,\
  **/jest-setup.ts

# Test exclusions
sonar.test.exclusions=\
  **/node_modules/**,\
  **/coverage/**

# Language
sonar.language=ts

# Encoding
sonar.sourceEncoding=UTF-8

# TypeScript specific
sonar.typescript.node=node

# Coverage report paths
sonar.javascript.lcov.reportPaths=coverage/lcov.info
sonar.coverage.exclusions=\
  **/__tests__/**,\
  **/__mocks__/**,\
  **/*.test.ts,\
  **/*.test.tsx,\
  **/*.spec.ts,\
  **/*.spec.tsx

# Disable external issues
sonar.typescript.internal.typescriptLocation=node_modules/typescript

# Host URL
sonar.host.url=http://localhost:9000

# Authentication token (add after generating)
# sonar.login=your-token-here

4. Update .gitignore

Add to your .gitignore:

# SonarQube
.scannerwork/
.sonarqube/

5. Start SonarQube

# Start Docker Desktop first
open -a Docker

# Start SonarQube server
yarn sonar:start

# Wait 1-2 minutes, then check logs
yarn sonar:logs

6. Generate Authentication Token

Open http://localhost:9000
Login with admin / admin
Change password when prompted
Go to Profile Icon → My Account → Security
Generate token:
- Name: local-scanner
- Type: Global Analysis Token
Copy the token immediately!

7. Add Token to Configuration

Edit sonar-project.properties and uncomment the last line:

sonar.login=your-generated-token-here

8. Install Sonar Scanner

npm install --save-dev @sonar/scan
# or
yarn add -D @sonar/scan

9. Run Your First Scan

# Run tests with coverage
yarn test --coverage

# Run SonarQube analysis
yarn sonar

View results at http://localhost:9000

Daily Usage

# Start server (if not running)
yarn sonar:start

# After making code changes
yarn test --coverage && yarn sonar

# View results at http://localhost:9000

# Stop server when done
yarn sonar:stop

Configuration for Different Projects

For Node.js/Express Backend:

sonar.sources=src
sonar.tests=src
sonar.test.inclusions=**/*.test.js,**/*.spec.js

For React Native:

sonar.sources=src
sonar.tests=__tests__
sonar.exclusions=**/android/**,**/ios/**

Common Issues

Docker not running:

open -a Docker
# Wait 30 seconds, then retry

Port 9000 in use:

lsof -i :9000
# Kill the process or change port in docker-compose.yml

Authentication error:

# Verify token in sonar-project.properties
cat sonar-project.properties | grep sonar.login

What Gets Analyzed

Code quality issues
Potential bugs
Security vulnerabilities
Test coverage
Duplicate code
Complexity metrics

Key Benefits

✅ Catch bugs before production

✅ Improve code maintainability

✅ Track test coverage

✅ Enforce coding standards

✅ Identify security issues early

Useful Commands

yarn sonar:start   # Start server
yarn sonar:stop    # Stop server
yarn sonar:down    # Stop and remove containers
yarn sonar:logs    # View logs
yarn sonar         # Run analysis

That's it! Keep SonarQube running in the background and scan your code regularly to maintain high-quality standards.

Resources:

DEV Community: Ajmal Hasan

Jev & System One Models — Fast Decision Making for AI Agents

What You'll Learn

1. What Is Jev?

The Simple Idea

2. What Are "System One" Models?

System One Model Definition

How It's Trained

3. How Jev Works — State + Questions

The API Request Format

The API Response

4. The Three Question Types

4a. Noul (Yes/No)

4b. Choice (Pick One from Options)

4c. Score (Rate on a Scale)

5. Multiple Questions in One Request

6. Using Jev with LangChain

Installation

Setting Up

Basic Classification with TypeSafeClassifier

Multi-Question Example

7. Real-World Use Cases with LLM Agents

7a. Model Routing (Use Cheap Model vs Expensive Model)

7b. Agent Guardrails / Auto Mode (Tool Risk Gating)

7c. Email Triage at Scale

7d. Support Ticket Classification & Routing

8. Where Jev Fits in the Agent Loop

9. Jev vs LLM Structured Output — When to Use Which?

Decision Flowchart

10. Quick Reference

Setup Cheat Sheet

Question Type Cheat Sheet

Cost Comparison

Links & Resources

RAG for Beginners: 5 Levels of Building an AI That Actually Knows Your Stuff

First, What Even Is RAG? 🤔

Level 1: Basic RAG — Teaching AI to Read Your Documents 📄

Building the "library" first (ingestion)

Actually answering a question (querying)

Level 2: Hybrid Search — Two Search Buddies Beat One 🤝

The fix: Reciprocal Rank Fusion (RRF)

Level 3: Single Agent — Giving the AI a Toolbox 🧰

Enter the agent

Level 4: Multi-Agent Orchestrator — Hiring Specialists Instead of One Generalist 🏥

Level 5: Knowledge Assistant (RAG + MCP) — Usable by Literally Anything 🔌

Putting It All Together 🎯

📐 Mathematics for AI — Foundation Course

🔄 How an LLM Actually Works — The Complete Pipeline

📚 Core Concepts

1. Number Systems & Encoding

2. Probability & Prediction

3. Vectors & Embeddings

4. Algebra & Model Formulas

5. Statistics

6. Matrices & Linear Algebra

7. Calculus & Optimization

8. Information Theory

🧠 The Complete Training Loop

⚠️ Common Pitfalls in Model Training

Overfitting vs. Underfitting

Regularization Techniques

💡 Key Takeaways

🚀 Advanced Roadmap (Next Steps)

🐍 Python Essentials for GenAI

Everything a JS/React Native Developer Needs to Know

1. JavaScript → Python Mental Model

Syntax Cheat Sheet

Indentation = Curly Braces

Truthiness Differences

2. Data Structures

Lists (= JavaScript Arrays)

List Comprehensions (Python Superpower)

Dictionaries (= JavaScript Objects)

Tuples (Immutable Lists — No JS Equivalent)

Sets (= JavaScript Sets)

3. Functions

Function Definitions

Lambda Functions (= Arrow Functions)

Higher-Order Functions

4. Object-Oriented Python

Basic Classification with `TypeSafeClassifier`

JavaScript/React (`js-*`)

Native (`native-*`)

Bundling (`bundle-*`)