Skip to content

OPENAI_DEEPDIVE.md

Latest commit

 

History

History
333 lines (234 loc) · 6.2 KB

OPENAI_DEEPDIVE.md

File metadata and controls

333 lines (234 loc) · 6.2 KB
Raw

OpenAI Deep Dive – Chat Completions & Function Calling

Audience: GenAI Developers, Backend Engineers, AI Engineers
Level: Intermediate → Advanced
Language: Python
Focus: Practical usage, production patterns, and mental models

1. Introduction

The Chat Completions API is the foundation for building conversational AI systems using :contentReference[oaicite:0]{index=0} models.

It enables:

  • Multi-turn conversations
  • Role-based prompting (system, user, assistant)
  • Tool / function calling
  • Structured AI outputs for automation

This document explains:

  1. How Chat Completions work
  2. How messages are structured
  3. What function calling is
  4. How to implement function calling in Python
  5. Production best practices

2. Chat Completions – Core Concept

At its core, Chat Completions take a list of messages and return the next assistant message.

Mental Model


Conversation History → LLM → Next Best Response

Each message has:

  • role: system | user | assistant | tool
  • content: text or structured output

3. Basic Chat Completion (Python)

Example: Simple Question Answering

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[
        {"role": "system", "content": "You are a helpful tutor."},
        {"role": "user", "content": "Explain what recursion is in simple terms."}
    ]
)

print(response.choices[0].message.content)

Key Points

  • system sets behavior
  • user asks the question
  • assistant is generated by the model
  • The model is stateless → you must send history every time

4. Message Roles Explained

4.1 System Message

Controls personality, tone, rules.

"You are a strict Python code reviewer."

4.2 User Message

Actual user input.

"Write a recursive factorial function."

4.3 Assistant Message

Model-generated response.

4.4 Tool Message

Used when a tool/function returns output back to the model.

5. Why Function Calling?

LLMs are great at text, but weak at:

  • Performing actions
  • Calling APIs
  • Returning structured JSON reliably

Function calling bridges this gap.

Without Function Calling

❌ Unstructured text ❌ Hard to parse ❌ Error-prone automation

With Function Calling

✅ Structured JSON ✅ Deterministic schema ✅ Safe automation

6. Function Calling – Conceptual Flow

User Request
   ↓
LLM decides: "I should call a function"
   ↓
LLM returns function name + arguments (JSON)
   ↓
Your code executes the function
   ↓
Result sent back to LLM
   ↓
LLM generates final response

7. Defining a Function Schema

Functions are defined using JSON Schema.

Example Function: Get Weather

functions = [
    {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "City name"
                }
            },
            "required": ["city"]
        }
    }
]

8. Chat Completion with Function Calling

Step 1: Send User Prompt + Function Definition

response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What's the weather in Bengaluru?"}
    ],
    functions=functions,
    function_call="auto"
)

9. Detecting a Function Call

message = response.choices[0].message

if message.function_call:
    function_name = message.function_call.name
    arguments = message.function_call.arguments

Example output:

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

10. Executing the Function

import json

def get_weather(city: str):
    # Mocked API call
    return {
        "city": city,
        "temperature": "28°C",
        "condition": "Cloudy"
    }

args = json.loads(message.function_call.arguments)
result = get_weather(**args)

11. Sending Tool Result Back to the Model

followup_response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What's the weather in Bengaluru?"},
        message,
        {
            "role": "tool",
            "name": "get_weather",
            "content": json.dumps(result)
        }
    ]
)

print(followup_response.choices[0].message.content)

12. Final User-Facing Output

The current weather in Bengaluru is 28°C with cloudy conditions.

13. Common Use Cases

  • API orchestration
  • Database queries
  • RAG pipelines
  • Workflow automation
  • Agent frameworks
  • Admin dashboards
  • AI copilots

14. Best Practices (Production)

14.1 Validate Inputs

Always validate function arguments before execution.

14.2 Never Trust the Model Fully

Treat LLM outputs as suggestions, not commands.

14.3 Use Idempotent Functions

Avoid side effects where possible.

14.4 Log Everything

Store:

  • Prompt
  • Function name
  • Arguments
  • Result

15. Chat Completions vs Tools vs Agents

Feature Chat Completion Function Calling Agents
Free-form text ✅ ⚠️ ⚠️
Structured output ❌ ✅ ✅
Automation ❌ ✅ ✅
Multi-step reasoning ⚠️ ⚠️ ✅

16. Key Takeaways

  • Chat Completions are the foundation

  • Function calling enables safe automation

  • The model decides, your code executes

  • This pattern is core to:

    • RAG
    • Agents
    • AI workflows
    • Enterprise AI systems

17. What to Learn Next

  • Tool calling vs Function calling
  • JSON mode & response schemas
  • Agents SDK
  • RAG + function calling
  • Error recovery strategies