DEV Community: Amir Ehsan Ahmadzadeh

How Actually Your Functions Get Called By LLMs?

Amir Ehsan Ahmadzadeh — Mon, 03 Aug 2026 18:59:21 +0000

How do tool calls actually happen?

That was the question that started this investigation for me.

I kept seeing examples like this:

@agent.tool
def get_weather(city: str) -> dict:
    return weather_api.fetch(city)

Then the explanation would casually say:

“The LLM calls the get_weather function.”

But... how?

Does the LLM reach into my Python process and execute that function?

Does it know where the function exists in memory?

Can it directly access my database, local files, or private APIs?

If an LLM receives input and generates output, how can it possibly call anything?

And if model providers already support native tool calling, why do we need agent frameworks such as PydanticAI, LangChain, or LangGraph?

That led me to several more questions:

Who actually executes the function?
How does the function result get back to the model?
Is tool calling just a sophisticated prompting technique?
Is LangChain merely adding instructions around an LLM?
Can I build the entire loop myself?
What does an agent framework provide beyond the loop?
Is MCP the same thing as tool calling?
Do I need an agent framework for every LLM application?

My original mental model was simple:

input → LLM → output

That model seemed incompatible with phrases such as:

The LLM called a tool.

So I decided to stop treating the process like magic and follow the data through real framework code. 🔍

This article documents what I found.

First: how I verified the claims in this article 🔬

Before explaining the architecture, I want to make the evidence trail explicit.

This is not based only on diagrams, AI generated explanations, or second-hand tutorials. Sure I used help of AI creating this article, But I assure you that I validated the results during my study, so you can rely on the results.

I checked:

The public documentation for PydanticAI and LangChain.
The current agent orchestration implementations.
The code that validates model-generated tool arguments.
The exact lines that invoke registered tools.
The code that converts function results back into model messages.
Commit-pinned revisions so the evidence remains inspectable after main changes.

Source-review timestamp

The source review for this article was completed on:

August 3, 2026 at 20:42 CEST

Inspected source snapshots

The commits below are the latest revisions I found for the specific files at the time of review. They are file-specific revisions, not necessarily the repository-wide HEAD commits.

Project	File	Inspected commit
PydanticAI	`_agent_graph.py`	`5dee1ea37c86df4764ff143ef4259dc8027ab81e`
PydanticAI	`tool_manager.py`	`fbabc0f2d04be7b67c00d18e7e2c4fcfe0310ed2`
PydanticAI	`_tool_execution.py`	`d8a1254a5ad1a86d0164d497f43f12616069d6cf`
LangChain	`agents/factory.py`	`9ef324c9abb534b4839bd2a42f4fb36b1ec3f3c3`
LangGraph	`prebuilt/tool_node.py`	`2b1abc807b282245211f5ba8f292aaf3e24f1e07`

The relevant commit-pinned files are linked throughout the article.

That matters because internal framework code changes.

A link to main shows whatever the project contains today. A commit-pinned link shows exactly what I inspected while writing this article.

The practical examples use Python, but the architecture is not Python-specific.

The same loop appears in TypeScript, Go, C#, Rust, and other languages:

model request
→ structured tool request
→ runtime validation
→ ordinary function execution
→ tool-result message
→ another model request

Python simply gives us readable framework implementations to inspect.

The answer in one paragraph 💡

An LLM does not directly execute my function.

It generates output that may represent a request to call a function.

My application—or an agent framework running inside it—reads that request, matches it to an available tool, validates the arguments, checks permissions, executes the real function, captures the result, returns that result to the model, and continues the loop.

The model proposes an action. The runtime validates, governs, and executes it.

Even native tool calling is still structured model output.

A model response may contain something logically similar to:

{
  "name": "get_weather",
  "arguments": {
    "city": "Tokyo"
  }
}

At that moment:

get_weather() has not run.
No weather API has been contacted.
No Python function has been invoked.
No external side effect has happened.

The model has produced a structured request.

Something else must execute it.

That “something else” is application code, framework code, or—in the case of certain provider-hosted tools—provider-operated runtime infrastructure.

It is not the neural network itself.

The four actors involved 🧩

The architecture becomes much clearer when I separate four components:

The LLM.
The provider API or model adapter.
The application or agent framework.
The actual tool implementation.

They cooperate, but they do not perform the same job.

1. The LLM: generating tokens and action requests 🧠

At its core, the model performs something conceptually similar to:

input tokens → model computation → output tokens

Depending on the provider, those output tokens may be interpreted as:

Natural-language text.
JSON.
Structured content blocks.
A tool-call object.
Several tool calls.
A mixture of text and action requests.

The raw model does not directly:

Run Python.
Execute JavaScript.
Query my database.
Read arbitrary files from my computer.
Send an email from my account.
Call my private API.
Modify application state.
Refund a payment.
Restart my production server.

It can generate text that describes any of those actions.

It can also generate structured output requesting that surrounding software perform one of them.

That distinction is the foundation of tool calling.

2. The provider API: giving tool requests a structure

Model providers define conventions for presenting tools to models and returning tool requests to applications.

A model request may include:

Conversation messages.
System instructions.
Tool names.
Tool descriptions.
JSON Schemas for tool arguments.
Tool-selection settings.

A provider response may contain:

Normal assistant text.
One tool call.
Multiple tool calls.
Provider-specific content blocks.
Text combined with tool requests.

The provider API makes the generated action request easier for application code to interpret.

It does not automatically possess or execute a local function running inside my application.

The provider may know this:

{
  "name": "get_customer",
  "description": "Retrieve a customer by ID.",
  "parameters": {
    "type": "object",
    "properties": {
      "customer_id": {
        "type": "string"
      }
    },
    "required": ["customer_id"]
  }
}

But it does not automatically have this:

def get_customer(customer_id: str) -> dict:
    return my_private_database.find_customer(customer_id)

The schema and the implementation are different things.

One important exception: provider-hosted tools

Some providers expose tools that run on their own infrastructure, such as hosted web search, file search, or code execution.

In those cases, provider software may execute the tool.

But even then, the model weights are not directly operating the server.

The model generates an action request, and a controlled provider runtime executes it.

The architecture still contains a separation between:

model decision

and:

external execution

Prompt-based tool use versus native tool calling

Before native tool APIs became common, applications often told models:

If you need a tool, return JSON containing:
- the tool name
- the arguments

A model might answer:

{
  "name": "get_customer",
  "arguments": {
    "customer_id": "cust-1001"
  }
}

The application would then:

Parse the JSON.
Resolve the tool name.
Validate the arguments.
Execute the function.
Send the result back to the model.

With native tool calling, the application sends tool definitions through a dedicated API field, and the provider returns a dedicated tool-call structure.

Conceptually:

{
  "tool_calls": [
    {
      "id": "call_123",
      "name": "get_customer",
      "arguments": {
        "customer_id": "cust-1001"
      }
    }
  ]
}

Both approaches involve the model generating an action request.

Native tool calling generally provides:

Better message structure.
Provider-supported call IDs.
More reliable argument handling.
Easier support for multiple calls.
Clearer separation between text and actions.
Less fragile output parsing.

It does not eliminate the execution loop.

3. The application or framework: running the loop 🔁

The application or agent framework owns the orchestration.

It commonly performs these operations:

Send messages and available tool definitions to the model.
Read the model response.
Detect tool requests.
Match each requested name to an implementation.
Validate the arguments.
Check authorization and approval rules.
Execute the actual tool.
Capture its result or exception.
Create a tool-result message.
Send the updated conversation back to the model.
Continue until the model returns a final answer.

A production framework may also handle:

Streaming.
Parallel tool calls.
Retries.
Invalid-argument correction.
Timeouts.
Cancellation.
Token budgets.
Cost limits.
Maximum-step limits.
Dependency injection.
Conversation state.
Durable execution.
Checkpoints.
Human approval.
Structured outputs.
Logging and tracing.

This orchestration layer is where agent frameworks earn most of their value.

4. The tool: ordinary executable software 🛠️

The tool itself is normal code:

def get_weather(city: str) -> dict[str, object]:
    return weather_api.fetch(city)

It might instead be:

async function getWeather(city: string): Promise<Weather> {
  return weatherApi.fetch(city);
}

Or:

func GetWeather(ctx context.Context, city string) (Weather, error) {
    return weatherClient.Fetch(ctx, city)
}

The language does not change the architectural boundary.

The function runs because some runtime invokes it.

The neural network does not reach into the language runtime and call it directly.

Following one tool call from beginning to end

Let’s use one tool throughout the article:

def get_customer(customer_id: str) -> dict[str, str]:
    ...

The user asks:

What subscription plan is customer cust-1001 using?

Here is the full lifecycle.

Step 1: The application sends the model a tool definition

The application sends:

The user’s message.
Relevant instructions.
The get_customer tool definition.
A schema describing its arguments.

A simplified definition might look like:

{
  "name": "get_customer",
  "description": "Retrieve a customer by customer ID.",
  "parameters": {
    "type": "object",
    "properties": {
      "customer_id": {
        "type": "string"
      }
    },
    "required": ["customer_id"]
  }
}

The model can now infer that get_customer may help answer the question.

It still cannot directly execute the implementation.

Step 2: The model generates a tool request

The response may be normalized into:

{
  "tool_calls": [
    {
      "id": "call_123",
      "name": "get_customer",
      "arguments": {
        "customer_id": "cust-1001"
      }
    }
  ]
}

At this point, the customer function has still not run.

The model has effectively written a request ticket:

Please run get_customer with customer_id="cust-1001".

Step 3: The runtime validates the request

The application or framework asks:

Does get_customer exist?
Was it exposed to this model invocation?
Is customer_id present?
Is its value a string?
Is this user allowed to access cust-1001?
Does the operation require human approval?
Has the agent exceeded its step limit?

Only after these checks should the runtime execute the tool.

Step 4: Ordinary software invokes the function

The framework performs something logically equivalent to:

result = get_customer(customer_id="cust-1001")

The function might return:

{
  "id": "cust-1001",
  "name": "Alice",
  "plan": "pro"
}

This is the moment when the actual work happens.

The database was queried by application code.

The model generated the proposal.

Step 5: The runtime creates a tool-result message

The function’s return value must be represented in the conversation:

{
  "role": "tool",
  "tool_call_id": "call_123",
  "content": {
    "id": "cust-1001",
    "name": "Alice",
    "plan": "pro"
  }
}

Provider formats differ, but the purpose is the same:

Associate the result with the correct tool request.
Make the result visible to the model.

Step 6: The model is called again

The next model request contains:

The original question.
The model’s earlier tool call.
The tool result.

The model can now answer:

Customer cust-1001 is using the Pro plan.

The complete sequence looks like this:

sequenceDiagram
    actor User
    participant Runtime as Application / Agent Framework
    participant Model as LLM Provider
    participant Tool as Tool Implementation

    User->>Runtime: What plan is cust-1001 using?
    Runtime->>Model: Messages + get_customer schema
    Model-->>Runtime: Tool request: get_customer(cust-1001)

    Note over Runtime,Tool: The model requested an action.<br/>The function has not run yet.

    Runtime->>Runtime: Validate arguments and permissions
    Runtime->>Tool: Invoke get_customer("cust-1001")
    Tool-->>Runtime: {"plan": "pro"}

    Runtime->>Model: Tool-result message
    Model-->>Runtime: Customer cust-1001 uses the Pro plan
    Runtime-->>User: Final response

The most important detail is the missing direct connection:

LLM ─────X────→ local function

The runtime sits between the model and the executable code.

Building the loop without a framework

Once I understood the data flow, the basic loop looked surprisingly small.

The following is intentionally provider-neutral pseudocode:

async def run_agent(user_message: str) -> str:
    messages = [
        {
            "role": "user",
            "content": user_message,
        }
    ]

    for _ in range(10):
        response = await call_model(
            messages=messages,
            tools=tool_schemas,
        )

        messages.append(response.message)

        if not response.tool_calls:
            return response.text

        for call in response.tool_calls:
            tool = tool_registry[call.name]

            arguments = validate_arguments(
                tool=tool,
                arguments=call.arguments,
            )

            authorize_tool_call(
                tool=tool,
                arguments=arguments,
                current_user=current_user,
            )

            result = await execute_tool(
                tool=tool,
                arguments=arguments,
            )

            messages.append(
                {
                    "role": "tool",
                    "tool_call_id": call.id,
                    "content": serialize(result),
                }
            )

    raise RuntimeError("Maximum agent steps exceeded")

This is the heart of many agent frameworks.

What each stage does

`call_model(...)`

This converts application messages and tool schemas into the provider’s request format.

It also converts the provider response into objects the application can inspect.

`response.tool_calls`

These calls are model-generated output.

The model may:

Select the wrong tool.
Invent a tool name.
Omit an argument.
Use the wrong type.
Request an unauthorized resource.
Produce semantically dangerous arguments.

Structured output is not automatically trustworthy output.

`tool_registry[call.name]`

The runtime resolves a generated string to an executable implementation:

tool_registry = {
    "get_customer": get_customer,
    "search_orders": search_orders,
}

This is a crucial security boundary.

The model can only request tools that the application exposes and resolves.

`validate_arguments(...)`

Validation checks whether generated arguments match the expected structure.

For example:

class GetCustomerArguments(BaseModel):
    customer_id: str

This can prove that customer_id is a string.

It cannot prove that the current user is allowed to access that customer.

`authorize_tool_call(...)`

Authorization is a business decision, not a schema decision.

if customer_id not in current_user.allowed_customers:
    raise PermissionError("Customer access denied")

`execute_tool(...)`

This is where the actual side effect occurs.

The executor may need to support:

Sync and async functions.
Exceptions.
Timeouts.
Cancellation.
Approval.
Tracing.
Sandboxing.
Dependency injection.

The step limit

Without a stopping guard, the model could repeatedly request tools:

model → tool → model → tool → model → tool → ...

A maximum-step limit is ordinary defensive engineering.

The loop itself is not magic. The engineering around the loop is where frameworks earn their keep.

Proof from PydanticAI’s implementation 🔬

Now let’s move past conceptual pseudocode and inspect a real framework.

The public starting points are:

The documentation shows that PydanticAI can derive a tool schema from a Python function’s signature and docstring.

A current-style example looks like:

import asyncio
import os

from pydantic_ai import Agent


CUSTOMERS = {
    "cust-1001": {
        "id": "cust-1001",
        "name": "Alice",
        "plan": "pro",
    }
}


agent = Agent(
    os.environ["MODEL"],
    instructions=(
        "Answer questions about customer subscriptions. "
        "Use get_customer when customer data is required."
    ),
)


@agent.tool_plain
async def get_customer(customer_id: str) -> dict[str, str]:
    """Retrieve a customer by customer ID."""
    customer = CUSTOMERS.get(customer_id)

    if customer is None:
        return {
            "id": customer_id,
            "error": "Customer not found",
        }

    return customer


async def main() -> None:
    result = await agent.run(
        "What subscription plan is customer cust-1001 using?"
    )
    print(result.output)


if __name__ == "__main__":
    asyncio.run(main())

The public API is convenient, but it does not show us who invokes the function.

For that, we need to follow the internal execution path.

PydanticAI step 1: the model response enters the graph

In the inspected revision of _agent_graph.py, a model response containing tool calls is routed to a CallToolsNode.

The relevant transition is logically represented by:

return CallToolsNode[DepsT, NodeRunEndT](last_message)

This tells us something important:

The model response does not execute the Python function by itself.

The response is handed to another runtime node responsible for processing tool requests.

PydanticAI step 2: validation and execution are separate operations

Inside the inspected revision of _tool_execution.py, the framework first validates the model-generated call:

validated = await self.tool_manager.validate_tool_call(call)

Then it executes the validated call:

tool_result = await self.tool_manager.execute_tool_call(validated)

That separation is excellent evidence of the actual boundary:

model-generated tool request
→ framework validation
→ framework execution

The model is not performing either operation.

PydanticAI step 3: the tool manager invokes executable code

The inspected revision of tool_manager.py eventually delegates the validated call to the registered tool set:

return await self.toolset.call_tool(
    name,
    validated.validated_args,
    validated.ctx,
    validated.tool,
)

That is the real execution handoff.

The framework has:

Received a generated tool request.
Resolved the tool.
Validated its arguments.
Invoked registered executable code.

There is no mystery left in this part of the path.

PydanticAI step 4: the result becomes a model message

After execution, _tool_execution.py creates a ToolReturnPart.

Conceptually, that part contains:

The tool name.
The returned content.
The tool-call ID.
Additional metadata.

The result is then included in a later model request.

The PydanticAI documentation also exposes this sequence through its message history:

ToolCallPart
→ actual tool execution
→ ToolReturnPart
→ later model response

That is the framework loop made visible.

PydanticAI’s execution path

Agent receives registered tool
        ↓
Tool schema is generated
        ↓
Provider adapter sends schema to model
        ↓
Model returns ToolCallPart
        ↓
Agent graph routes response to CallToolsNode
        ↓
ToolManager validates the call
        ↓
ToolManager executes the registered tool
        ↓
ToolReturnPart is created
        ↓
Result is sent in another model request
        ↓
Model produces final text or another tool call

Useful source symbols include:

ModelRequestNode
CallToolsNode
ToolManager
ToolCallPart
ToolReturnPart
validate_tool_call
execute_tool_call

These are internal implementation details, not stable public APIs.

If a symbol moves in a future release, search the repository rather than assuming the path remains permanent:

rg "CallToolsNode" pydantic-ai
rg "validate_tool_call" pydantic-ai
rg "execute_tool_call" pydantic-ai
rg "ToolReturnPart" pydantic-ai

Proof from LangChain and LangGraph 🔬

Now let’s follow the same operation through the current LangChain agent stack.

Official starting points:

A current LangChain example for the same use case looks like:

import os

from langchain.agents import create_agent
from langchain.tools import tool


CUSTOMERS = {
    "cust-1001": {
        "id": "cust-1001",
        "name": "Alice",
        "plan": "pro",
    }
}


@tool
def get_customer(customer_id: str) -> dict[str, str]:
    """Retrieve a customer by customer ID."""
    customer = CUSTOMERS.get(customer_id)

    if customer is None:
        return {
            "id": customer_id,
            "error": "Customer not found",
        }

    return customer


agent = create_agent(
    model=os.environ["MODEL"],
    tools=[get_customer],
    system_prompt=(
        "Answer questions about customer subscriptions. "
        "Use get_customer when customer data is required."
    ),
)


result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": (
                    "What subscription plan is customer "
                    "cust-1001 using?"
                ),
            }
        ]
    }
)

print(result["messages"][-1].content)

Again, the public API hides most of the loop.

So let’s follow the source.

LangChain step 1: `create_agent` constructs a loop

In the inspected revision of LangChain’s agents/factory.py, the create_agent documentation describes its purpose directly:

"""Creates an agent graph that calls tools in a loop until a stopping condition is met."""

This is not merely a prompt template.

The factory constructs graph-based orchestration around:

A model node.
Tool routing.
Tool execution.
State updates.
Stopping conditions.

The implementation imports LangGraph components including ToolNode and message types such as ToolMessage.

LangChain step 2: the model returns tool calls

The model does not execute the tool.

It returns an AI message containing structured tool-call data.

Conceptually:

{
  "name": "get_customer",
  "args": {
    "customer_id": "cust-1001"
  },
  "id": "call_123"
}

Graph routing examines that message.

If tool calls are present, execution moves to the tool node.

If no tool calls are present, the graph can stop and return the final answer.

LangGraph step 3: `ToolNode` invokes the registered tool

The decisive evidence appears in the inspected revision of LangGraph’s tool_node.py.

For synchronous tools, the execution path contains:

response = tool.invoke(call_args, config)

For asynchronous tools, it contains:

response = await tool.ainvoke(call_args, config)

That is the actual function-execution boundary.

The model generated a request.

ToolNode resolved the registered tool and invoked it through normal runtime code.

The source does not require us to guess who performs the execution.

It shows us.

LangGraph step 4: the result becomes a `ToolMessage`

After the invocation, ToolNode normalizes the result into a ToolMessage.

That message contains information such as:

The returned content.
The tool name.
The tool-call ID.
Status or error information.

The message is appended to graph state.

The graph then returns to the model node, allowing the model to read the tool result and decide whether to:

Answer the user.
Request another tool.
Retry with different arguments.
Continue another branch of the workflow.

LangChain and LangGraph’s execution path

Python function is converted to a tool
        ↓
Tool schema is bound to the chat model
        ↓
Model returns AIMessage with tool_calls
        ↓
Graph routing detects tool_calls
        ↓
ToolNode resolves the requested tool
        ↓
ToolNode calls tool.invoke() or tool.ainvoke()
        ↓
Result is converted to ToolMessage
        ↓
ToolMessage is added to graph state
        ↓
Graph returns to model node
        ↓
Execution stops when no tool call remains

Useful source searches include:

rg "create_agent" langchain
rg "bind_tools" langchain
rg "class ToolNode" langgraph
rg "tool.invoke" langgraph
rg "tool.ainvoke" langgraph
rg "ToolMessage" langchain langgraph

A note about old LangChain tutorials

Many older tutorials use concepts such as:

AgentExecutor
format_to_tool_messages
classic tool-calling agents
agent scratchpads

Those examples belong to earlier or classic LangChain APIs.

Modern create_agent examples increasingly expose graph-based execution built with LangGraph components.

That does not make the older material useless, but mixing classic APIs with modern APIs in one runnable example can create confusion.

When reading framework articles, always check:

The publication date.
The installed package version.
Whether the example uses classic or current APIs.
Whether the linked source still matches the explanation.

What these source tours prove

PydanticAI and LangChain/LangGraph organize their internals differently, but both implement the same fundamental loop:

model produces structured tool request
        ↓
framework reads request
        ↓
framework validates and resolves tool
        ↓
framework invokes executable code
        ↓
framework converts result into message
        ↓
framework calls model again

PydanticAI makes the sequence visible through concepts such as:

CallToolsNode
ToolManager
validate_tool_call
execute_tool_call
ToolReturnPart

LangChain and LangGraph expose the sequence through concepts such as:

create_agent
tool_calls
ToolNode
tool.invoke
tool.ainvoke
ToolMessage

Different abstractions, same architectural boundary.

The LLM creates the request. The runtime performs the side effect.

Why not keep a handwritten loop?

For a small application, I often should.

The handwritten loop is excellent when:

Learning how tool calling works.
Building a prototype.
Using a single provider.
Exposing one to three tools.
Wanting maximum transparency.
Having simple request-response behavior.

The complexity grows when I need:

Provider-specific adapters.
Streaming.
Parallel calls.
Tool-call retries.
Validation-error feedback.
Tool exception handling.
Maximum-step limits.
Token and cost budgets.
Dependency injection.
Durable state.
Checkpoints.
Human approval.
Authorization.
Observability.
Structured outputs.
Cancellation.
Timeouts.
User-specific tool visibility.
Deterministic tests.

Eventually, my tiny loop contains:

A state machine.
A tool registry.
Validators.
Adapters.
Retry policies.
Middleware.
Persistence.
Tracing.
Error translation.

At that point, I am building an agent framework—just one with a single maintainer and no documentation. 😅

PydanticAI versus LangChain/LangGraph

This is not a popularity contest.

They emphasize different developer experiences.

Concern	Handwritten loop	PydanticAI	LangChain/LangGraph
Learning the fundamentals	Excellent	Good	Good
Minimal dependencies	Excellent	Moderate	Lower
Type-driven development	Manual	Strong focus	Supported
Pydantic validation	Manual	Central design	Optional/integrated
Complex graph workflows	Manual	Possible	Strong focus
Provider support	Manual	Framework-supported	Broad ecosystem
State and persistence	Manual	Available patterns	Core LangGraph strength
Human-in-the-loop	Manual	Supported patterns	Strong graph support
Source-code surface	Small initially	Focused	Larger ecosystem
Production orchestration	Must build it	Provided abstractions	Extensive abstractions

Consider PydanticAI when

The application is primarily Python.
Strong runtime validation matters.
You prefer type-oriented APIs.
You want explicit dependency patterns.
You need structured outputs.
You like Pydantic’s development model.

Consider LangChain and LangGraph when

The workflow branches.
Execution must resume after interruption.
Durable state and checkpoints matter.
Many systems must be integrated.
Middleware is important.
Human approval is part of the workflow.
You want graph-level control.

Consider neither when

One model request solves the problem.
No tools are needed.
The workflow is tiny.
A handwritten loop is clearer.
Framework complexity would exceed application complexity.

Do not install an agent framework merely because your application contains an LLM.

A text summarizer does not need a robotic middle-management department. 🤖

What does the model decide?

The model commonly proposes:

Whether the current information is sufficient.
Whether a tool appears necessary.
Which visible tool seems appropriate.
Which arguments to generate.
Whether another call is needed after seeing a result.
How to phrase the final response.

These are probabilistic decisions.

The model may make a bad proposal.

What does the runtime decide? 🔐

The application or framework determines:

Which tools are visible.
How schemas are generated.
Whether arguments are valid.
Whether the user is authorized.
Whether approval is required.
Whether execution should be blocked.
How the function is invoked.
Which timeout applies.
How exceptions are represented.
How many iterations are permitted.
Which state is persisted.
When execution stops.
What gets logged.

For example:

if tool_call.name == "refund_payment":
    require_human_approval()

if current_user.role != "admin":
    hide_admin_tools()

if step_count >= 8:
    stop_agent()

if requested_amount > current_user.refund_limit:
    reject_tool_call()

The model may propose a refund.

The application owns the money.

A prompt such as this is not an authorization system:

Please never issue an unauthorized refund.

Prompts influence model behavior.

They do not replace deterministic controls.

Are agent frameworks just prompt templates?

Not really.

Some early agents and custom systems relied heavily on prompts such as:

When you need a tool, return JSON.

Modern providers expose structured tool definitions and tool-call responses.

Frameworks still use instructions to influence:

When tools should be used.
Which tools are appropriate.
How outputs should be formatted.

But their main responsibility is orchestration:

request
→ response
→ tool detection
→ validation
→ authorization
→ execution
→ result
→ next request
→ stopping condition

The analogy I now use is:

The LLM is the planner.
The framework is the dispatcher.
The tool is the worker.

Or:

The model writes a request ticket.
The runtime checks and routes it.
Executable software performs the operation.

Making the invisible loop visible 🔍

Agent debugging becomes much easier when I stop logging only the final answer.

I want to see:

MODEL REQUEST
AVAILABLE TOOLS
MODEL RESPONSE
MODEL TOOL CALL
VALIDATED ARGUMENTS
AUTHORIZATION RESULT
TOOL START
TOOL RESULT
MODEL FOLLOW-UP
FINAL RESPONSE

A useful trace may look like:

[model] user asks about cust-1001
[model] requests get_customer({"customer_id": "cust-1001"})
[validation] arguments accepted
[authorization] access granted
[tool] executing get_customer
[tool] returned {"id": "cust-1001", "plan": "pro"}
[model] follow-up includes tool result
[model] final answer generated

When execution behaves strangely, I check:

Did the model receive the correct tool schema?
Did it generate a tool call?
Was the requested name correct?
Were the arguments valid?
Was the user authorized?
Did the runtime invoke the tool?
Did the function succeed?
Was the result linked to the correct call ID?
Did the next request contain the result?
Why did the loop stop?

I also recommend:

Enabling framework tracing.
Inspecting raw provider responses.
Reading the full message history.
Placing breakpoints inside tools.
Testing tools independently.
Using fake models for orchestration tests.
Setting iteration limits.
Recording tool latency and failures.

Replacing this:

The agent got confused.

with this:

The second model response contained no tool_calls.

is a major debugging upgrade.

Mystery reduced. Bug acquired. 🐛

Where MCP fits

Tools do not have to be local functions.

They may be exposed by another process through a protocol such as MCP.

MCP can standardize how an application:

Discovers tools.
Reads their schemas.
Sends tool requests.
Receives results.

But MCP does not change the model loop:

model requests tool
→ application receives request
→ application invokes or forwards request
→ application receives result
→ application returns result to model

MCP and tool calling are not the same thing.

Tool calling is the model-facing action-request mechanism.
MCP is one possible application-facing protocol for connecting to external capabilities.

MCP is the next layer of this story, but it deserves its own article.

Ten misconceptions worth correcting

1. “The LLM executes my function.”

It does not.

The model generates an action request. Runtime software executes the function.

2. “Native tool calling gives the model operating-system access.”

It does not.

It provides a structured convention for tool definitions and model-generated tool requests.

3. “The framework decides everything.”

It does not.

The model commonly proposes which tool to use and which arguments to generate.

4. “The model decides everything.”

Definitely not.

The runtime controls exposure, validation, authorization, execution, state, and stopping rules.

5. “Agent frameworks are just prompt templates.”

They may use prompts, but they also implement adapters, execution loops, validation, state, retries, middleware, and tracing.

6. “MCP and tool calling are the same thing.”

They operate at different architectural layers.

7. “Every AI application needs LangChain.”

It does not.

Many applications need one model request and no agent loop.

8. “An agent is automatically autonomous and intelligent.”

An agent may simply be a model running inside a loop with tools and stopping conditions.

The label does not guarantee good judgment.

9. “Giving a tool to a model makes execution safe.”

It does not.

Safety requires deterministic controls such as authorization, approval, isolation, limits, and auditing.

10. “Tool-call arguments are guaranteed to be valid and authorized.”

They are not.

Tool calls are generated output and should be treated as untrusted input.

The mental model I am keeping 💡

I started with these questions:

How do tool calls actually happen?

Does the LLM really execute my function?

If providers support tool calling, why do we need agent frameworks?

My answer now is that generating an action request and operating a reliable tool-using system are different problems.

Here is the mental model I keep:

LLM

Generates text and structured action requests.

Provider adapter

Translates between application-level messages and provider-specific formats.

Agent framework

Runs the loop, manages state, validates calls, executes tools, handles failures, and returns results to the model.

Tool

Performs the real operation.

My application

Owns permissions, business rules, safety, and the user experience.

The framework does not give the model magical hands.

It creates a controlled runtime around model-generated proposals.

Once I followed the actual code, “agentic AI” stopped looking like a mysterious new type of computer.

It looked like something much more familiar:

A model proposes the next operation, while ordinary software validates, executes, records, and controls it.

That is less magical.

It is also much easier to understand, test, secure, and debug. 🛠️

In the next article, I’ll follow the same approach with MCP: no magic words—just the client, server, transport, and the actual messages moving between them.

NestJS Fundamentals Part 1: Modularity in NestJS

Amir Ehsan Ahmadzadeh — Tue, 21 Jan 2025 13:55:53 +0000

When building scalable applications with NestJS, understanding its modular architecture is the first and most critical step. Modules are at the heart of every NestJS application, organizing your code into manageable, reusable, and maintainable components.

NestJS’s modular architecture works closely with its Dependency Injection (DI) system, which enables the decoupling of application logic and improves testability and maintainability. If you’re unfamiliar with concepts like DI, IoC (Inversion of Control), or the Dependency Inversion principle, I’ve created a blog post to help you understand these foundational ideas. You can check it out here.

This guide is Part 1 of the NestJS Fundamentals series, where we’ll explore how to leverage the @Module decorator to design modular applications. Future parts of this series will cover controllers, dependency injection in practice, middleware, testing, and more. By the end of this series, you’ll have a deep understanding of NestJS and how to use it effectively.

Let’s dive into modularity in NestJS and master the inputs of the @Module decorator.

What is the Module Decorator?
Inputs of the Module Decorator
- Providers
- Controllers
- Imports
- Exports
- Global
- Scope
Practical Example: A Modular NestJS Application
FAQs About NestJS Modules

What is the Module Decorator?

The @Module decorator in NestJS is used to define the metadata of a module. A module organizes your application into smaller, reusable building blocks, each responsible for a specific piece of functionality. This modular approach enhances scalability and maintainability in applications.

For more details, visit the official NestJS documentation on modules.

Inputs of the Module Decorator

The @Module decorator accepts several inputs that define the structure and behavior of a module. These inputs include:

Providers

Providers are the backbone of NestJS’s dependency injection system. They encapsulate reusable business logic, services, or utilities that can be injected into other parts of your application.

Default Scope: Providers are module-scoped by default, meaning they are available only within the module they are defined in.

Example:

// src/services/my.service.ts
import { Injectable } from '@nestjs/common';

@Injectable()
export class MyService {
  private data = 'Hello, NestJS!';

  getData(): string {
    return this.data;
  }
}

Controllers

Controllers define routes and handle incoming HTTP requests. They are specified in the controllers array within a module.

Example:

// src/controllers/user.controller.ts
import { Controller, Get } from '@nestjs/common';

@Controller('users')
export class UserController {
  @Get()
  getAllUsers() {
    return 'List of users';
  }
}

// src/modules/user.module.ts
import { Module } from '@nestjs/common';
import { UserController } from '../controllers/user.controller';

@Module({
  controllers: [UserController],
})
export class UserModule {}

Imports

The imports array allows a module to include and use other modules. By importing a module, you gain access to its exported providers.

Example:

// src/modules/app.module.ts
import { Module } from '@nestjs/common';
import { UserModule } from './user.module';

@Module({
  imports: [UserModule], // Importing UserModule
})
export class AppModule {}

Exports

The exports array specifies which providers from the current module are available for use in other modules. Without exporting, providers remain private to the module.

Example:

// src/modules/user.module.ts
import { Module } from '@nestjs/common';
import { MyService } from '../services/my.service';

@Module({
  providers: [MyService],
  exports: [MyService], // Making MyService accessible to other modules
})
export class UserModule {}

Global

The global property makes a module automatically available across the application without needing to explicitly import it in other modules.

Example:

// src/modules/global.module.ts
import { Module } from '@nestjs/common';
import { MyService } from '../services/my.service';

@Module({
  providers: [MyService],
  exports: [MyService],
  global: true, // Marks the module as globally available
})
export class GlobalModule {}

Scope

The scope property allows you to customize the lifecycle of a provider. The available scopes are:

Singleton (default): A single instance is shared across the application.
Request: A new instance is created for each HTTP request.
Transient: A new instance is created each time it is injected.

Example:

// src/services/request-scoped.service.ts
import { Injectable, Scope } from '@nestjs/common';

@Injectable({ scope: Scope.REQUEST })
export class RequestScopedService {}

Practical Example: A Modular NestJS Application

Here’s a real-world scenario demonstrating how the module decorator inputs work together:

Step 1: Define a Shared Provider

// src/services/shared.service.ts
import { Injectable } from '@nestjs/common';

@Injectable()
export class SharedService {
  private message = 'Shared Message';

  getMessage() {
    return this.message;
  }

  setMessage(newMessage: string) {
    this.message = newMessage;
  }
}

Step 2: Create and Export a Module

// src/modules/shared.module.ts
import { Module } from '@nestjs/common';
import { SharedService } from '../services/shared.service';

@Module({
  providers: [SharedService],
  exports: [SharedService], // Export SharedService to make it accessible
})
export class SharedModule {}

Step 3: Import the Module and Use the Provider

// src/modules/app.module.ts
import { Module } from '@nestjs/common';
import { SharedModule } from './shared.module';
import { AppController } from '../controllers/app.controller';

@Module({
  imports: [SharedModule], // Importing SharedModule
  controllers: [AppController],
})
export class AppModule {}

// src/controllers/app.controller.ts
import { Controller, Get } from '@nestjs/common';
import { SharedService } from '../services/shared.service';

@Controller()
export class AppController {
  constructor(private readonly sharedService: SharedService) {}

  @Get()
  getSharedData() {
    return this.sharedService.getMessage();
  }
}

Here’s the improved FAQs About NestJS Modules section with better, practical, and engaging questions that address common challenges and curiosities about modularity in NestJS:

FAQs About NestJS Modules

1. What is the purpose of modularity in NestJS?

Modularity allows you to divide your application into feature-specific units called modules. This:

Promotes code reusability.
Enhances maintainability by isolating features.
Simplifies scaling by making it easier to manage and extend modules.

2. How do I decide what should go into a module?

Each module should encapsulate a specific feature or closely related functionalities. Examples:

UserModule for user management (authentication, profiles).
ProductModule for product operations.
SharedModule for utilities like logging or configuration.

3. What’s the difference between `providers`, `exports`, and `imports`?

Providers: Internal services or logic available within the module.
Exports: Providers made available to other modules that import the module.
Imports: A way for a module to access the exports of another module.

Example:

@Module({
  providers: [FeatureService],
  exports: [FeatureService], // Makes FeatureService reusable
})
export class FeatureModule {}

@Module({
  imports: [FeatureModule], // Accessing exports of FeatureModule
})
export class AppModule {}

4. When should I use `global: true` for a module?

Use global: true when you need application-wide accessibility for a module (e.g., ConfigModule, LoggerModule). Avoid overuse to prevent unintended dependencies.

5. How does the `scope` of providers affect their lifecycle?

Singleton (default): One shared instance across the app.
Request: A new instance for each HTTP request.
Transient: A new instance every time it’s injected.

Example:

@Injectable({ scope: Scope.REQUEST })
export class RequestScopedService {}

6. Can I import the same module into multiple other modules?

Yes! NestJS ensures that exported providers remain singletons unless explicitly scoped otherwise.

7. How do I handle circular dependencies between modules?

Use forwardRef() to resolve circular dependencies:

@Injectable()
export class AService {
  constructor(@Inject(forwardRef(() => BService)) private bService: BService) {}
}

8. How do I test a module in isolation?

Use Test.createTestingModule() to create an isolated testing environment. Override providers to use mock implementations.

Example:

const module = await Test.createTestingModule({
  imports: [UserModule],
})
  .overrideProvider(UserService)
  .useValue(mockUserService)
  .compile();

9. How do shared modules work in NestJS?

A shared module exports providers to be reused across multiple modules. Exported providers remain singletons.

Example:

@Module({
  providers: [LoggingService],
  exports: [LoggingService],
})
export class SharedModule {}

10. How should I organize modules in a large NestJS application?

Structure modules by feature or domain for scalability:

src/
├── app.module.ts
├── modules/
│   ├── auth/
│   │   ├── auth.module.ts
│   │   ├── auth.service.ts
│   │   ├── auth.controller.ts
│   ├── users/
│   │   ├── users.module.ts
│   │   ├── users.service.ts
│   │   ├── users.controller.ts
│   ├── shared/
│       ├── shared.module.ts
│       ├── logging.service.ts

The @Module decorator is the foundation of NestJS’s modular architecture. By understanding and leveraging its inputs—providers, controllers, imports, exports, global, and scope—you can create scalable, maintainable, and reusable application structures.

If this guide helped you, don’t forget to share it or leave a comment. Let’s discuss your experience with NestJS modules below!

Breaking Down Dependency Inversion, IoC, and DI

Amir Ehsan Ahmadzadeh — Sun, 19 Jan 2025 15:18:59 +0000

I was, knee-deep in the dependency injection system of NestJS, trying to figure out how it all worked. You know that feeling when you’re exploring something and suddenly realize there are concepts you kind of know, but not really? That’s where I was with Dependency Inversion, Inversion of Control, and Dependency Injection.

These three ideas seem so similar at first. But the deeper I dug, the more it became clear: they’re connected, but they solve different problems. I figured I’d write this as a refresher for myself—and for anyone else who’s been staring at these terms and wondering how they all fit together.

1. Dependency Inversion Principle (DIP)

Definition:

High-level modules should not depend on low-level modules. Both should depend on abstractions. Abstractions should not depend on details. Details should depend on abstractions.

What Does This Mean?

In software, a high-level module contains core business logic, while low-level modules handle specific implementation details (e.g., file systems, databases, or APIs). Without DIP, high-level modules directly depend on low-level modules, creating tight coupling that:

Reduces flexibility.
Complicates testing and maintenance.
Increases effort to replace or extend low-level details.

DIP flips this relationship. Instead of the high-level module controlling low-level implementation, both depend on a shared abstraction (like an interface or abstract class).

Without DIP

Python Example

class EmailService:
    def send_email(self, message):
        print(f"Sending email: {message}")

class Notification:
    def __init__(self):
        self.email_service = EmailService()

    def notify(self, message):
        self.email_service.send_email(message)

TypeScript Example

class EmailService {
    sendEmail(message: string): void {
        console.log(`Sending email: ${message}`);
    }
}

class Notification {
    private emailService: EmailService;

    constructor() {
        this.emailService = new EmailService();
    }

    notify(message: string): void {
        this.emailService.sendEmail(message);
    }
}

Problems:

Tight coupling: Notification depends on EmailService.
Hard to extend: Switching to an SMSService or a PushNotificationService requires modifying Notification.

With DIP

Python Example

from abc import ABC, abstractmethod

class MessageService(ABC):
    @abstractmethod
    def send_message(self, message):
        pass

class EmailService(MessageService):
    def send_message(self, message):
        print(f"Sending email: {message}")

class Notification:
    def __init__(self, message_service: MessageService):
        self.message_service = message_service

    def notify(self, message):
        self.message_service.send_message(message)

# Usage
email_service = EmailService()
notification = Notification(email_service)
notification.notify("Hello, Dependency Inversion!")

TypeScript Example

interface MessageService {
    sendMessage(message: string): void;
}

class EmailService implements MessageService {
    sendMessage(message: string): void {
        console.log(`Sending email: ${message}`);
    }
}

class Notification {
    private messageService: MessageService;

    constructor(messageService: MessageService) {
        this.messageService = messageService;
    }

    notify(message: string): void {
        this.messageService.sendMessage(message);
    }
}

// Usage
const emailService = new EmailService();
const notification = new Notification(emailService);
notification.notify("Hello, Dependency Inversion!");

Benefits of DIP

Flexibility: Swap implementations without modifying high-level modules.
Testability: Replace real dependencies with mock versions for testing.
Maintainability: Changes in low-level modules don’t affect high-level modules.

2. Inversion of Control (IoC)

IoC is a design principle where the control of dependencies is transferred to an external system or framework, rather than managed within the class itself.

In traditional programming, a class creates and manages its dependencies. IoC flips this control—an external entity (e.g., a framework or container) manages dependencies and injects them where needed.

Without IoC

In a setup without IoC, the class itself is responsible for creating and managing its dependencies, leading to tight coupling. Let’s see examples in Python and TypeScript:

Python Example: Without IoC

class SMSService:
    def send_message(self, message):
        print(f"Sending SMS: {message}")

class Notification:
    def __init__(self):
        # Dependency is created inside the class
        self.sms_service = SMSService()

    def notify(self, message):
        self.sms_service.send_message(message)

# Usage
notification = Notification()
notification.notify("Hello, tightly coupled dependencies!")

TypeScript Example: Without IoC

class SMSService {
    sendMessage(message: string): void {
        console.log(`Sending SMS: ${message}`);
    }
}

class Notification {
    private smsService: SMSService;

    constructor() {
        // Dependency is created inside the class
        this.smsService = new SMSService();
    }

    notify(message: string): void {
        this.smsService.sendMessage(message);
    }
}

// Usage
const notification = new Notification();
notification.notify("Hello, tightly coupled dependencies!");

Problems Without IoC:

Tight coupling: The Notification class directly creates and depends on the SMSService class.
Low flexibility: Switching to a different implementation (e.g., EmailService) requires modifying the Notification class.
Difficult testing: Mocking dependencies for unit tests is challenging because the dependencies are hardcoded.

With IoC

In the With IoC examples, we shift the responsibility of managing dependencies to an external system or a framework, achieving loose coupling and enhancing testability.

Python Example: With IoC

class SMSService:
    def send_message(self, message):
        print(f"Sending SMS: {message}")

class Notification:
    def __init__(self, message_service):
        # Dependency is injected externally
        self.message_service = message_service

    def notify(self, message):
        self.message_service.send_message(message)

# IoC: Dependency is controlled externally
sms_service = SMSService()
notification = Notification(sms_service)
notification.notify("Hello, Inversion of Control!")

TypeScript Example: With IoC

class SMSService {
    sendMessage(message: string): void {
        console.log(`Sending SMS: ${message}`);
    }
}

class Notification {
    private messageService: SMSService;

    constructor(messageService: SMSService) {
        // Dependency is injected externally
        this.messageService = messageService;
    }

    notify(message: string): void {
        this.messageService.sendMessage(message);
    }
}

// IoC: Dependency is controlled externally
const smsService = new SMSService();
const notification = new Notification(smsService);
notification.notify("Hello, Inversion of Control!");

Benefits of IoC

Loose coupling: Classes don’t create their dependencies, making them less dependent on specific implementations.
Easy to switch implementations: Replace a SMSService with an EmailService without modifying the core class.
Improved testability: Inject mock or fake dependencies during testing.

3. Dependency Injection (DI)

DI is a technique where an object receives its dependencies from an external source rather than creating them itself.

DI is a practical implementation of IoC. It allows developers to "inject" dependencies into classes in various ways:

Constructor Injection: Dependencies are passed via the constructor.
Setter Injection: Dependencies are set via public methods.
Interface Injection: Dependencies are provided through an interface.

Python Example: DI Framework

Using the injector library:

from injector import Injector, inject

class EmailService:
    def send_message(self, message):
        print(f"Email sent: {message}")

class Notification:
    @inject
    def __init__(self, email_service: EmailService):
        self.email_service = email_service

    def notify(self, message):
        self.email_service.send_message(message)

# DI Container
injector = Injector()
notification = injector.get(Notification)
notification.notify("This is Dependency Injection in Python!")

Note: Be aware that the injector relies on Python type annotations; So it will distinguish dependencies based on type hints.

TypeScript Example: DI Framework

Using tsyringe:

import "reflect-metadata";
import { injectable, inject, container } from "tsyringe";

@injectable()
class EmailService {
    sendMessage(message: string): void {
        console.log(`Email sent: ${message}`);
    }
}

@injectable()
class Notification {
    constructor(@inject(EmailService) private emailService: EmailService) {}

    notify(message: string): void {
        this.emailService.sendMessage(message);
    }
}

// DI Container
const notification = container.resolve(Notification);
notification.notify("This is Dependency Injection in TypeScript!");

Benefits of DI

Simplifies Testing: Easily replace dependencies with mock objects.
Improves Scalability: Add new implementations without modifying existing code.
Enhances Maintainability: Reduces the impact of changes in one part of the system.

Why 'this' in JavaScript Differs from Other OOP Languages

Amir Ehsan Ahmadzadeh — Fri, 17 Jan 2025 06:17:12 +0000

One of the most confusing aspects of JavaScript for me was understanding how the this keyword works.

The this keyword in JavaScript behaves differently from OOP languages like C#, Java, or Python (where the equivalent is self) because of how this is determined. In those languages, this consistently refers to the current instance of the class or object. In JavaScript, however, this is more dynamic and its value depends on how and where a function is invoked.

With that in mind, I decided to create a summary of the different scenarios where the behavior of this can vary. Here's the breakdown:

1. Global Context

Non-Strict Mode:

this refers to the global object (window in browsers, global in Node.js).

console.log(this); // `window` or `global`

Strict Mode:

this is undefined.

"use strict";
console.log(this); // undefined

2. Inside a Function

Regular Function:

In non-strict mode, this refers to the global object.
In strict mode, this is undefined.

function myFunction() {
    console.log(this);
}
myFunction(); // `window` (non-strict), undefined (strict)

3. As a Method of an Object

When a function is called as a method of an object, this refers to the object that owns the method.

const obj = {
    name: "JavaScript",
    greet() {
        console.log(this.name); // `this` refers to `obj`
    }
};
obj.greet(); // Output: "JavaScript"

4. Arrow Functions

Arrow functions do not have their own this. Instead, they inherit this from their lexical scope (the surrounding context).

const obj = {
    name: "JavaScript",
    arrowFunc: () => {
        console.log(this.name); // `this` is inherited from the global scope
    }
};
obj.arrowFunc(); // undefined (in browsers, `this` is `window`)

function outer() {
    const arrow = () => console.log(this);
    arrow(); // Inherits `this` from `outer`'s context
}
outer();

5. In a Constructor

In a constructor function or class, this refers to the instance being created.

class Person {
    constructor(name) {
        this.name = name;
    }
    greet() {
        console.log(`Hello, ${this.name}`);
    }
}

const person = new Person("Alice");
person.greet(); // Output: Hello, Alice

6. Explicit Binding (`call`, `apply`, `bind`)

In JavaScript, functions are objects and have methods like call, apply, and bind, which let you explicitly set the value of this.

`call` and `apply`:

Invoke the function with a specified this value.
Difference: call accepts arguments as a comma-separated list; apply takes an array.

function greet(greeting) {
    console.log(`${greeting}, ${this.name}`);
}

const user = { name: "Alice" };
greet.call(user, "Hello"); // Output: Hello, Alice
greet.apply(user, ["Hi"]); // Output: Hi, Alice

`bind`:

Returns a new function with this permanently bound to the specified value.

const boundGreet = greet.bind(user);
boundGreet("Hello"); // Output: Hello, Alice

7. In an Event Listener

Regular Function:

this refers to the element that triggered the event.

const button = document.querySelector("button");
button.addEventListener("click", function () {
    console.log(this); // The button element
});

Arrow Function:

this inherits from the surrounding scope, not the element.

button.addEventListener("click", () => {
    console.log(this); // `this` depends on where the arrow function is defined
});

8. Inside `setTimeout` or `setInterval`

Regular Function:

this defaults to the global object (window).

setTimeout(function () {
    console.log(this); // `window` in browsers
}, 1000);

Arrow Function:

Inherits this from its lexical scope.

setTimeout(() => {
    console.log(this); // Inherits `this` from the surrounding context
}, 1000);

9. In Classes

Inside a class method, this refers to the class instance.

class MyClass {
    constructor(name) {
        this.name = name;
    }

    sayName() {
        console.log(this.name);
    }
}

const obj = new MyClass("JavaScript");
obj.sayName(); // Output: JavaScript

10. Losing Context (Method Extraction)

When a method is assigned to a variable or passed as a callback, this can lose its binding.

const obj = {
    name: "JavaScript",
    greet() {
        console.log(this.name);
    }
};

const greet = obj.greet;
greet(); // undefined (`this` is no longer bound to `obj`)

Solutions:

Use bind:

   const boundGreet = obj.greet.bind(obj);
   boundGreet(); // Output: JavaScript

Use an Arrow Function:

   const obj = {
       name: "JavaScript",
       greet: () => console.log(this.name) // `this` is inherited lexically
   };
   obj.greet(); // Output depends on outer scope

11. In `new` Keyword Usage

When you use new with a function or class, this refers to the newly created object.

function MyConstructor() {
    this.name = "New Object";
}
const instance = new MyConstructor();
console.log(instance.name); // Output: New Object

Summary

Context	`this` Refers To
Global (non-strict)	Global object (`window`/`global`).
Global (strict)	`undefined`.
Object Method	The object that owns the method.
Arrow Function	Inherits `this` from the enclosing context.
Constructor/Class	The instance being created.
`call`, `apply`, `bind`	Explicitly defined value.
Event Listener	The element that triggered the event.
`setTimeout/Interval`	Global object or inherited context (arrow).
`new` Keyword	The newly created object.

Why Use Getters and Setters?!

Amir Ehsan Ahmadzadeh — Wed, 18 Dec 2024 22:39:21 +0000

If you’ve worked with Python or JavaScript or any other language that supports OOP, you’ve likely come across getters and setters—special methods used to access or modify an object’s attributes. But if we can directly change attributes like this:

class Person:
    def __init__(self, name):
        self.name = name  # Directly accessible attribute

# Usage
p = Person("Alice")
print(p.name)  # Access directly
p.name = "Bob"  # Modify directly
print(p.name)

Why would we ever need getters and setters? Isn’t this redundant?

It’s a valid question. In this article, we’ll break down why getters and setters are useful, when you should use them, and when you can skip them.

What Are Getters and Setters?

In object-oriented programming, getters and setters are methods used to access and modify an object's attributes. Here's a simple example in Python:

class Person:
    def __init__(self, name):
        self._name = name  # Protected attribute

    @property
    def name(self):
        return self._name  # Getter

    @name.setter
    def name(self, value):
        if not value:
            raise ValueError("Name cannot be empty")  # Validation
        self._name = value  # Setter

In JavaScript, it looks like this:

class Person {
    constructor(name) {
        this._name = name; // Protected attribute
    }

    get name() {
        return this._name; // Getter
    }

    set name(value) {
        if (!value) {
            throw new Error("Name cannot be empty"); // Validation
        }
        this._name = value; // Setter
    }
}

By wrapping attributes in methods, you gain control over how they’re accessed or modified.

Why Not Access Attributes Directly?

The argument for direct access is simplicity. Why add extra layers when you can just do this?

class Person:
    def __init__(self, name):
        self.name = name  # Use a regular attribute


# Try to changing it directly
p = Person("Alice")
print(p.name)
p.name = "Bob"
print(p.name)

# Output: 
# Alice
# Bob

This works, but it leaves your attributes vulnerable to unintended or invalid changes. Let’s explore why getters and setters matter:

Validation and Control

Direct access gives you no way to enforce rules for the attribute’s value. For instance, consider a Person class where the name attribute must never be empty. With a setter, you can validate the value:
Python:

@name.setter
def name(self, value):
    if not value:
        raise ValueError("Name cannot be empty")

JavaScript:

set name(value) {
    if (!value) {
        throw new Error("Name cannot be empty");
    }
    this._name = value;
}

Without this, invalid values can sneak in:

p.name = ""  # No error without a setter!

Read-Only Properties

Some attributes should only be readable, not writable. Getters allow you to expose data without allowing modifications.

Example: Calculating age from birth_year:
Python:

from datetime import date

class Person:
    def __init__(self, name, birth_year):
        self.name = name
        self.birth_year = birth_year

    @property
    def age(self):
        return date.today().year - self.birth_year  # Read-only attribute

JavaScript:

class Person {
    constructor(name, birthYear) {
        this.name = name;
        this.birthYear = birthYear;
    }

    get age() {
        return new Date().getFullYear() - this.birthYear; // Read-only attribute
    }
}

Users can read age but not modify it directly:

p.age = 30  # Throws an error

Future-Proofing

Exposing an attribute directly ties your internal implementation to your class's public interface. If you later decide to add logic (e.g., validating or formatting values), you’ll need to refactor all code that directly accesses the attribute.

Using getters and setters from the start makes future changes seamless.

Example: Changing how name is stored:

Python:

@name.setter
def name(self, value):
    self._name = value.capitalize()  # Always capitalize names

JavaScript:

set name(value) {
    this._name = value.toUpperCase(); // Always store in uppercase
}

With direct access, these changes would break existing code.

Lazy Computation

Python:

class Rectangle:
    def __init__(self, width, height):
        self.width = width
        self.height = height
        self._area = None

    @property
    def area(self):
        if self._area is None:
            self._area = self.width * self.height
        return self._area

JavaScript:

get area() {
    if (!this._area) {
        this._area = this.width * this.height;
    }
    return this._area;
}

Benefits of Using Getters and Setters

1. Better Control
Getters and setters give you fine-grained control over how attributes are accessed and modified. They allow you to enforce rules, validate input, or transform data as needed, ensuring consistency and reliability.

2. Encapsulation
They support encapsulation by hiding the internal implementation of attributes and exposing only what is necessary. This helps maintain a clean, modular, and maintainable class design.

3. Reusability
By implementing logic directly within setters, you eliminate the need for external validation or transformation code. This centralization ensures that users of the class don’t need to write additional code to handle common operations, such as validation or formatting. As a result, your class becomes easier to use and more consistent across different parts of your project.

4. Security
Restricting direct access to attributes provides an added layer of security. Sensitive or critical data is protected from accidental or unauthorized modifications, enhancing the robustness of your code.

5. Future-Proofing
Getters and setters decouple the attribute’s external access from its internal implementation. This makes it easier to adapt to future changes, such as adding new features, validations, or logic, without breaking existing code.

What Do You Think?

Have you used getters and setters in your projects? Are they overkill, or do they help you write better code? Share your thoughts in the comments!

RAG Explained: Tackling the Big Problems in AI

Amir Ehsan Ahmadzadeh — Sat, 14 Dec 2024 18:22:02 +0000

This is the post about understanding concept of RAG, but before diving into the core concept of Retrieval-Augmented Generation (RAG), I want to share a little bit about myself and the approach I take when learning something new. I’m new here and excited to be part of this community, so here’s a quick intro to my learning philosophy.

My Learning Philosophy

When it comes to exploring new technologies or concepts, I try to ensure they are worth my time by focusing on approaches or tools that are widely recognized as good practices. Time is valuable, so learning something impactful is always the goal.

I like to begin with a top-down approach by asking myself two key questions:

What problem does this aim to solve?
How were these problems addressed before this tool/technology existed?

These questions help me understand not just the “what” but also the “why” of a technology. With that in mind, let’s explore RAG together, focusing on its core purpose and what makes it significant.

What is RAG, and Why Does It Matter?

At its core, Retrieval-Augmented Generation (RAG) bridges the gap between generative language models (like GPT) and retrieval systems (such as search engines or databases). While generative models are amazing at creating human-like text, they have limitations, especially when it comes to:

Providing accurate and up-to-date information.
Retaining context about niche or domain-specific topics.
Operating efficiently without consuming massive computational resources.

These limitations—and how RAG addresses them—are discussed in more detail below. In essence, RAG solves these challenges by combining the creativity of generative AI with the precision and factual accuracy of retrieval systems.

The Problem RAG Solves

While large language models (LLMs) like GPT-3 or T5 are powerful, they have inherent limitations:

1. Outdated Knowledge

LLMs are trained on a static dataset. Once trained, their knowledge is fixed and may not include the latest information or domain-specific updates.

Example:

A user asks: "What are the latest COVID-19 travel restrictions?"

The LLM might not have up-to-date information because it relies on the training data available at the time of training.

2. Lack of Specific Domain Knowledge

LLMs may not perform well in niche domains or contexts requiring detailed, specialized information.

Example:

A legal question: "What does clause 4.3 in the GDPR specify about data retention?"

The LLM may generate a response that is vague or inaccurate due to limited understanding of the specific legal context.

3. Hallucinations

LLMs can "hallucinate" facts, producing confident-sounding but incorrect or fabricated answers because they predict the most likely word sequences, rather than relying on verified sources.

Example:

A user asks: "Who discovered Pluto?"

The model may incorrectly generate a random name, even though the correct answer is Clyde Tombaugh.

4. Inefficiency in Large Knowledge Bases

Incorporating large datasets directly into the model during training is impractical.

Example:

Storing and training on an organization's entire document library can be computationally infeasible.

Embedding all possible knowledge directly into the model leads to inefficiency.

How RAG Solves These Problems

RAG overcomes these limitations by integrating retrieval systems with generative models. Here's how:

1. Dynamic and Up-to-Date Information

RAG systems retrieve relevant data from external sources, such as a document store, database, or API, at the time of querying. This allows the system to include the latest information without retraining the model.

Example:

Query: "What are the latest COVID-19 travel restrictions?"

Retrieval: Fetch the most recent government announcements or website data.

Response: Generate an accurate, up-to-date answer based on retrieved information.

2. Domain-Specific Context

RAG systems can leverage a curated knowledge base tailored to specific industries, ensuring that responses are grounded in the desired context.

Example:

Query: "What are the best practices for microservice architecture?"

Retrieval: Fetch relevant excerpts from technical documentation or whitepapers on microservices.

Response: Generate a summary or actionable recommendations using the retrieved data.

3. Grounded Responses (Reducing Hallucinations)

By using retrieval as a foundation, RAG reduces hallucination by grounding the response generation in factual, retrieved content. The model no longer relies solely on its internal knowledge but can explicitly reference external sources.

Example:

Query: "Who discovered Pluto?"

Retrieval: Access an astronomy textbook or article specifying Clyde Tombaugh.

Response: Accurately respond based on the retrieved material.

4. Efficiency and Scalability

Instead of embedding all knowledge into the model, RAG retrieves only relevant pieces of information as needed. This reduces computational load and allows the system to scale with large datasets.

Example:

A company stores thousands of internal documents in a vector database.

Instead of fine-tuning the LLM on all documents, the RAG pipeline retrieves only the 5-10 most relevant documents for the query, ensuring efficient usage of resources.

Illustrative Example of RAG in Action

Query: "What are the benefits of solar panels?"

Retrieval: The retriever fetches excerpts from relevant documents:
- "Solar panels reduce electricity bills by converting sunlight into energy."
- "They help in reducing carbon footprints."
Generation: The generative model processes the query and retrieved data to create an informed response:
- "Solar panels offer several benefits, including reduced electricity bills and a smaller carbon footprint, by converting sunlight into energy."

Applications of RAG

Customer Support: Quickly retrieve and summarize relevant support documents to address customer queries.
Search-Driven Content Generation: Enhance search engines with conversational abilities grounded in real data.
Legal and Financial Assistance: Provide detailed, grounded answers based on legal documents or financial reports.
Medical Advice: Answer medical queries based on the latest research or medical guidelines.
Research Assistance: Summarize and contextualize scientific articles for researchers.

Why RAG is Transformative

Adaptability: Can be updated in real-time without retraining.
Customizability: Tailored to specific domains or datasets.
Efficiency: Reduces computational cost compared to embedding all data in the model.

In the next part of this post, I’ll delve deeper into how RAG works, its components, and share insights from my own exploration. Feel free to share your thoughts—how do you approach learning new technologies? Let’s start a conversation! 😊

The History and Purpose of Node.js: Revolutionizing Server-Side Programming

Amir Ehsan Ahmadzadeh — Thu, 05 Dec 2024 09:32:02 +0000

The History and Purpose of Node.js: Revolutionizing Server-Side Programming

From Simple Web Pages to Complex Systems

The web of the early 1990s was a simpler place. Static HTML pages dominated the internet, and user interactions were limited to clicking hyperlinks. However, as the web matured, user expectations changed. Websites evolved into full-fledged applications capable of handling complex tasks like online shopping, social networking, and real-time communication.

This shift brought unprecedented challenges for web servers and developers alike:

Increased Traffic: Modern applications needed to handle thousands, if not millions, of simultaneous users.
Dynamic Content: Static pages were no longer enough. Servers were expected to generate dynamic responses, pulling data from databases and external APIs in real-time.
Real-time Interaction: The rise of real-time applications like chat systems, collaborative tools, and live gaming demanded low latency and high concurrency.

The Problem with Traditional Server Architectures

Traditional server architectures struggled to keep up with these demands. For example:

Blocking I/O Operations: In conventional server models, operations like reading a file or querying a database would block the server thread, leaving it idle until the task was complete. This inefficiency reduced the server’s ability to handle multiple requests.
Thread-based Concurrency: To address blocking issues, servers like Apache relied on spawning threads for each incoming request. However, threads come with significant memory and CPU overhead, limiting the scalability of this approach.

The limitations of these architectures became increasingly evident as developers tried to build more interactive, real-time systems. The need for a new paradigm—one that could handle thousands of simultaneous connections without being bogged down by blocking operations—was clear.

Node.js: A Game-Changing Solution

In 2009, a software engineer named Ryan Dahl introduced Node.js, a framework that promised to revolutionize server-side programming. By combining an event-driven, non-blocking architecture with the power of JavaScript, Node.js became the tool that many modern web applications desperately needed.

But why did Dahl choose JavaScript, a language that had primarily been used for client-side scripting? To understand this decision and why Node.js was groundbreaking, we need to explore its design philosophy and the problems it set out to solve.

Why JavaScript? The Choice That Changed the Game

Ryan Dahl’s decision to use JavaScript as the foundation for Node.js was both bold and forward-thinking. Here’s why:

JavaScript Everywhere: By 2009, JavaScript was already the dominant language for client-side programming. Using it on the server allowed developers to write both front-end and back-end code in the same language, reducing complexity and enabling easier collaboration.
Event-Driven Nature: JavaScript, through its use in browsers, was already designed to handle asynchronous, event-driven programming. This made it a natural fit for a non-blocking server environment.
V8 Engine: Google’s V8 engine, which powered JavaScript in the Chrome browser, provided a fast and efficient runtime that could handle heavy workloads. Node.js leveraged this engine to deliver exceptional performance.

Node.js and the Event-Driven Revolution

Node.js wasn’t just a framework; it was a rethinking of how web servers should work. Instead of blocking operations and using threads to manage concurrency, Node.js adopted an event loop—a single-threaded mechanism that could handle multiple tasks asynchronously. This allowed it to serve thousands of concurrent connections without the overhead of traditional thread-based systems.

Let’s dive deeper into the core principles of Node.js to see how it handles modern web development’s toughest challenges.

Introduction: The Problem with Traditional Web Servers

In the early 2000s, web development was rapidly evolving. Applications were becoming more dynamic, interactive, and resource-intensive. However, traditional web servers like Apache faced challenges in handling the growing demands of modern applications:

Blocking I/O Operations: In most traditional server models, an incoming request would block the server’s thread while waiting for an I/O operation, such as reading from a database or accessing a file system, to complete. This inefficiency made it difficult to scale applications that required frequent or simultaneous I/O operations.
Thread-based Concurrency: Traditional server models often relied on thread-based concurrency. While threads enable servers to handle multiple requests concurrently, they come with significant overhead in memory and CPU usage, limiting scalability.
The Rising Demand for Real-time Applications: With the growth of real-time applications like chat systems, online gaming, and live collaboration tools, the need for a more efficient, non-blocking architecture became apparent.

Enter Node.js: A Solution Born from Necessity

In 2009, Ryan Dahl, a software engineer, introduced Node.js to address these limitations. Dahl sought to build a framework capable of handling a large number of simultaneous connections efficiently, without the overhead associated with threads.

Why JavaScript?

One of Dahl's most pivotal decisions was to use JavaScript as the programming language for Node.js. Here’s why:

Ubiquity of JavaScript: By 2009, JavaScript had already become the lingua franca of web development, thanks to its dominance on the client side. Using JavaScript for server-side programming meant developers could work on both ends of an application using a single language.
Event-driven Nature: JavaScript’s event-driven programming paradigm, popularized by browsers, was a perfect fit for asynchronous, non-blocking server operations.
V8 Engine: Google’s V8 engine, developed for Chrome, provided a high-performance runtime for JavaScript. Dahl leveraged V8’s speed and efficiency to build a fast, lightweight server framework.

Alternatives Considered

Before Node.js, developers relied on various technologies for building scalable web servers:

Ruby on Rails and PHP: These frameworks used synchronous, blocking I/O models and thread-based concurrency.
Python with Twisted: While Twisted provided asynchronous programming capabilities, it lacked the simplicity and performance optimization that Node.js offered.
Java (e.g., Netty): Java frameworks supported non-blocking I/O, but they came with a steep learning curve and more complexity compared to Node.js.

Core Concepts of Node.js

1. I/O-Bound vs. CPU-Bound Tasks

To understand Node.js’s significance, it’s essential to differentiate between:

I/O-bound tasks: These involve waiting for data input or output, such as reading a file, querying a database, or fetching a remote API response. These tasks are often the bottleneck in traditional server architectures.
CPU-bound tasks: These involve intensive computations, such as image processing, data encryption, or machine learning model inference.

Node.js excels at handling I/O-bound tasks due to its non-blocking, event-driven architecture. However, it is less suited for CPU-bound tasks, which can monopolize the single-threaded event loop.

2. The Asynchronous Approach

The cornerstone of Node.js is its asynchronous programming model, which allows the server to handle multiple operations concurrently without waiting for any single task to complete. This is achieved through:

Callbacks: Functions that are executed once an operation completes.
Promises and async/await: Modern abstractions for managing asynchronous operations, introduced in later versions of JavaScript.

3. Event Loop and Non-Blocking I/O

The event loop is the heart of Node.js. It allows the server to offload time-consuming operations (like file access or database queries) to the system’s underlying I/O mechanisms while continuing to process other requests. Once the operation completes, the event loop picks up the result and executes the appropriate callback.

The Rise of Node.js: Use Cases and Ecosystem

Ideal Use Cases

Node.js has become a staple for applications that require:

Real-time interaction (e.g., chat applications, online multiplayer games).
High concurrency with minimal resource usage (e.g., APIs, microservices).
Streaming capabilities (e.g., media streaming platforms).

NPM: The Node.js Package Manager

Node.js's success is closely tied to NPM, its package ecosystem. With thousands of modules readily available, developers can easily add functionality like authentication, data validation, or web frameworks (e.g., Express.js) to their projects.

Node.js emerged as a response to the limitations of traditional server models, bringing an event-driven, asynchronous approach to server-side programming. By leveraging JavaScript and Google’s V8 engine, Ryan Dahl created a framework that bridged the gap between client and server, enabling a new generation of scalable, real-time web applications.

Today, Node.js remains a cornerstone of modern web development, empowering developers to build efficient, high-performing applications that meet the demands of an ever-connected world.

DEV Community: Amir Ehsan Ahmadzadeh

How Actually Your Functions Get Called By LLMs?

How do tool calls actually happen?

First: how I verified the claims in this article 🔬

Source-review timestamp

Inspected source snapshots

The answer in one paragraph 💡

The four actors involved 🧩

1. The LLM: generating tokens and action requests 🧠

2. The provider API: giving tool requests a structure

One important exception: provider-hosted tools

Prompt-based tool use versus native tool calling

3. The application or framework: running the loop 🔁

4. The tool: ordinary executable software 🛠️

Following one tool call from beginning to end

Step 1: The application sends the model a tool definition

Step 2: The model generates a tool request

Step 3: The runtime validates the request

Step 4: Ordinary software invokes the function

Step 5: The runtime creates a tool-result message

Step 6: The model is called again

Building the loop without a framework

What each stage does

call_model(...)

response.tool_calls

tool_registry[call.name]

validate_arguments(...)

authorize_tool_call(...)

execute_tool(...)

The step limit

Proof from PydanticAI’s implementation 🔬

PydanticAI step 1: the model response enters the graph

PydanticAI step 2: validation and execution are separate operations

PydanticAI step 3: the tool manager invokes executable code

PydanticAI step 4: the result becomes a model message

PydanticAI’s execution path

Proof from LangChain and LangGraph 🔬

LangChain step 1: create_agent constructs a loop

LangChain step 2: the model returns tool calls

LangGraph step 3: ToolNode invokes the registered tool

LangGraph step 4: the result becomes a ToolMessage

LangChain and LangGraph’s execution path

A note about old LangChain tutorials

What these source tours prove

Why not keep a handwritten loop?

PydanticAI versus LangChain/LangGraph

Consider PydanticAI when

Consider LangChain and LangGraph when

Consider neither when

What does the model decide?

What does the runtime decide? 🔐

Are agent frameworks just prompt templates?

Making the invisible loop visible 🔍

Where MCP fits

Ten misconceptions worth correcting

1. “The LLM executes my function.”

2. “Native tool calling gives the model operating-system access.”

3. “The framework decides everything.”

4. “The model decides everything.”

5. “Agent frameworks are just prompt templates.”

6. “MCP and tool calling are the same thing.”

7. “Every AI application needs LangChain.”

8. “An agent is automatically autonomous and intelligent.”

9. “Giving a tool to a model makes execution safe.”

10. “Tool-call arguments are guaranteed to be valid and authorized.”

The mental model I am keeping 💡

LLM

Provider adapter

Agent framework

Tool

My application

NestJS Fundamentals Part 1: Modularity in NestJS

Table of Contents

What is the Module Decorator?

Inputs of the Module Decorator

Providers

Controllers

Imports

Exports

Global

`call_model(...)`

`response.tool_calls`

`tool_registry[call.name]`

`validate_arguments(...)`

`authorize_tool_call(...)`

`execute_tool(...)`

LangChain step 1: `create_agent` constructs a loop

LangGraph step 3: `ToolNode` invokes the registered tool

LangGraph step 4: the result becomes a `ToolMessage`

3. What’s the difference between `providers`, `exports`, and `imports`?

4. When should I use `global: true` for a module?

5. How does the `scope` of providers affect their lifecycle?

6. Explicit Binding (`call`, `apply`, `bind`)

`call` and `apply`:

`bind`:

8. Inside `setTimeout` or `setInterval`

11. In `new` Keyword Usage