Module: Implement AI Solutions with Foundry

Section: Generative AI with Foundry

Lesson Title: Completions and Chat Completions

Introduction: Understanding the Generative AI Paradigm

In the landscape of modern software development, integrating artificial intelligence into enterprise platforms has shifted from a specialized research task to a fundamental architectural requirement. Within the Foundry ecosystem, Generative AI is not just a tool for generating text; it is a bridge between unstructured human intent and structured data operations. At the heart of this integration lie two primary interfaces: Completions and Chat Completions. These represent the fundamental ways that developers interact with Large Language Models (LLMs) to perform tasks ranging from summarization and classification to complex conversational logic.

Understanding the distinction between these two interfaces is critical for any engineer working in Foundry. While they may seem similar on the surface, they represent different mental models of how a machine "thinks" and responds. A Completion model is essentially a text-in, text-out engine that predicts the most likely next sequence of tokens based on a provided prompt. Conversely, a Chat Completion model is structured to manage the state of a dialogue, allowing the model to understand context, history, and the roles of participants. Mastering these interfaces allows you to build applications that are not only accurate but also predictable and maintainable.

Why does this matter for your work in Foundry? Because the efficiency of your AI implementation dictates the user experience. If you use a Completion approach where a Chat approach is needed, your application might struggle with context retention. If you use a Chat approach where a simple completion suffices, you might be wasting compute resources and increasing latency unnecessarily. This lesson provides a deep dive into these concepts, ensuring you can make informed architectural decisions for your AI-powered solutions.

The Anatomy of Completions

The "Completion" interface is the foundational primitive of generative AI. At its core, it is a function that takes a string of text—the prompt—and returns a continuation of that text. Think of it as a supercharged version of the "autocomplete" feature you see in your email client, but with an vastly expanded understanding of grammar, facts, and context.

When you send a prompt to a completion endpoint, you are essentially telling the model: "Here is the beginning of a document; please complete it." This is highly effective for tasks where the output is a direct extension of the input. For example, if you provide a list of items and ask the model to format them into a table, the completion model treats the entire input as the "text so far" and generates the subsequent tokens that form the table.

Key Parameters in Completions

Prompt: The input string that serves as the basis for generation.
Max Tokens: The limit on the number of tokens the model will generate. This acts as a budget for your output.
Temperature: A value between 0 and 1 (or higher) that controls randomness. Lower values make the output deterministic and focused, while higher values make it creative and unpredictable.
Stop Sequences: Specific strings that, if generated, force the model to stop outputting. This is essential for preventing the model from rambling.

Callout: Completion vs. Chat Completion The fundamental difference lies in structure. Completion models see a single, continuous stream of text. They do not intrinsically understand that a user said something, followed by the AI saying something else. Chat Completion models, however, are trained on structured messages labeled by role (System, User, Assistant), which allows them to track the back-and-forth flow of a conversation without needing to re-process the entire history as a single block of text.

Implementing Chat Completions: The Conversational Standard

While the completion interface is powerful, the industry has largely converged on the Chat Completion interface as the standard for most applications. This is because most AI use cases—whether they are customer support bots, data analysis assistants, or code generation tools—are inherently conversational.

In the Chat Completion model, you send an array of messages rather than a single string. Each message has a role and content.

System: Defines the behavior, persona, and constraints of the AI.
User: Contains the query or input from the end user.
Assistant: Stores the previous responses generated by the AI to maintain context.

Why Use Chat Completions?

The primary advantage here is context management. By providing the model with a history of the conversation, you enable it to reference previous points, correct itself based on feedback, and maintain a consistent tone. In Foundry, this is particularly useful when building agents that interact with datasets. You can feed the model the system instructions to "act as a data analyst," and then provide the user's specific questions as part of a multi-turn conversation.

Practical Example: Building a Data Query Assistant

Let’s look at how you would implement a basic chat-based interaction within a Foundry environment. Assume we are building a tool that helps users query a internal database of supply chain metrics.

Step 1: Define the System Prompt

Your system prompt is the "North Star" for your AI. It should be clear, concise, and restrictive enough to prevent the model from hallucinating data.

# System prompt definition
system_message = {
    "role": "system",
    "content": "You are a helpful supply chain assistant. You only answer questions based on the provided supply chain datasets. If you do not know the answer, state that you do not have that information."
}

Step 2: Manage the Message History

To maintain context, you must append the user's input and the model's response to a list. This list is passed to the API every time you make a request.

# Initialize history
conversation_history = [system_message]

def get_ai_response(new_user_input):
    # Add user input
    conversation_history.append({"role": "user", "content": new_user_input})
    
    # Call the Foundry Chat Completion API
    response = foundry_ai.chat_completions.create(
        model="gpt-4",
        messages=conversation_history,
        temperature=0.2
    )
    
    # Extract and store the assistant's reply
    assistant_reply = response.choices[0].message.content
    conversation_history.append({"role": "assistant", "content": assistant_reply})
    
    return assistant_reply

Warning: Token Limits and Context Windows Every time you send the conversation_history to the model, you are consuming tokens. If the conversation goes on for a long time, you will eventually hit the "context window" limit of the model. You must implement a strategy to truncate or summarize older messages if the history grows too large, otherwise, your API calls will fail.

Best Practices for Prompt Engineering

Regardless of which interface you use, the quality of your output is almost entirely dependent on how you structure your prompt. This is often called "Prompt Engineering," though it is really just about clear communication.

Be Explicit about Persona: Tell the model who it is. "You are an expert financial analyst" yields better results than "Answer the following question."
Provide Examples (Few-Shot Prompting): If you need a specific output format (like JSON or a specific Markdown table), provide 2-3 examples of the input and the desired output.
Use Delimiters: Use clear separators like triple quotes (""") or XML tags (<data></data>) to help the model distinguish between instructions and the data it needs to process.
Chain of Thought: For complex logic, explicitly ask the model to "think step by step." This forces the model to break down the problem, which significantly improves accuracy in reasoning tasks.

The Power of System Messages

In a chat interface, the system message is your most powerful tool. Unlike the user prompt, which changes every time, the system message persists. Use it to set the "rules of the road." For example, if you are building an application for a regulated industry, use the system message to enforce compliance, such as: "You must always cite the source of your data and never offer investment advice."

Common Pitfalls and How to Avoid Them

Even experienced engineers fall into common traps when implementing LLMs. Being aware of these will save you hours of debugging.

Prompt Injection: Users may try to "jailbreak" your model by providing input designed to override your system prompt. Always treat user input as untrusted. If you are feeding user input into a database query, sanitize it thoroughly.
Over-Reliance on Randomness: Setting a high temperature (e.g., 0.9+) is great for creative writing, but it is disastrous for data extraction or classification. For tasks that require precision, keep the temperature at 0.0 or 0.1.
Ignoring Latency: Chat completions with long histories are slow. If your application requires real-time feedback, keep your message history as short as possible. Use a "summary" message to condense older parts of the conversation instead of sending the entire transcript.
Hardcoding Constants: Never hardcode your API keys or sensitive system prompts in your application code. Use Foundry’s secret management tools to inject these values at runtime.

Tip: Monitoring and Logging In a production Foundry environment, you should log every request and response pair. This is not just for auditing; it is for improvement. By reviewing these logs, you can identify where the model is failing and refine your system prompts accordingly.

Comparison: When to Use Which?

Scenario	Recommended Approach	Why?
Simple text completion (e.g., finishing a sentence)	Completion	Lower overhead, faster response times.
Building a customer support chatbot	Chat Completion	Essential for maintaining context and history.
Extracting entities from a single document	Completion	Direct input-to-output transformation.
Interactive data exploration tools	Chat Completion	Allows the user to ask follow-up questions.
Generating code snippets	Either	Chat is better for iterative refinement of code.

Step-by-Step Implementation Guide

To implement these solutions effectively in your Foundry project, follow this structured workflow:

Define the Use Case: Clearly identify if your application is a "one-shot" task (Completion) or a dialogue (Chat). If you are unsure, start with Chat; it is more flexible.
Prototype in a Sandbox: Use a playground or a notebook environment to test your prompts. Do not write your final prompt in the application code initially.
Establish Guardrails: Define what the AI should not do. Add these as negative constraints in your system prompt.
Implement State Management: If using Chat, build a function to handle the message history. Ensure that you have logic to prune the history when it exceeds a certain token count.
Test for Edge Cases: What happens if the user inputs gibberish? What happens if the user asks for something outside the scope of your system prompt? Ensure your code handles these gracefully.
Deploy and Monitor: Use the telemetry tools available in Foundry to track token usage and response quality. Iteratively update your prompts based on actual usage data.

Advanced Techniques: Token Efficiency

One of the most overlooked aspects of Generative AI implementation is token efficiency. Every token costs money and contributes to latency. Here are ways to keep your implementation lean:

System Prompt Optimization: Keep your system prompt as short as possible while still conveying the necessary instructions. Use clear, imperative language.
Selective History: You do not always need to send the entire conversation history. If the user is asking a question about a specific document, only send the relevant portions of the conversation that provide context for that document.
Streaming Responses: Instead of waiting for the entire response to be generated, use the streaming feature. This allows your application to start displaying the text to the user as it is generated, significantly improving the perceived speed of the application.

Code Snippet: Implementing Streaming

Streaming is particularly useful for Chat Completions, as it makes the experience feel much more "human-like."

# Example of streaming a response
stream = foundry_ai.chat_completions.create(
    model="gpt-4",
    messages=conversation_history,
    stream=True
)

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

This snippet demonstrates how to handle the response in chunks. By iterating over the stream, you can update your UI in real-time, providing immediate feedback to the user.

Handling Errors and Reliability

In a distributed system like Foundry, API calls can fail. Network issues, rate limits, or model capacity issues are realities you must plan for.

Implement Retries: Always use an exponential backoff strategy for your API calls. If a request fails due to a transient error, wait a few seconds before trying again.
Graceful Degradation: If the AI is unavailable, ensure your application has a fallback. For example, if the AI is supposed to categorize a document, have a rule-based fallback mechanism that handles the task if the AI call fails.
Timeouts: Never wait indefinitely for a response. Set a reasonable timeout for your API calls to ensure that your application remains responsive even if the AI service is lagging.

Future-Proofing Your AI Integration

The field of Generative AI is moving rapidly. Models are becoming faster, cheaper, and more capable. To ensure your Foundry implementation remains relevant:

Decouple Model Logic: Do not bake your prompt logic into your core business logic. Keep your prompts in a separate configuration file or a database. This allows you to update the prompt—or even swap out the underlying model—without having to redeploy your entire application.
Versioning: Treat your prompts like code. Use version control for your prompt templates so you can track changes and roll back if a new version performs worse than the old one.
Evaluation Frameworks: As you scale, you cannot manually check every response. Implement automated testing for your prompts. Create a set of "golden questions" and expected answers, and run these against your prompts every time you make a change to ensure you haven't introduced regressions.

Conclusion: Key Takeaways

Implementing Generative AI in Foundry is a balance between understanding the technical capabilities of the models and applying rigorous software engineering principles. By mastering the differences between Completions and Chat Completions, you position yourself to build applications that are both powerful and resilient.

Interface Selection: Use the Completion interface for simple, single-turn text generation tasks, and use the Chat Completion interface for any application that requires context, history, or a persona-driven interaction.
System Prompts are Paramount: The system prompt is the most effective way to control model behavior and enforce constraints. Spend the majority of your time refining these instructions.
Context Management: Always be mindful of token limits. Implement strategies for summarizing or truncating history to keep your API calls within the bounds of the model's window.
Iterative Design: Prompt engineering is an experimental process. Use playgrounds to test, version control to track changes, and automated evaluations to ensure reliability.
Efficiency Matters: Techniques like streaming and selective history management are essential for creating a responsive user experience and keeping your operational costs under control.
Reliability First: Treat AI calls as unreliable network services. Implement robust error handling, retries, and fallback mechanisms to ensure your application remains stable even when the model is under stress.
Decoupling: Keep your prompt logic separate from your business code to allow for easy updates and model swaps as technology evolves.

By adhering to these principles, you will move beyond simple experimentation and start delivering production-grade AI solutions that provide genuine value to your organization. The goal is not just to "use AI," but to build systems that are predictable, scalable, and deeply integrated into the data-driven workflows that Foundry is known for.

FAQ: Frequently Asked Questions

Q: Can I use Chat Completions for tasks that don't need history? A: Yes. You can simply provide a single user message in the chat history. While it might have a tiny bit more overhead than a standard completion, it is often easier to maintain a single code path for all AI interactions.

Q: How do I know which model to choose? A: Generally, choose the most capable model (e.g., GPT-4) for complex reasoning tasks and smaller, faster models for simple extraction or classification tasks. Always start with the most capable model to establish a baseline, then optimize for cost/speed if needed.

Q: What is the best way to handle "hallucinations"? A: You cannot completely eliminate them, but you can minimize them by providing the model with the exact data it needs to answer the question (Retrieval Augmented Generation) and by including a "I don't know" clause in your system prompt.

Q: How many examples should I provide in a few-shot prompt? A: Usually, 2-3 examples are sufficient. Providing too many examples can consume unnecessary tokens and may actually confuse the model if they are inconsistent.

Q: Is it safe to send sensitive data to the AI? A: Always check your organization's data privacy policy and the compliance certifications of the AI models provided within your Foundry environment. Never send PII (Personally Identifiable Information) unless you are certain the environment is configured to handle it securely.

Completions and Chat Completions