pip install openai python-dotenv

OPENAI_API_KEY="gsk_YOUR_GROQ_API_KEY"
OPENAI_MODEL="openai/gpt-oss-120b"
OPENAI_BASE_URL="https://api.groq.com/openai/v1"

import os
from dotenv import load_dotenv
from openai import OpenAI

# 1. Load your API key from the .env file
load_dotenv()
client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY")
    base_url=os.getenv("OPENAI_BASE_URL") 
)

# 2. Make a single chat completion request
response = client.chat.completions.create(
    model=os.getenv("OPENAI_MODEL),
    messages=[
        {
            "role": "system",
            "content": "You are a helpful assistant that explains things simply.",
        },
        {
            "role": "user",
            "content": "What is an AI agent in 3 sentences?",
        },
    ],
    temperature=0.7,
    max_tokens=256,
)

# 3. Print the result
message = response.choices[0].message
print(f"Role   : {message.role}")
print(f"Content: {message.content}")

# 4. Inspect usage (tokens consumed)
usage = response.usage
print(f"\n--- Token Usage ---")
print(f"Prompt tokens     : {usage.prompt_tokens}")
print(f"Completion tokens : {usage.completion_tokens}")
print(f"Total tokens      : {usage.total_tokens}")

python main.py

Role   : assistant
Content: An AI agent is a software system that can perceive its environment,
make decisions, and take actions to achieve specific goals. Unlike simple
programs, agents can adapt their behavior based on new information...

--- Token Usage ---
Prompt tokens     : 32
Completion tokens : 68
Total tokens      : 100

messages=[
    {"role": "system", "content": "You are a helpful assistant..."},
    {"role": "user", "content": "What is an AI agent?"},
]

response.choices[0].message

temperature=0.7

max_tokens=256

Your Code                    OpenAI API
─────────                    ──────────
messages list ──────────────→ Process messages
                              Generate response
response object ←───────────  Return completion

messages = [
    {"role": "system", "content": "You are a friendly assistant."},
]

# User says something → append it
messages.append({"role": "user", "content": "Hi there"})

# Model responds → append that too
messages.append({"role": "assistant", "content": "Hello! How can I help?"})

# Next turn: send the ENTIRE list again
# The model sees the full conversation and can respond in context

import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY")
    base_url=os.getenv("OPENAI_BASE_URL") 
)

SYSTEM_PROMPT = (
    "You are a friendly and knowledgeable coding assistant. "
    "You help developers learn about AI agents. "
    "Keep answers concise but thorough."
)

def run_chatbot():
    """Main chatbot loop with streaming."""

    # The conversation history — this is the KEY concept.
    messages = [
        {"role": "system", "content": SYSTEM_PROMPT},
    ]

    print("=" * 60)
    print("  AI Chatbot  (type 'exit' to quit)")
    print("=" * 60)

    while True:
        try:
            user_input = input("\nYou: ").strip()
        except (EOFError, KeyboardInterrupt):
            print("\nGoodbye!")
            break

        if not user_input:
            continue
        if user_input.lower() in ("exit", "quit"):
            print("Goodbye!")
            break

        # Append what the user said
        messages.append({"role": "user", "content": user_input})

        # Stream the response
        print("\nAssistant: ", end="", flush=True)

        stream = client.chat.completions.create(
            model=os.getenv("OPENAI_MODEL),
            messages=messages,
            temperature=0.7,
            stream=True,
        )

        # Collect the full response while printing tokens as they arrive
        assistant_response = ""
        for chunk in stream:
            delta = chunk.choices[0].delta
            if delta.content:
                token = delta.content
                print(token, end="", flush=True)
                assistant_response += token

        print()  # Newline after streaming finishes

        # Append the assistant response to history
        messages.append({"role": "assistant", "content": assistant_response})


if __name__ == "__main__":
    run_chatbot()

stream = client.chat.completions.create(
    model=os.getenv("OPENAI_MODEL),
    messages=messages,
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)

messages = [
    {"role": "system", "content": "You are a coding assistant."},
    {"role": "user", "content": "What is Python?"},
]
# → Model responds: "Python is a programming language..."
# → Append assistant response to messages

messages = [
    {"role": "system", "content": "You are a coding assistant."},
    {"role": "user", "content": "What is Python?"},
    {"role": "assistant", "content": "Python is a programming language..."},
    {"role": "user", "content": "What makes it good for AI?"},
]
# → Model sees the FULL history and responds in context

def get_weather(city: str) -> dict:
    """Simulate a weather lookup."""
    fake_weather = {
        "new york": {"temp": "22C", "condition": "Sunny"},
        "london":   {"temp": "15C", "condition": "Cloudy"},
        "tokyo":    {"temp": "28C", "condition": "Humid"},
    }
    data = fake_weather.get(city.lower(), {"temp": "20C", "condition": "Unknown"})
    return {"city": city, **data}

def calculate(expression: str) -> dict:
    """Evaluate a math expression safely."""
    try:
        result = eval(expression, {"__builtins__": {}})
        return {"expression": expression, "result": str(result)}
    except Exception as e:
        return {"expression": expression, "error": str(e)}

AVAILABLE_FUNCTIONS = {
    "get_weather": get_weather,
    "calculate": calculate,
}

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a given city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "The city name, e.g. 'New York'"}
                },
                "required": ["city"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "calculate",
            "description": "Evaluate a mathematical expression and return the result.",
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {"type": "string", "description": "A math expression, e.g. '2 + 2 * 3'"}
                },
                "required": ["expression"],
            },
        },
    },
]

import os
import json
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY")
    base_url=os.getenv("OPENAI_BASE_URL") 
)


# ══════════════════════════════════════════════
# STEP 1: Define your Python functions (the actual tools)
# ══════════════════════════════════════════════

def get_weather(city: str) -> dict:
    """Simulate a weather lookup. In production, call a real API."""
    fake_weather = {
        "new york": {"temp": "22°C", "condition": "Sunny"},
        "london":   {"temp": "15°C", "condition": "Cloudy"},
        "tokyo":    {"temp": "28°C", "condition": "Humid"},
    }
    data = fake_weather.get(city.lower(), {"temp": "20°C", "condition": "Unknown"})
    return {"city": city, **data}


def calculate(expression: str) -> dict:
    """Evaluate a math expression safely."""
    try:
        # WARNING: In production, use a proper sandbox. This is for learning only.
        result = eval(expression, {"__builtins__": {}})
        return {"expression": expression, "result": str(result)}
    except Exception as e:
        return {"expression": expression, "error": str(e)}


# ══════════════════════════════════════════════
# STEP 2: Map function names → actual functions
# ══════════════════════════════════════════════

AVAILABLE_FUNCTIONS = {
    "get_weather": get_weather,
    "calculate": calculate,
}


# ══════════════════════════════════════════════
# STEP 3: Define the tool schemas (JSON descriptions)
#   This tells the model WHAT tools exist, their parameters,
#   and their descriptions. The model uses this to decide
#   when and how to call them.
# ══════════════════════════════════════════════

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a given city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "The city name, e.g. 'New York'",
                    }
                },
                "required": ["city"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "calculate",
            "description": "Evaluate a mathematical expression and return the result.",
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {
                        "type": "string",
                        "description": "A math expression to evaluate, e.g. '2 + 2 * 3'",
                    }
                },
                "required": ["expression"],
            },
        },
    },
]


# ══════════════════════════════════════════════
# STEP 4: The main flow — call API, detect tool calls, execute, return results
# ══════════════════════════════════════════════

def run():
    user_question = "What's the weather in Tokyo, and what is 145 * 37?"

    print(f"User: {user_question}\n")

    messages = [
        {"role": "system", "content": "You are a helpful assistant. Use the provided tools when needed."},
        {"role": "user", "content": user_question},
    ]

    # ── First API call: the model decides what tools to call ──
    response = client.chat.completions.create(
        model=os.getenv("OPENAI_MODEL),,
        messages=messages,
        tools=TOOLS,
        tool_choice="auto",         # Let the model decide
    )

    assistant_message = response.choices[0].message
    print(f"[Model Decision] finish_reason = {response.choices[0].finish_reason}")

    # ── Check if the model wants to call tools ──
    if assistant_message.tool_calls:
        print(f"[Model wants to call {len(assistant_message.tool_calls)} tool(s)]\n")

        # IMPORTANT: append the assistant's message (with tool_calls) to history
        messages.append(assistant_message)

        # ── Execute each tool call ──
        for tool_call in assistant_message.tool_calls:
            func_name = tool_call.function.name
            func_args = json.loads(tool_call.function.arguments)

            print(f"  Calling: {func_name}({func_args})")

            # Look up and execute the function
            func = AVAILABLE_FUNCTIONS[func_name]
            result = func(**func_args)

            print(f"  Result : {result}\n")

            # IMPORTANT: send the result back as a "tool" role message
            messages.append({
                "role": "tool",
                "tool_call_id": tool_call.id,        # Must match the tool_call's id
                "content": json.dumps(result),
            })

        # ── Second API call: the model uses tool results to form its answer ──
        final_response = client.chat.completions.create(
            model="gpt-4o-mini",
            messages=messages,
            tools=TOOLS,
        )

        final_answer = final_response.choices[0].message.content
        print(f"Assistant: {final_answer}")

    else:
        # Model didn't need tools — it answered directly
        print(f"Assistant: {assistant_message.content}")


if __name__ == "__main__":
    run()

┌─── OUTER LOOP (conversation turns) ───────────────────────┐
│                                                           │
│       User says something → append to messages            │
│                                                           │
│   ┌─── INNER LOOP (tool execution) ──────────────────┐    │
│   │                                                  │    │
│   │   Call API with messages                         │    │
│   │   ↓                                              │    │
│   │   Model returns tool_calls?                      │    │
│   │     YES → execute tools, append results, LOOP    │    │
│   │     NO  → return text response                   │    │
│   │                                                  │    │
│   └──────────────────────────────────────────────────┘    │
│                                                           │
│   Print response → wait for next user input               │
│                                                           │
└───────────────────────────────────────────────────────────┘

import os
import json
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

# ──────────────────────────────────────────────
# Tools — same as Chapter 3, but integrated into a chat loop
# ──────────────────────────────────────────────

def get_weather(city: str) -> dict:
    """Simulate a weather lookup."""
    fake_weather = {
        "new york": {"temp": "22°C", "condition": "Sunny"},
        "london":   {"temp": "15°C", "condition": "Cloudy"},
        "tokyo":    {"temp": "28°C", "condition": "Humid"},
        "paris":    {"temp": "18°C", "condition": "Rainy"},
        "mumbai":   {"temp": "34°C", "condition": "Hot and humid"},
    }
    data = fake_weather.get(city.lower(), {"temp": "20°C", "condition": "Unknown"})
    return {"city": city, **data}


def calculate(expression: str) -> dict:
    """Evaluate a math expression safely."""
    try:
        result = eval(expression, {"__builtins__": {}})
        return {"expression": expression, "result": str(result)}
    except Exception as e:
        return {"expression": expression, "error": str(e)}


AVAILABLE_FUNCTIONS = {
    "get_weather": get_weather,
    "calculate": calculate,
}

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a given city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "The city name, e.g. 'New York'"}
                },
                "required": ["city"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "calculate",
            "description": "Evaluate a mathematical expression and return the result.",
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {"type": "string", "description": "A math expression, e.g. '2 + 2 * 3'"}
                },
                "required": ["expression"],
            },
        },
    },
]


# ──────────────────────────────────────────────
# The tool execution loop — this is the core pattern
# ──────────────────────────────────────────────

def process_tool_calls(messages):
    """
    Repeatedly calls the model until it stops requesting tools.
    Returns the final assistant content.

    This is the INNER LOOP that handles:
    1. Model requests tool calls → execute them → send results → repeat
    2. Model responds with text → return it (loop ends)
    """
    while True:
        response = client.chat.completions.create(
            model="gpt-4o-mini",
            messages=messages,
            tools=TOOLS,
            tool_choice="auto",
        )

        assistant_message = response.choices[0].message
        finish_reason = response.choices[0].finish_reason

        # If the model wants to call tools
        if assistant_message.tool_calls:
            # Append the assistant message (contains tool_calls metadata)
            messages.append(assistant_message)

            for tool_call in assistant_message.tool_calls:
                func_name = tool_call.function.name
                func_args = json.loads(tool_call.function.arguments)

                print(f"  🔧 Calling {func_name}({func_args})")

                # Execute the function
                func = AVAILABLE_FUNCTIONS.get(func_name)
                if func:
                    result = func(**func_args)
                else:
                    result = {"error": f"Unknown function: {func_name}"}

                # Append the tool result to messages
                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": json.dumps(result),
                })

            # Loop again — model might want to call more tools
            continue

        else:
            # No more tool calls — model is done, return the text
            messages.append({
                "role": "assistant",
                "content": assistant_message.content,
            })
            return assistant_message.content


# ──────────────────────────────────────────────
# The chatbot loop (outer loop = conversation turns)
# ──────────────────────────────────────────────

def run_chatbot():
    messages = [
        {
            "role": "system",
            "content": (
                "You are a helpful assistant with access to tools. "
                "Use the weather tool when asked about weather, "
                "and the calculator when math is involved. "
                "Always respond naturally after using tools."
            ),
        },
    ]

    print("=" * 60)
    print("  Chatbot with Tools  (type 'exit' to quit)")
    print("=" * 60)

    while True:
        try:
            user_input = input("\nYou: ").strip()
        except (EOFError, KeyboardInterrupt):
            print("\nGoodbye!")
            break

        if not user_input:
            continue
        if user_input.lower() in ("exit", "quit"):
            print("Goodbye!")
            break

        messages.append({"role": "user", "content": user_input})

        print()  # Blank line before tool calls / response
        response_text = process_tool_calls(messages)
        print(f"\nAssistant: {response_text}")


if __name__ == "__main__":
    run_chatbot()

def process_tool_calls(messages):
    """
    Repeatedly calls the model until it stops requesting tools.
    Returns the final assistant content.
    """
    while True:
        response = client.chat.completions.create(
            model=os.getenv("OPENAI_MODEL),
            messages=messages,
            tools=TOOLS,
            tool_choice="auto",
        )

        assistant_message = response.choices[0].message
        finish_reason = response.choices[0].finish_reason

        if assistant_message.tool_calls:
            # Append the assistant message WITH its tool_calls metadata
            messages.append(assistant_message)

            for tool_call in assistant_message.tool_calls:
                func_name = tool_call.function.name
                func_args = json.loads(tool_call.function.arguments)

                print(f"  🔧Tool Calling {func_name}({func_args})")

                func = AVAILABLE_FUNCTIONS.get(func_name)
                if func:
                    result = func(**func_args)
                else:
                    result = {"error": f"Unknown function: {func_name}"}

                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": json.dumps(result),
                })

            # Loop again — model might want more tools
            continue

        else:
            # No tool calls — we have a text response
            messages.append({
                "role": "assistant",
                "content": assistant_message.content,
            })
            return assistant_message.content

messages = [
    # 1. System prompt (set at start)
    {"role": "system", "content": "You are a helpful assistant with tools..."},

    # 2. User's question
    {"role": "user", "content": "What's the weather in London and Tokyo..."},

    # 3. Model's first response (contains tool_calls, no text content)
    {"role": "assistant", "tool_calls": [
        {"id": "call_abc", "function": {"name": "get_weather", "arguments": '{"city":"London"}'}},
        {"id": "call_def", "function": {"name": "get_weather", "arguments": '{"city":"Tokyo"}'}},
    ]},

    # 4. Tool result: London weather
    {"role": "tool", "tool_call_id": "call_abc",
     "content": '{"city":"London","temp":"15°C","condition":"Cloudy"}'},

    # 5. Tool result: Tokyo weather
    {"role": "tool", "tool_call_id": "call_def",
     "content": '{"city":"Tokyo","temp":"28°C","condition":"Humid"}'},

    # 6. Model's second response (another tool_call)
    {"role": "assistant", "tool_calls": [
        {"id": "call_ghi", "function": {"name": "calculate", "arguments": '{"expression":"28-15"}'}},
    ]},

    # 7. Tool result: calculation
    {"role": "tool", "tool_call_id": "call_ghi",
     "content": '{"expression":"28-15","result":"13"}'},

    # 8. Model's final text response
    {"role": "assistant", "content": "London is 15°C and cloudy, while Tokyo is 28°C..."},
]

def run_chatbot():
    messages = [
        {
            "role": "system",
            "content": (
                "You are a helpful assistant with access to tools. "
                "Use the weather tool when asked about weather, "
                "and the calculator when math is involved. "
                "Always respond naturally after using tools."
            ),
        },
    ]

    print("=" * 60)
    print("  Chatbot with Tools  (type 'exit' to quit)")
    print("=" * 60)

    while True:
        try:
            user_input = input("\nYou: ").strip()
        except (EOFError, KeyboardInterrupt):
            print("\nGoodbye!")
            break

        if not user_input:
            continue
        if user_input.lower() in ("exit", "quit"):
            print("Goodbye!")
            break

        messages.append({"role": "user", "content": user_input})

        print()  # Blank line before response
        response_text = process_tool_calls(messages)
        print(f"\nAssistant: {response_text}")

# ✅ Correct order
messages.append(assistant_message)     # The model's decision (contains tool_calls)
messages.append({"role": "tool", ...}) # The result

# ❌ Wrong: missing the assistant message
messages.append({"role": "tool", ...}) # API will error — what tool_call does this respond to?

if assistant_message.tool_calls:
    # ... execute tools ...
    continue   # ← Go back and call the API again

else:
    # ... append text response ...
    return     # ← Done, exit the inner loop

python main.py

import json
from openai import OpenAI


class Agent:
    """
    A simple agent: takes a task, uses tools, returns a result.

    This is the inner loop from Chapter 4 wrapped in a class,
    with a clean interface: agent.run(task) -> result.
    """

    def __init__(
        self,
        client: OpenAI,
        name: str,
        system_prompt: str,
        tools: list[dict] | None = None,
        functions: dict | None = None,
        model: str = "gpt-4o-mini",
    ):
        self.client = client
        self.name = name
        self.system_prompt = system_prompt
        self.tools = tools or []
        self.functions = functions or {}
        self.model = model

    def run(self, task: str) -> str:
        """Execute a task and return the result."""
        print(f"\n[{self.name}] Starting task: {task[:80]}...")

        messages = [
            {"role": "system", "content": self.system_prompt},
            {"role": "user", "content": task},
        ]

        while True:
            kwargs = {"model": self.model, "messages": messages}
            if self.tools:
                kwargs["tools"] = self.tools
                kwargs["tool_choice"] = "auto"

            response = self.client.chat.completions.create(**kwargs)
            assistant_message = response.choices[0].message

            if assistant_message.tool_calls:
                messages.append(assistant_message)
                for tool_call in assistant_message.tool_calls:
                    func_name = tool_call.function.name
                    func_args = json.loads(tool_call.function.arguments)

                    print(f"  [{self.name}] Tool: {func_name}({func_args})")

                    func = self.functions.get(func_name)
                    if func:
                        result = func(**func_args)
                    else:
                        result = {"error": f"Unknown tool: {func_name}"}

                    result_str = json.dumps(result) if isinstance(result, dict) else str(result)
                    messages.append({
                        "role": "tool",
                        "tool_call_id": tool_call.id,
                        "content": result_str,
                    })
                continue
            else:
                print(f"  [{self.name}] Done.")
                return assistant_message.content

def __init__(self, client, name, system_prompt, tools=None, functions=None, model="openai/gpt-oss-120b"):

def run(self, task: str) -> str:

def look_up_population(country: str) -> dict:
    """Simulated database of country populations."""
    data = {
        "india":   {"country": "India",   "population": "1.44 billion"},
        "china":   {"country": "China",   "population": "1.43 billion"},
        "usa":     {"country": "USA",     "population": "334 million"},
        "japan":   {"country": "Japan",   "population": "125 million"},
        "germany": {"country": "Germany", "population": "84 million"},
    }
    return data.get(country.lower(), {"country": country, "population": "Unknown"})


def calculate(expression: str) -> dict:
    """Evaluate a math expression."""
    try:
        result = eval(expression, {"__builtins__": {}})
        return {"expression": expression, "result": str(result)}
    except Exception as e:
        return {"expression": expression, "error": str(e)}

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "look_up_population",
            "description": "Look up the population of a country.",
            "parameters": {
                "type": "object",
                "properties": {
                    "country": {"type": "string", "description": "Country name"}
                },
                "required": ["country"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "calculate",
            "description": "Evaluate a mathematical expression.",
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {"type": "string", "description": "Math expression to evaluate"}
                },
                "required": ["expression"],
            },
        },
    },
]

FUNCTIONS = {
    "look_up_population": look_up_population,
    "calculate": calculate,
}

# ──────────────────────────────────────────────
# Creating a Research Agent
# ──────────────────────────────────────────────
research_agent = Agent(
    client=client,
    name="Research Agent",
    system_prompt=(
        "You are a research agent. When given a question, "
        "use your tools to look up data and perform calculations. "
        "Always show your work and provide a clear final answer."
    ),
    tools=TOOLS,
    functions=FUNCTIONS,
)

result = research_agent.run(
    "What is the combined population of India and Japan? "
    "Show the individual numbers and the total."
)

print("\n" + "=" * 60)
print("FINAL RESULT:")
print("=" * 60)
print(result)

messages = [
    # 1. System prompt
    {"role": "system", "content": "You are a research agent..."},

    # 2. The task
    {"role": "user", "content": "What is the combined population of India and Japan?..."},

    # 3. Model decides to look up both countries
    {"role": "assistant", "tool_calls": [
        {"id": "call_abc", "function": {"name": "look_up_population", "arguments": '{"country":"India"}'}},
        {"id": "call_def", "function": {"name": "look_up_population", "arguments": '{"country":"Japan"}'}},
    ]},

    # 4. India result
    {"role": "tool", "tool_call_id": "call_abc",
     "content": '{"country": "India", "population": "1.44 billion"}'},

    # 5. Japan result
    {"role": "tool", "tool_call_id": "call_def",
     "content": '{"country": "Japan", "population": "125 million"}'},

    # 6. Model decides to calculate the sum
    {"role": "assistant", "tool_calls": [
        {"id": "call_ghi", "function": {"name": "calculate", "arguments": '{"expression":"1440000000 + 125000000"}'}},
    ]},

    # 7. Calculation result
    {"role": "tool", "tool_call_id": "call_ghi",
     "content": '{"expression": "1440000000 + 125000000", "result": "1565000000"}'},

    # 8. Final text response
    {"role": "assistant", "content": "The population of India is approximately 1.44 billion..."},
]

# A research agent with data tools
researcher = Agent(
    client=client,
    name="Researcher",
    system_prompt="You research topics thoroughly using available tools.",
    tools=SEARCH_TOOLS,
    functions=SEARCH_FUNCTIONS,
)

# A math agent with calculation tools
calculator = Agent(
    client=client,
    name="Calculator",
    system_prompt="You solve math problems step by step.",
    tools=MATH_TOOLS,
    functions=MATH_FUNCTIONS,
)

# Same class, different configuration
research_result = researcher.run("Find information about Python's GIL")
math_result = calculator.run("What is the integral of x^2 from 0 to 5?")

def run(self, task: str) -> str:
    messages = [  # ← Fresh every call
        {"role": "system", "content": self.system_prompt},
        {"role": "user", "content": task},
    ]

python main.py

┌──────────────────────────────────────────┐
│  while iterations < max_iterations:      │
│      1. THINK   → call the model         │
│      2. DECIDE  → tool calls or text?    │
│      3. ACT     → execute tools          │
│      4. OBSERVE → feed results back      │
│      5. CHECK   → did agent call "done"? │
│          YES → return result             │
│          NO  → loop again                │
└──────────────────────────────────────────┘

# Injected automatically  the agent always has this tool
{
    "type": "function",
    "function": {
        "name": "task_complete",
        "description": "Call this when you have completed the task. Provide the final result.",
        "parameters": {
            "type": "object",
            "properties": {
                "result": {
                    "type": "string",
                    "description": "The final result/answer for the task.",
                }
            },
            "required": ["result"],
        },
    },
}

self.functions["task_complete"] = lambda result: {"__done__": True, "result": result}

class AgenticAgent:
    def __init__(self, client, name, system_prompt,
                 tools=None, functions=None,
                 model="openai/gpt-oss-120b", max_iterations=10):
        self.client = client
        self.name = name
        self.system_prompt = system_prompt
        self.model = model
        self.max_iterations = max_iterations
        self.functions = dict(functions or {})
        self.tools = list(tools or [])

        # Inject the completion tool
        self.tools.append({
            "type": "function",
            "function": {
                "name": "task_complete",
                "description": "Call this when you have completed the task.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "result": {"type": "string", "description": "The final result."}
                    },
                    "required": ["result"],
                },
            },
        })
        self.functions["task_complete"] = lambda result: {
            "__done__": True, "result": result
        }

    def run(self, task: str) -> str:
        messages = [
            {"role": "system", "content": self.system_prompt},
            {"role": "user", "content": task},
        ]

        for iteration in range(1, self.max_iterations + 1):
            print(f"  [{self.name}] Iteration {iteration}/{self.max_iterations}")

            response = self.client.chat.completions.create(
                model=self.model,
                messages=messages,
                tools=self.tools,
                tool_choice="auto",
            )
            assistant_message = response.choices[0].message

            # No tool calls = implicit completion
            if not assistant_message.tool_calls:
                return assistant_message.content or "(No response)"

            messages.append(assistant_message)

            for tool_call in assistant_message.tool_calls:
                func_name = tool_call.function.name
                func_args = json.loads(tool_call.function.arguments)

                try:
                    result = self.functions[func_name](**func_args)
                except Exception as e:
                    result = {"error": str(e)}

                # Check for explicit completion
                if isinstance(result, dict) and result.get("__done__"):
                    print(f"  [{self.name}] Task complete!")
                    return result["result"]

                result_str = json.dumps(result) if isinstance(result, dict) else str(result)
                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": result_str,
                })

        # Safety valve
        return f"[Stopped after {self.max_iterations} iterations]"

- while True:
+ for iteration in range(1, self.max_iterations + 1):
+     print(f"  [{self.name}] Iteration {iteration}/{self.max_iterations}")

+ self.tools.append({...task_complete schema...})
+ self.functions["task_complete"] = lambda result: {"__done__": True, "result": result}

  result = self.functions[func_name](**func_args)
+
+ if isinstance(result, dict) and result.get("__done__"):
+     return result["result"]

- func = self.functions.get(func_name)
- if func:
-     result = func(**func_args)
- else:
-     result = {"error": f"Unknown tool: {func_name}"}
+ try:
+     result = self.functions[func_name](**func_args)
+ except Exception as e:
+     result = {"error": str(e)}

def get_stock_price(symbol: str) -> dict:
    """Simulated stock price lookup."""
    prices = {
        "AAPL": 182.52, "GOOGL": 141.80, "MSFT": 378.91,
        "AMZN": 178.25, "TSLA": 248.42, "META": 390.10,
    }
    price = prices.get(symbol.upper())
    if price:
        return {"symbol": symbol.upper(), "price": price, "currency": "USD"}
    return {"symbol": symbol, "error": "Symbol not found"}


def get_company_info(name: str) -> dict:
    """Simulated company info lookup."""
    info = {
        "apple":    {"name": "Apple Inc.",      "ticker": "AAPL",  "sector": "Technology", "employees": "164,000"},
        "google":   {"name": "Alphabet Inc.",   "ticker": "GOOGL", "sector": "Technology", "employees": "182,000"},
        "microsoft":{"name": "Microsoft Corp.", "ticker": "MSFT",  "sector": "Technology", "employees": "221,000"},
    }
    return info.get(name.lower(), {"name": name, "error": "Company not found"})


def calculate(expression: str) -> dict:
    """Evaluate a math expression."""
    try:
        result = eval(expression, {"__builtins__": {}})
        return {"expression": expression, "result": str(result)}
    except Exception as e:
        return {"expression": expression, "error": str(e)}

analyst = AgenticAgent(
    client=client,
    name="Market Analyst",
    system_prompt=(
        "You are a market research analyst. "
        "Use your tools to gather data, perform calculations, and produce insights. "
        "When you have a complete analysis, call the task_complete tool with your findings."
    ),
    tools=TOOLS,
    functions=FUNCTIONS,
    max_iterations=10,
)

result = analyst.run(
    "Compare Apple and Microsoft: look up both companies' info and stock prices, "
    "then calculate which stock is cheaper per 1,000 employees. "
    "Present a brief analysis."
)

print("\n" + "=" * 60)
print("FINAL ANALYSIS:")
print("=" * 60)
print(result)

Iteration 1: [system, user] → API → [assistant+tools, tool, tool]
Iteration 2: [system, user, asst, tool, tool] → API → [assistant+tools, tool, tool]
Iteration 3: [system, user, asst, tool, tool, asst, tool, tool] → API → [assistant+tools, tool, tool]
Iteration 4: [system, user, asst, tool, tool, asst, tool, tool, asst, tool, tool] → API → task_complete → EXIT

# Chapter 5: Implicit completion
# The model might respond with:
#   "Based on my calculations, Apple is cheaper at $1.11 per 1000 employees."
# But it might also respond with:
#   "Let me also check Google for comparison..."  ← then call more tools
#   "Interesting, let me recalculate..."           ← unnecessary extra work

# Chapter 6: Explicit completion
# The model calls:
#   task_complete(result="Apple (AAPL) at $182.52 is cheaper per 1,000 employees
#                         ($1.11) compared to Microsoft (MSFT) at $378.91 ($1.71).")

try:
    result = self.functions[func_name](**func_args)
except Exception as e:
    result = {"error": str(e)}

# Chapter 5: "I hope it stops eventually"
while True:
    response = call_model()
    if not response.tool_calls:
        return response.content  # 🤞

# Chapter 6: "It will stop, and I'll know why"
for i in range(max_iterations):
    response = call_model()
    for tool in response.tool_calls:
        result = execute(tool)
        if result.get("__done__"):
            return result["result"]  # ✅ Explicit completion
return "[Safety limit reached]"      # ✅ Bounded

python main.py

User Input → Clarifier → PRD Agent → Planner → Coder → Working Software

python main.py "Build a calculator app with HTML, CSS, and JavaScript"

"""Framework Package Init"""
from .base_agent import BaseAgent
from .tool_registry import ToolRegistry
from .message_bus import MessageBus, Message
from .orchestrator import Orchestrator, Phase

__all__ = ["BaseAgent", "ToolRegistry", "MessageBus", "Message", "Orchestrator", "Phase"]

class ToolRegistry:
    """
    Manages the registration and execution of tools.

    Each tool is:
        - A Python callable (the function to run)
        - A JSON schema (tells the model what parameters the function accepts)
        - A name and description (helps the model decide when to use it)
    """

    def __init__(self):
        self._tools: dict[str, dict] = {}

    def register(self, name: str, description: str, parameters: dict, func: callable):
        """Register a tool with its schema and handler."""
        self._tools[name] = {
            "func": func,
            "schema": {
                "type": "function",
                "function": {
                    "name": name,
                    "description": description,
                    "parameters": parameters,
                },
            },
        }

    def get_schemas(self) -> list[dict]:
        """Return all tool schemas in OpenAI API format."""
        return [t["schema"] for t in self._tools.values()]

    def get_names(self) -> list[str]:
        """Return all registered tool names."""
        return list(self._tools.keys())

    def has_tool(self, name: str) -> bool:
        return name in self._tools

    def execute(self, name: str, arguments: dict) -> any:
        """Execute a tool by name with the given arguments."""
        if name not in self._tools:
            raise ValueError(f"Tool '{name}' is not registered.")
        return self._tools[name]["func"](**arguments)

    def __len__(self):
        return len(self._tools)

    def __repr__(self):
        return f"ToolRegistry(tools={self.get_names()})"

import json
import os
import time
from openai import OpenAI
from .tool_registry import ToolRegistry


class BaseAgent:
    """
    Base class for all agents in the multi-agent system.

    Subclasses should:
        1. Set self.name and self.system_prompt in __init__
        2. Register tools via self.tool_registry.register(...)
        3. Optionally override pre_run() and post_run() hooks
    """

    COLORS = {
        "blue": "\033[94m", "green": "\033[92m", "yellow": "\033[93m",
        "magenta": "\033[95m", "cyan": "\033[96m", "red": "\033[91m",
        "reset": "\033[0m", "bold": "\033[1m", "dim": "\033[2m",
    }

    # Class-level rate limiter — shared across ALL agents
    _api_call_timestamps: list = []
    _rate_limit: int = 14
    _rate_window: int = 60

    def __init__(self, client: OpenAI, name: str = "Agent",
                 system_prompt: str = "You are a helpful assistant.",
                 model: str = None, max_iterations: int = 15, color: str = "cyan"):
        self.client = client
        self.name = name
        self.system_prompt = system_prompt
        self.model = model or os.getenv("OPENAI_MODEL", "gpt-4o-mini")
        self.max_iterations = max_iterations
        self.color = color
        self.tool_registry = ToolRegistry()

        # Built-in task_complete tool
        self.tool_registry.register(
            name="task_complete",
            description="Call this tool when you have fully completed the assigned task.",
            parameters={
                "type": "object",
                "properties": {
                    "result": {
                        "type": "string",
                        "description": "The complete final result/deliverable for the task.",
                    }
                },
                "required": ["result"],
            },
            func=self._handle_task_complete,
        )

    @classmethod
    def _wait_for_rate_limit(cls):
        """Sleep if we're about to exceed the API rate limit."""
        now = time.time()
        cls._api_call_timestamps = [
            t for t in cls._api_call_timestamps if now - t < cls._rate_window
        ]
        if len(cls._api_call_timestamps) >= cls._rate_limit:
            oldest = cls._api_call_timestamps[0]
            wait_time = cls._rate_window - (now - oldest) + 1
            if wait_time > 0:
                print(f"\033[93m⏳ Rate limit: waiting {wait_time:.0f}s...\033[0m")
                time.sleep(wait_time)
        cls._api_call_timestamps.append(time.time())

    def log(self, message: str, style: str = ""):
        c = self.COLORS.get(self.color, "")
        r = self.COLORS["reset"]
        s = self.COLORS.get(style, "")
        print(f"{c}[{self.name}]{r} {s}{message}{r}")

    def pre_run(self, task: str) -> str:
        return task

    def post_run(self, result: str) -> str:
        return result

    def run(self, task: str) -> str:
        task = self.pre_run(task)
        self.log(f"📋 Task received", "bold")
        self.log(f"   {task[:120]}{'...' if len(task) > 120 else ''}", "dim")

        tool_names = self.tool_registry.get_names()
        tool_reminder = (
            f"\n\nIMPORTANT: You have ONLY these tools available: {', '.join(tool_names)}. "
            "Do NOT invent tool names or add prefixes. Use the exact names listed above."
        )

        messages = [
            {"role": "system", "content": self.system_prompt + tool_reminder},
            {"role": "user", "content": task},
        ]
        tool_schemas = self.tool_registry.get_schemas()

        for iteration in range(1, self.max_iterations + 1):
            self.log(f"🔄 Iteration {iteration}/{self.max_iterations}", "dim")
            self._wait_for_rate_limit()

            kwargs = {"model": self.model, "messages": messages}
            if tool_schemas:
                kwargs["tools"] = tool_schemas
                kwargs["tool_choice"] = "auto"

            response = self.client.chat.completions.create(**kwargs)
            assistant_message = response.choices[0].message

            if not assistant_message.tool_calls:
                result = assistant_message.content or "(empty response)"
                self.log("💬 Completed (text response)")
                return self.post_run(result)

            messages.append(assistant_message)
            for tool_call in assistant_message.tool_calls:
                func_name = tool_call.function.name
                func_args = json.loads(tool_call.function.arguments)
                self.log(f"🔧 {func_name}({self._summarize_args(func_args)})")

                try:
                    result = self.tool_registry.execute(func_name, func_args)
                except Exception as e:
                    result = {"error": str(e)}
                    self.log(f"❌ Error: {e}", "red")

                if isinstance(result, dict) and result.get("__done__"):
                    self.log("✅ Task complete!", "bold")
                    return self.post_run(result["result"])

                result_str = json.dumps(result) if isinstance(result, (dict, list)) else str(result)
                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": result_str,
                })

        self.log(f"⚠️  Max iterations ({self.max_iterations}) reached!", "yellow")
        return self.post_run(f"[Agent stopped after {self.max_iterations} iterations]")

    def _handle_task_complete(self, result: str) -> dict:
        return {"__done__": True, "result": result}

    def _summarize_args(self, args: dict) -> str:
        parts = []
        for k, v in args.items():
            val_str = str(v)
            if len(val_str) > 60:
                val_str = val_str[:57] + "..."
            parts.append(f"{k}={val_str!r}")
        return ", ".join(parts)