Showing posts with label AIML. Show all posts

Confusion Matrix + Precision/Recall (Super Simple, With Examples)

1) Binary Classification Setup

Binary classification means the model predicts one of two classes:

Positive (1) → e.g., Fraud, Spam, Disease present
Negative (0) → e.g., Not Fraud, Not Spam, Healthy

Important: “Positive” does not mean “good”. It just means the class you care about detecting.

2) Confusion Matrix (The 2×2 Table)

A confusion matrix compares Actual vs Predicted:


                 Predicted
               0 (Negative)   1 (Positive)
Actual 0 (Neg)     TN            FP
Actual 1 (Pos)     FN            TP

✅ The 4 outcomes (all combinations)

1) True Positive (TP)

Actual = Positive (1)
Predicted = Positive (1)

Example (Fraud):

Transaction is fraud ✅
Model says fraud ✅

2) True Negative (TN)

Actual = Negative (0)
Predicted = Negative (0)

Example:

Transaction is not fraud ✅
Model says not fraud ✅

3) False Positive (FP) — “False Alarm”

Actual = Negative (0)
Predicted = Positive (1)

Example:

Not fraud ❌
Model says fraud ✅ (wrong)

Impact: blocks good users, annoys customers

4) False Negative (FN) — “Miss”

Actual = Positive (1)
Predicted = Negative (0)

Example:

Fraud ✅
Model says not fraud ❌ (wrong)

Impact: fraud slips through (often expensive)

3) Precision, Recall, Accuracy (Simple Meaning)

✅ Accuracy

“Out of all predictions, how many were correct?”

Accuracy = \frac{TP + TN}{TP + TN + FP + FN}

Good when:

classes are balanced (equal positives and negatives)

✅ Precision

“When the model says Positive, how often is it correct?”

Precision = \frac{TP}{TP + FP}

High precision means:

few false positives
good when “false alarms” are costly
(e.g., blocking legitimate bank transactions)

✅ Recall (Sensitivity)

“Out of actual Positives, how many did we catch?”

Recall = \frac{TP}{TP + FN}

High recall means:

few false negatives
good when missing positives is costly
(e.g., cancer detection, fraud detection)

✅ F1 Score

“Balance between Precision and Recall”

F1 = \frac{2 \cdot Precision \cdot Recall}{Precision + Recall}

Use when:

you need a tradeoff between FP and FN

4) Real Example With Numbers (Very Clear)

Assume we have:

TP = 40
FP = 10
FN = 20
TN = 30

Precision

Precision = \frac{40}{40+10} = \frac{40}{50} = 0.80

Meaning:

When we say “Positive”, we’re correct 80% of the time.

Recall

Recall = \frac{40}{40+20} = \frac{40}{60} \approx 0.67

Meaning:

We catch 67% of all real positives.

Accuracy

Accuracy = \frac{40+30}{100} = 0.70

5) Small Python Code Example (Confusion Matrix + Precision/Recall)


from sklearn.metrics import confusion_matrix, classification_report, precision_score, recall_score

# Actual labels (ground truth)
y_true = [1, 0, 1, 1, 0, 0, 1, 0, 0, 1]

# Model predictions
y_pred = [1, 0, 0, 1, 0, 1, 1, 0, 0, 0]

cm = confusion_matrix(y_true, y_pred)
print("Confusion Matrix:\n", cm)

tn, fp, fn, tp = cm.ravel()
print("\nTN:", tn, "FP:", fp, "FN:", fn, "TP:", tp)

print("\nPrecision:", precision_score(y_true, y_pred))
print("Recall:", recall_score(y_true, y_pred))

print("\nClassification Report:\n", classification_report(y_true, y_pred))

Output interpretation

cm.ravel() gives: TN, FP, FN, TP (in that order)
Use this to clearly see FP vs FN

6) How to Remember FP vs FN (Super Easy Trick)

False Positive (FP) = “False Alarm”

Model says Positive
But it’s actually Negative

Example: Spam filter puts real email into spam ❌

False Negative (FN) = “Miss”

Model says Negative
But it’s actually Positive

Example: Fraud transaction not detected ❌

7) When to Focus on Precision vs Recall (Interview Ready)

Focus on Precision when FP is costly

Spam filter (don’t block important emails)
Payment fraud block (don’t block genuine customers)
Legal/Compliance flags

Focus on Recall when FN is costly

Cancer detection (don’t miss disease)
Fraud detection (don’t miss fraud)
Security intrusion detection

8) Final Summary (One Paragraph)

A confusion matrix shows TP, TN, FP, FN. False positives are “false alarms” (predict positive when actually negative). False negatives are “misses” (predict negative when actually positive). Precision measures how reliable positive predictions are (reduces FP). Recall measures how many real positives are detected (reduces FN). F1 balances precision and recall, and accuracy is overall correctness but can be misleading when classes are imbalanced.

AI/ML Basics — Supervised vs Unsupervised Learning (Simple Guide + Code)

1) What is Machine Learning?

Machine Learning (ML) helps computers learn patterns from data so they can:

predict outcomes (e.g., house price)
classify things (e.g., spam vs not spam)
group similar items (e.g., customer segments)

2) Supervised vs Unsupervised Learning

✅ Supervised Learning (Labeled Data)

What

You train a model using:

input features X
known output labels/targets y

Example:

X = [size, bedrooms]
y = house_price

Goal

Learn a mapping:

X → y

Common problems

Regression: predict a number (price, demand, temperature)
Classification: predict a category (spam/ham, fraud/not fraud)

✅ Unsupervised Learning (Unlabeled Data)

What

You only have X, but no labels y.

Example:

customer data: spending, visits, age
(no “segment label” provided)

Goal

Discover structure:

clusters (groups)
similarity
hidden patterns

Common problems

Clustering (K-Means, Hierarchical)
dimensionality reduction (PCA)

3) Supervised Learning Algorithms (with Simple Code)

3.1 Linear Regression (Regression)

Use case

Predict a continuous value:

house price
sales forecast

Code (Simple)


from sklearn.model_selection import train_test_split
from sklearn.linear_model import LinearRegression
from sklearn.metrics import mean_squared_error
import numpy as np

# Sample data: X = [area], y = price
X = np.array([[500], [800], [1000], [1200], [1500], [1800]])
y = np.array([150, 220, 280, 330, 400, 480])  # price (in thousands)

X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.33, random_state=42)

model = LinearRegression()
model.fit(X_train, y_train)

pred = model.predict(X_test)

print("Predictions:", pred)
print("MSE:", mean_squared_error(y_test, pred))
print("Slope (m):", model.coef_[0], "Intercept (b):", model.intercept_)

3.2 Logistic Regression (Classification)

Use case

Predict a category:

spam vs not spam
pass/fail
fraud/not fraud

Code (Iris dataset)


from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from sklearn.linear_model import LogisticRegression
from sklearn.metrics import accuracy_score, classification_report

iris = load_iris()
X = iris.data
y = (iris.target == 0).astype(int)  # binary: setosa(1) vs others(0)

X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.25, random_state=42)

model = LogisticRegression(max_iter=1000)
model.fit(X_train, y_train)

pred = model.predict(X_test)

print("Accuracy:", accuracy_score(y_test, pred))
print(classification_report(y_test, pred))

3.3 Random Forest (Classification + Regression)

What

Random Forest is an ensemble of many decision trees.
It reduces overfitting and works well in practice.

A) Random Forest Classifier


from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import accuracy_score

iris = load_iris()
X, y = iris.data, iris.target

X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.25, random_state=42)

model = RandomForestClassifier(n_estimators=200, random_state=42)
model.fit(X_train, y_train)

pred = model.predict(X_test)

print("Accuracy:", accuracy_score(y_test, pred))

B) Random Forest Regressor


from sklearn.model_selection import train_test_split
from sklearn.ensemble import RandomForestRegressor
from sklearn.metrics import mean_absolute_error
import numpy as np

X = np.array([[1], [2], [3], [4], [5], [6]])
y = np.array([3, 5, 7, 9, 11, 13])  # y = 2x + 1

X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.33, random_state=42)

model = RandomForestRegressor(n_estimators=200, random_state=42)
model.fit(X_train, y_train)

pred = model.predict(X_test)

print("Predictions:", pred)
print("MAE:", mean_absolute_error(y_test, pred))

4) Unsupervised Learning Algorithms (with Simple Code)

4.1 K-Means Clustering

What

K-Means groups points into K clusters by minimizing distance to cluster centers.

Use cases

customer segmentation
grouping similar products
anomaly detection (rough)

Code


from sklearn.cluster import KMeans
import numpy as np

# Example: customer data (spend, visits)
X = np.array([
    [100, 1], [120, 2], [130, 2],   # group 1
    [700, 8], [650, 7], [800, 9],   # group 2
    [300, 4], [320, 4], [280, 3]    # group 3
])

kmeans = KMeans(n_clusters=3, random_state=42)
labels = kmeans.fit_predict(X)

print("Cluster labels:", labels)
print("Centers:", kmeans.cluster_centers_)

Interpretation

Each row gets a cluster label (0/1/2)
Points with same label belong to the same group

4.2 Hierarchical Clustering (Agglomerative)

What

Builds clusters by progressively merging closest groups:

start with each point as its own cluster
merge until desired cluster count

Use cases

when you want a “cluster tree” (dendrogram concept)
small/medium datasets

Code


from sklearn.cluster import AgglomerativeClustering
import numpy as np

X = np.array([
    [1, 1], [2, 1], [2, 2],
    [8, 8], [9, 8], [8, 9]
])

model = AgglomerativeClustering(n_clusters=2, linkage="ward")
labels = model.fit_predict(X)

print("Cluster labels:", labels)

Note

"ward" works best with Euclidean distance
linkage options: ward, complete, average, single

5) When to Use Which Algorithm? (Simple Decision)

Supervised

✅ Linear Regression → numeric prediction, linear relationship
✅ Logistic Regression → simple classification, interpretable
✅ Random Forest → strong baseline for most tabular problems

Unsupervised

✅ K-Means → fast clustering when you know K
✅ Hierarchical → good when you want cluster structure and no need for huge scale

6) Interview-Friendly Summary (One Paragraph)

Supervised learning uses labeled data (X, y) to learn a mapping and is used for regression and classification (e.g., Linear Regression, Logistic Regression, Random Forest). Unsupervised learning uses only features X to find hidden patterns, mainly clustering (e.g., K-Means, Hierarchical). Linear regression predicts numbers, logistic regression predicts classes, random forests provide robust performance by combining many trees, and clustering algorithms group similar points without labels.

7) Quick Setup (Run These Examples)


pip install scikit-learn numpy

Model Context Protocol (MCP) — Complete Guide for Backend Engineers

Build Tools, Resources, and AI-Driven Services Using LangChain

Modern LLM-based applications are no longer just about generating text — they need to interact with real systems:

✅ Databases
✅ File systems
✅ Internal microservices
✅ Web APIs
✅ Analytics engines
✅ Cloud services

To support this, OpenAI introduced MCP — Model Context Protocol, a powerful standard that lets LLMs communicate with tools using a safe, structured API.

This guide gives you:

✅ Clear concepts
✅ Interview-focused explanations
✅ Step-by-step MCP server creation
✅ Examples using LangChain
✅ Text-based architecture diagrams

Perfect for your blog.

What Is MCP?

MCP (Model Context Protocol) is a unified protocol that allows AI models to access tools, resources, and files in a structured manner.

Think of it as an API gateway for LLMs.

Instead of relying only on prompts, LLMs can call tools like:


get_weather
search_files
query_database
run_sql
get_customer_orders

MCP provides:

✅ A standard interface
✅ Strong typing
✅ Clear request/response format
✅ Security boundaries
✅ Cross-language interoperability

📐 High-Level Architecture (Text-Based Diagram)


                     ┌────────────────────────┐
                     │        LLM / Agent     │
                     │  (GPT-4, LangChain,    │
                     │   Anthropic, Groq)     │
                     └────────────▲───────────┘
                                  │
                     Structured Tool Calls (JSON-RPC)
                                  │
                     ┌────────────┴───────────┐
                     │      MCP Server        │
                     │  Tools / Resources     │
                     │  Transport: stdio/ws   │
                     └────────────▲───────────┘
                                  │
             ┌────────────────────┼────────────────────┐
             │                    │                    │
      ┌──────┴──────┐     ┌──────┴──────┐     ┌──────┴──────┐
      │  APIs        │     │ Databases   │     │ Filesystem   │
      │ REST/GraphQL │     │ SQL/NoSQL   │     │ Logs/Docs    │
      └──────────────┘     └──────────────┘     └──────────────┘

🔌 MCP Transport Protocols

MCP defines how an AI agent connects to your server:

✅ 1. stdio (local execution)

Uses stdin/stdout for message passing
Zero network overhead
Ideal for CLI tools, dev workflows

✅ 2. websocket (remote execution)

Perfect for cloud microservices
Works with Kubernetes, ECS, GKE, etc.
Supports multiple LLM clients

✅ 3. HTTP (proxy adapters)

HTTP isn't native in MCP but supported via
Nginx/Envoy/Gateway adapters.

🛠️ Building a Simple MCP Server (LangChain)

Below is a minimal MCP server using LangChain + FastAPI.

✅ Install dependencies


pip install langchain langchain-core fastapi uvicorn mcp-server-fastapi

✅ Step 1: Create Tools


from langchain.tools import tool
import requests, os

@tool
def get_weather(city: str) -> str:
    """Return temperature and weather for a given city."""
    return requests.get(f"https://wttr.in/{city}?format=3").text

@tool
def list_files(folder: str) -> list:
    """List files in a directory."""
    return os.listdir(folder)

✅ Step 2: Create the MCP Server


from mcp_server_fastapi import MCPServer
from fastapi import FastAPI

app = FastAPI()
server = MCPServer(app, title="Utility MCP Server")

server.add_tool(get_weather)
server.add_tool(list_files)

✅ Step 3: Run the MCP Server


uvicorn main:app --host 0.0.0.0 --port 8000

MCP endpoint available at:


ws://localhost:8000/mcp

🧰 Exposing Resources

You can expose static or dynamic resources:


from mcp_server_fastapi import resource

@resource("config/app")
def config_resource():
    return {"version": "1.0.0", "env": "production"}

📂 Exposing File-System Resources (Read-Only)


server.mount_folder("/logs", "/var/log/myapp/")

🤖 How Agents Call MCP Tools (LangChain)


from mcp_client import MCPClient
from langchain.agents import create_openai_tools_agent, AgentExecutor
from langchain_openai import ChatOpenAI

client = MCPClient("ws://localhost:8000/mcp")
tools = client.get_tools()

llm = ChatOpenAI(model="gpt-4.1")

agent = create_openai_tools_agent(llm, tools)
executor = AgentExecutor(agent=agent, tools=tools)

result = executor.invoke({"input": "What is the weather in Bangalore?"})
print(result["output"])

🎯 Tool Invocation Flow


User Query → Agent → Selects Tool → MCP Tool Executes → Returns Structured JSON → Agent Summarizes Result

Detailed:


    ┌───────────────────────────┐
    │  User Input: "Weather?"   │
    └───────────────┬───────────┘
                    │
            Reasoning by Agent
                    │
        ┌───────────▼───────────┐
        │  Tool Call Chosen      │
        │  get_weather("BLR")    │
        └───────────┬───────────┘
                    │ JSON-RPC
                    ▼
          ┌──────────────────────┐
          │    MCP Server        │
          │ Executes API calls   │
          └───────────┬─────────┘
                      │
                JSON Result
                      │
                      ▼
         ┌──────────────────────────┐
         │ Agent Summarizes Output │
         └──────────────────────────┘

💼 Where Backend Engineers Use MCP

✅ Integrating LLMs with microservices
✅ Allowing safe access to production data
✅ Creating API-driven agents
✅ Building internal developer tooling
✅ Simplifying multi-agent systems
✅ Enabling plug-and-play AI behavior

🎤 Interview-Ready Explanation

Q: What problem does MCP solve?
✅ Standardizes how AI models interact with external tools
✅ Makes tool usage safe, typed, predictable
✅ Enables multi-tool, multi-resource workflows

Q: How does an agent know which tool to call?
The LLM sees tool schemas + natural language description →
Uses reasoning + training → selects correct tool.

Q: What’s the difference between stdio and websocket?

stdio: Local execution
websocket: Cloud execution

Q: What can MCP expose?
✅ tools
✅ resources
✅ file systems

📦 Full Project Structure


mcp-weather-server/
│
├── main.py                 # Main MCP server entry
├── tools/
│   ├── weather.py          # Weather tool
│   ├── filesystem.py       # List file tool
│
├── resources/
│   └── config.py           # Sample resource
│
├── requirements.txt
└── README.md

📊 Summary Table

Feature	Description
Tools	Functions agent can execute
Resources	Static/dynamic information exposed to LLM
FileSystem	Safe, restricted directory access
Protocols	stdio, WebSocket, HTTP (proxy)
Language Support	Python, JS, Java (soon), Go (soon)
Architecture Style	JSON-RPC 2.0

✅ Final Thoughts

MCP is quickly becoming the standard protocol for LLM-to-system integration.
For backend engineers, knowing MCP gives you a huge advantage in:

✅ AI system design
✅ Multi-agent architectures
✅ Tooling integration
✅ LLM-powered microservices

Building an Intelligent Stock Analysis Agent with MCP, Groq LLM, and Multi-Source Data

A complete walkthrough of my MCP-powered AI agent for real-time stock insights

GitHub Repo: https://github.com/kkvinodkumaran/mcp_agent_stock_demo

🧩 Introduction

In the era of LLM-powered automation, we're moving beyond simple “question → answer” chatbots. Modern AI agents plan, reason, select the right tools, and combine multiple data sources to generate deep, actionable insights.

This project — MCP Stock Analysis Agent — demonstrates how to build a fully intelligent stock-analysis workflow using:

✅ Model Context Protocol (MCP)
✅ Groq LLM (ultra-fast inference)
✅ Multi-API data fusion (Yahoo Finance, Tavily, DuckDuckGo)
✅ LLM-driven tool selection and planning
✅ React UI + FastAPI backend + MCP server

It combines real-time market data, historical trends, company fundamentals, and news sentiment into a single, adaptive AI agent.

What Problem Does This Solve?

Traditional stock apps give you raw data: prices, charts, company descriptions, or scattered news articles. But they don’t answer real questions like:

“How is Tesla performing lately?”
“What’s the recent news about Apple?”
“Show me Microsoft’s long-term price trends.”
“Give me a full analysis of Nvidia today.”

Users don’t want to assemble multiple APIs or charts themselves.

✅ We solve this by creating an AI agent that understands your query and automatically chooses the right combination of tools.

This agent:

Interprets your natural language
Determines what data you actually need
Calls the right MCP tools and APIs
Combines results
Generates a clean, human-level summary

Architecture: How the Intelligent Agent Works


┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   User Query    │───▶│ Intelligent     │───▶│   MCP Server    │
│ (Natural Lang.) │    │ Agent (LLM)     │    │   (4 Tools)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                       │
                                ▼                       ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │ Tavily API      │    │ Yahoo Finance   │
                       │ (News Search)   │    │ (Stock Data)    │
                       └─────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌─────────────────┐
                       │    Groq LLM     │
                       │ (Planning +     │
                       │   Summary)      │
                       └─────────────────┘

✅ Components

MCP Server (Port 8000)
Hosts stock-related tools exposed via the Model Context Protocol.
Agent Client (Port 8001)
An LLM-powered agent that:
- Understands user intent
- Selects tools
- Orchestrates workflow
- Summarizes insights
React UI (Port 3000)
A simple frontend to query the agent.

🔧 Tools Exposed by the MCP Server

The MCP Server provides 4 main tools:

Tool	What It Does
`get_quote`	Real-time stock price + basic metrics
`get_stock_history`	Historical data (for trend analysis)
`get_company_info`	Fundamentals, sector, market cap, description
`company_news`	DuckDuckGo-based recent news

Additionally, the agent can directly call:

✅ Tavily API (Enhanced news search with relevance ranking)

🤖 How the Agent Thinks (LLM-Based Planning & Tool Selection)

The heart of the system is Groq LLM, which interprets queries and builds a plan.

Example 1 — Comprehensive Analysis

User: “Give me a complete analysis of Tesla”
Agent reasoning:

“I need price, company fundamentals, historical trends, and recent news.”

✅ Tools Selected

get_quote
get_company_info
get_stock_history
search_news_tavily

Example 2 — News-Focused Query

User: “What’s the recent news about Apple?”
Agent reasoning:

“The user only needs news. No market data required.”

✅ Tool Selected

search_news_tavily

Example 3 — Technical Analysis

User: “Show me Microsoft price trends.”
Agent reasoning:

“Trend analysis requires historical + current price.”

✅ Tools Selected

get_stock_history
get_quote

🏗️ System Architecture Overview

✅ Services

MCP Server → provides stock tools
Agent Client → coordinates LLM and tools
React UI → user interface

✅ Workflow


User Query → LLM Planning → Tool Execution → Data Fusion → AI Summary

Quick Start Guide

✅ Prerequisites

Docker & Docker Compose
Groq API Key
Tavily API Key
Note
Get Groq API key from https://console.groq.com
Get Tavily API key from https://tavily.com

1️⃣ Clone the Repository


git clone https://github.com/kkvinodkumaran/mcp_agent_stock_demo
cd mcp_agent_stock_demo

2️⃣ Configure `.env`


GROQ_API_KEY=your_groq_key
TAVILY_API_KEY=your_tavily_key

3️⃣ Start With Docker


docker-compose up --build

Access the system:

🔌 API Usage

✅ Analyze Endpoint (LLM-Based)


curl -X POST "http://localhost:8001/analyze" \
  -H "Content-Type: application/json" \
  -d '{"query": "Analyze Tesla including recent trends"}'

Response includes:

LLM reasoning
Tools selected
Raw data
Final AI summary

🛠️ Local Development

MCP Server


cd mcp_stock_server
uv sync
uv run python server.py

Agent


cd agent_client
uv sync
uv run uvicorn app.main:app --host 0.0.0.0 --port 8001

UI


cd ui
npm install
npm start

🔍 How It All Works (Under the Hood)

✅ Step-by-step pipeline

User sends a natural-language query
Groq LLM interprets the intent
Agent selects required MCP tools
Tools fetch data (Yahoo Finance, Tavily, DuckDuckGo)
Agent merges data from all sources
Groq LLM generates the final summary

📈 Intelligent Behaviors (Live Examples)

✅ “How is Tesla performing?”

Agent chooses:

get_quote
search_news_tavily

✅ “Give me Tesla's financial details”

Agent chooses:

get_company_info
get_quote

✅ “Analyze Tesla’s price trends”

Agent chooses:

get_stock_history
get_quote

🧱 Why MCP?

MCP (Model Context Protocol) is designed for:

✅ Standardized tools
✅ Dynamic discovery
✅ LLM-friendly interfaces
✅ Easy extensibility

This project shows how to expose your own tools for an AI agent.

🐳 Docker Deployment

All three services run in isolated containers
Health checks ensure reliability
Logs available via:


docker-compose logs agent-client
docker-compose logs mcp-server

🧰 Troubleshooting

LLM not selecting tools?

→ Check GROQ_API_KEY.

News not loading?

→ Check TAVILY_API_KEY.

MCP tools not available?

→ Check:


curl http://localhost:8000/list_tools