Upload 13 files

GPT-4.1 Prompting Guide.md

@@ -0,0 +1,1164 @@
+# [GPT-4.1 Prompting Guide](https://cookbook.openai.com/examples/gpt4-1_prompting_guide#2-long-context)
+> By [Noah MacCallum](https://x.com/noahmacca) and [Julian Lee](https://x.com/julianl093) (OpenAI)
+
+The GPT-4.1 family of models represents a significant step forward from GPT-4o in capabilities across coding, instruction following, and long context. In this prompting guide, we collate a series of important prompting tips derived from extensive internal testing to help developers fully leverage the improved abilities of this new model family.
+
+Many typical best practices still apply to GPT-4.1, such as providing context examples, making instructions as specific and clear as possible, and inducing planning via prompting to maximize model intelligence. However, we expect that getting the most out of this model will require some prompt migration. GPT-4.1 is trained to follow instructions more closely and more literally than its predecessors, which tended to more liberally infer intent from user and system prompts. This also means, however, that GPT-4.1 is highly steerable and responsive to well-specified prompts - if model behavior is different from what you expect, a single sentence firmly and unequivocally clarifying your desired behavior is almost always sufficient to steer the model on course.
+
+Please read on for prompt examples you can use as a reference, and remember that while this guidance is widely applicable, no advice is one-size-fits-all. AI engineering is inherently an empirical discipline, and large language models are inherently nondeterministic; in addition to following this guide, we advise building informative evals and iterating often to ensure your prompt engineering changes are yielding benefits for your use case.
+
+# 1. Agentic Workflows
+GPT-4.1 is a great place to build agentic workflows. In model training we emphasized providing a diverse range of agentic problem-solving trajectories, and our agentic harness for the model achieves state-of-the-art performance for non-reasoning models on SWE-bench Verified, solving 55% of problems.
+
+## System Prompt Reminders
+In order to fully utilize the agentic capabilities of GPT-4.1, we recommend including three key types of reminders in all agent prompts. The following prompts are optimized specifically for the agentic coding workflow, but can be easily modified for general agentic use cases.
+
+1. Persistence: this ensures the model understands it is entering a multi-message turn, and prevents it from prematurely yielding control back to the user. Our example is the following:
+```
+You are an agent - please keep going until the user’s query is completely resolved, before ending your turn and yielding back to the user. Only terminate your turn when you are sure that the problem is solved.
+```
+
+Tool-calling: this encourages the model to make full use of its tools, and reduces its likelihood of hallucinating or guessing an answer. Our example is the following:
+```
+If you are not sure about file content or codebase structure pertaining to the user’s request, use your tools to read files and gather the relevant information: do NOT guess or make up an answer.
+```
+Planning [optional]: if desired, this ensures the model explicitly plans and reflects upon each tool call in text, instead of completing the task by chaining together a series of only tool calls. Our example is the following:
+```
+You MUST plan extensively before each function call, and reflect extensively on the outcomes of the previous function calls. DO NOT do this entire process by making function calls only, as this can impair your ability to solve the problem and think insightfully.
+```
+GPT-4.1 is trained to respond very closely to both user instructions and system prompts in the agentic setting. The model adhered closely to these three simple instructions and increased our internal SWE-bench Verified score by close to 20% - so we highly encourage starting any agent prompt with clear reminders covering the three categories listed above. As a whole, we find that these three instructions transform the model from a chatbot-like state into a much more “eager” agent, driving the interaction forward autonomously and independently.
+
+## Tool Calls
+Compared to previous models, GPT-4.1 has undergone more training on effectively utilizing tools passed as arguments in an OpenAI API request. We encourage developers to exclusively use the tools field to pass tools, rather than manually injecting tool descriptions into your prompt and writing a separate parser for tool calls, as some have reported doing in the past. This is the best way to minimize errors and ensure the model remains in distribution during tool-calling trajectories - in our own experiments, we observed a 2% increase in SWE-bench Verified pass rate when using API-parsed tool descriptions versus manually injecting the schemas into the system prompt.
+
+Developers should name tools clearly to indicate their purpose and add a clear, detailed description in the "description" field of the tool. Similarly, for each tool param, lean on good naming and descriptions to ensure appropriate usage. If your tool is particularly complicated and you'd like to provide examples of tool usage, we recommend that you create an `# Examples` section in your system prompt and place the examples there, rather than adding them into the "description' field, which should remain thorough but relatively concise. Providing examples can be helpful to indicate when to use tools, whether to include user text alongside tool calls, and what parameters are appropriate for different inputs. Remember that you can use “Generate Anything” in the Prompt Playground to get a good starting point for your new tool definitions.
+
+## Prompting-Induced Planning & Chain-of-Thought
+As mentioned already, developers can optionally prompt agents built with GPT-4.1 to plan and reflect between tool calls, instead of silently calling tools in an unbroken sequence. GPT-4.1 is not a reasoning model - meaning that it does not produce an internal chain of thought before answering - but in the prompt, a developer can induce the model to produce an explicit, step-by-step plan by using any variant of the Planning prompt component shown above. This can be thought of as the model “thinking out loud.” In our experimentation with the SWE-bench Verified agentic task, inducing explicit planning increased the pass rate by 4%.
+
+## Sample Prompt: SWE-bench Verified
+
+Below, we share the agentic prompt that we used to achieve our highest score on SWE-bench Verified, which features detailed instructions about workflow and problem-solving strategy. This general pattern can be used for any agentic task.
+
+```python
+from openai import OpenAI
+import os
+
+client = OpenAI(
+    api_key=os.environ.get(
+        "OPENAI_API_KEY", "<your OpenAI API key if not set as env var>"
+    )
+)
+
+SYS_PROMPT_SWEBENCH = """
+You will be tasked to fix an issue from an open-source repository.
+
+Your thinking should be thorough and so it's fine if it's very long. You can think step by step before and after each action you decide to take.
+
+You MUST iterate and keep going until the problem is solved.
+
+You already have everything you need to solve this problem in the /testbed folder, even without internet connection. I want you to fully solve this autonomously before coming back to me.
+
+Only terminate your turn when you are sure that the problem is solved. Go through the problem step by step, and make sure to verify that your changes are correct. NEVER end your turn without having solved the problem, and when you say you are going to make a tool call, make sure you ACTUALLY make the tool call, instead of ending your turn.
+
+THE PROBLEM CAN DEFINITELY BE SOLVED WITHOUT THE INTERNET.
+
+Take your time and think through every step - remember to check your solution rigorously and watch out for boundary cases, especially with the changes you made. Your solution must be perfect. If not, continue working on it. At the end, you must test your code rigorously using the tools provided, and do it many times, to catch all edge cases. If it is not robust, iterate more and make it perfect. Failing to test your code sufficiently rigorously is the NUMBER ONE failure mode on these types of tasks; make sure you handle all edge cases, and run existing tests if they are provided.
+
+You MUST plan extensively before each function call, and reflect extensively on the outcomes of the previous function calls. DO NOT do this entire process by making function calls only, as this can impair your ability to solve the problem and think insightfully.
+
+# Workflow
+
+## High-Level Problem Solving Strategy
+
+1. Understand the problem deeply. Carefully read the issue and think critically about what is required.
+2. Investigate the codebase. Explore relevant files, search for key functions, and gather context.
+3. Develop a clear, step-by-step plan. Break down the fix into manageable, incremental steps.
+4. Implement the fix incrementally. Make small, testable code changes.
+5. Debug as needed. Use debugging techniques to isolate and resolve issues.
+6. Test frequently. Run tests after each change to verify correctness.
+7. Iterate until the root cause is fixed and all tests pass.
+8. Reflect and validate comprehensively. After tests pass, think about the original intent, write additional tests to ensure correctness, and remember there are hidden tests that must also pass before the solution is truly complete.
+
+Refer to the detailed sections below for more information on each step.
+
+## 1. Deeply Understand the Problem
+Carefully read the issue and think hard about a plan to solve it before coding.
+
+## 2. Codebase Investigation
+- Explore relevant files and directories.
+- Search for key functions, classes, or variables related to the issue.
+- Read and understand relevant code snippets.
+- Identify the root cause of the problem.
+- Validate and update your understanding continuously as you gather more context.
+
+## 3. Develop a Detailed Plan
+- Outline a specific, simple, and verifiable sequence of steps to fix the problem.
+- Break down the fix into small, incremental changes.
+
+## 4. Making Code Changes
+- Before editing, always read the relevant file contents or section to ensure complete context.
+- If a patch is not applied correctly, attempt to reapply it.
+- Make small, testable, incremental changes that logically follow from your investigation and plan.
+
+## 5. Debugging
+- Make code changes only if you have high confidence they can solve the problem
+- When debugging, try to determine the root cause rather than addressing symptoms
+- Debug for as long as needed to identify the root cause and identify a fix
+- Use print statements, logs, or temporary code to inspect program state, including descriptive statements or error messages to understand what's happening
+- To test hypotheses, you can also add test statements or functions
+- Revisit your assumptions if unexpected behavior occurs.
+
+## 6. Testing
+- Run tests frequently using `!python3 run_tests.py` (or equivalent).
+- After each change, verify correctness by running relevant tests.
+- If tests fail, analyze failures and revise your patch.
+- Write additional tests if needed to capture important behaviors or edge cases.
+- Ensure all tests pass before finalizing.
+
+## 7. Final Verification
+- Confirm the root cause is fixed.
+- Review your solution for logic correctness and robustness.
+- Iterate until you are extremely confident the fix is complete and all tests pass.
+
+## 8. Final Reflection and Additional Testing
+- Reflect carefully on the original intent of the user and the problem statement.
+- Think about potential edge cases or scenarios that may not be covered by existing tests.
+- Write additional tests that would need to pass to fully validate the correctness of your solution.
+- Run these new tests and ensure they all pass.
+- Be aware that there are additional hidden tests that must also pass for the solution to be successful.
+- Do not assume the task is complete just because the visible tests pass; continue refining until you are confident the fix is robust and comprehensive.
+"""
+
+PYTHON_TOOL_DESCRIPTION = """This function is used to execute Python code or terminal commands in a stateful Jupyter notebook environment. python will respond with the output of the execution or time out after 60.0 seconds. Internet access for this session is disabled. Do not make external web requests or API calls as they will fail. Just as in a Jupyter notebook, you may also execute terminal commands by calling this function with a terminal command, prefaced with an exclamation mark.
+
+In addition, for the purposes of this task, you can call this function with an `apply_patch` command as input.  `apply_patch` effectively allows you to execute a diff/patch against a file, but the format of the diff specification is unique to this task, so pay careful attention to these instructions. To use the `apply_patch` command, you should pass a message of the following structure as "input":
+
+%%bash
+apply_patch <<"EOF"
+*** Begin Patch
+[YOUR_PATCH]
+*** End Patch
+EOF
+
+Where [YOUR_PATCH] is the actual content of your patch, specified in the following V4A diff format.
+
+*** [ACTION] File: [path/to/file] -> ACTION can be one of Add, Update, or Delete.
+For each snippet of code that needs to be changed, repeat the following:
+[context_before] -> See below for further instructions on context.
+- [old_code] -> Precede the old code with a minus sign.
++ [new_code] -> Precede the new, replacement code with a plus sign.
+[context_after] -> See below for further instructions on context.
+
+For instructions on [context_before] and [context_after]:
+- By default, show 3 lines of code immediately above and 3 lines immediately below each change. If a change is within 3 lines of a previous change, do NOT duplicate the first change's [context_after] lines in the second change's [context_before] lines.
+- If 3 lines of context is insufficient to uniquely identify the snippet of code within the file, use the @@ operator to indicate the class or function to which the snippet belongs. For instance, we might have:
+@@ class BaseClass
+[3 lines of pre-context]
+- [old_code]
++ [new_code]
+[3 lines of post-context]
+
+- If a code block is repeated so many times in a class or function such that even a single @@ statement and 3 lines of context cannot uniquely identify the snippet of code, you can use multiple `@@` statements to jump to the right context. For instance:
+
+@@ class BaseClass
+@@ 	def method():
+[3 lines of pre-context]
+- [old_code]
++ [new_code]
+[3 lines of post-context]
+
+Note, then, that we do not use line numbers in this diff format, as the context is enough to uniquely identify code. An example of a message that you might pass as "input" to this function, in order to apply a patch, is shown below.
+
+%%bash
+apply_patch <<"EOF"
+*** Begin Patch
+*** Update File: pygorithm/searching/binary_search.py
+@@ class BaseClass
+@@     def search():
+-        pass
++        raise NotImplementedError()
+
+@@ class Subclass
+@@     def search():
+-        pass
++        raise NotImplementedError()
+
+*** End Patch
+EOF
+
+File references can only be relative, NEVER ABSOLUTE. After the apply_patch command is run, python will always say "Done!", regardless of whether the patch was successfully applied or not. However, you can determine if there are issue and errors by looking at any warnings or logging lines printed BEFORE the "Done!" is output.
+"""
+
+python_bash_patch_tool = {
+  "type": "function",
+  "name": "python",
+  "description": PYTHON_TOOL_DESCRIPTION,
+  "parameters": {
+      "type": "object",
+      "strict": True,
+      "properties": {
+          "input": {
+              "type": "string",
+              "description": " The Python code, terminal command (prefaced by exclamation mark), or apply_patch command that you wish to execute.",
+          }
+      },
+      "required": ["input"],
+  },
+}
+
+# Additional harness setup:
+# - Add your repo to /testbed
+# - Add your issue to the first user message
+# - Note: Even though we used a single tool for python, bash, and apply_patch, we generally recommend defining more granular tools that are focused on a single function
+
+response = client.responses.create(
+    instructions=SYS_PROMPT_SWEBENCH,
+    model="gpt-4.1-2025-04-14",
+    tools=[python_bash_patch_tool],
+    input=f"Please answer the following question:\nBug: Typerror..."
+)
+
+response.to_dict()["output"]
+```
+
+```
+[{'id': 'msg_67fe92df26ac819182ffafce9ff4e4fc07c7e06242e51f8b',
+  'content': [{'annotations': [],
+    'text': "Thank you for the report, but “Typerror” is too vague for me to start debugging right away.\n\n**To make progress, I need to:**\n1. Find the exact error message text (e.g. `'TypeError: ...'`).\n2. Find which file and which line/function/class the error occurred in.\n3. Figure out what triggered the error (test file, usage, reproduction steps).\n4. Find the root cause and details.\n\n**Next steps:**\n- Investigate error/log/test output files for a Python `TypeError` message.\n- Examine the relevant code sections for problematic type usage.\n- If possible, reproduce the bug locally.\n\n**Plan:**\n- First, I will search for test files and log output in the `/testbed` directory that may contain the full error message and stack trace.\n\nLet’s start by listing the contents of the `/testbed` directory to look for clues.",
+    'type': 'output_text'}],
+  'role': 'assistant',
+  'status': 'completed',
+  'type': 'message'},
+ {'arguments': '{"input":"!ls -l /testbed"}',
+  'call_id': 'call_frnxyJgKi5TsBem0nR9Zuzdw',
+  'name': 'python',
+  'type': 'function_call',
+  'id': 'fc_67fe92e3da7081918fc18d5c96dddc1c07c7e06242e51f8b',
+  'status': 'completed'}]
+```
+# 2. Long context
+GPT-4.1 has a performant 1M token input context window, and is useful for a variety of long context tasks, including structured document parsing, re-ranking, selecting relevant information while ignoring irrelevant context, and performing multi-hop reasoning using context.
+
+
+## Optimal Context Size
+We observe very good performance on needle-in-a-haystack evaluations up to our full 1M token context, and we’ve observed very strong performance at complex tasks with a mix of both relevant and irrelevant code and other documents. However, long context performance can degrade as more items are required to be retrieved, or perform complex reasoning that requires knowledge of the state of the entire context (like performing a graph search, for example).
+
+## Tuning Context Reliance
+
+Consider the mix of external vs. internal world knowledge that might be required to answer your question. Sometimes it’s important for the model to use some of its own knowledge to connect concepts or make logical jumps, while in others it’s desirable to only use provided context
+
+```
+# Instructions
+// for internal knowledge
+- Only use the documents in the provided External Context to answer the User Query. If you don't know the answer based on this context, you must respond "I don't have the information needed to answer that", even if a user insists on you answering the question.
+// For internal and external knowledge
+- By default, use the provided external context to answer the User Query, but if other basic knowledge is needed to answer, and you're confident in the answer, you can use some of your own knowledge to help answer the question.
+```
+## Prompt Organization
+
+Especially in long context usage, placement of instructions and context can impact performance. If you have long context in your prompt, ideally place your instructions at both the beginning and end of the provided context, as we found this to perform better than only above or below. If you’d prefer to only have your instructions once, then above the provided context works better than below.
+# 3. Chain of Thought
+
+As mentioned above, GPT-4.1 is not a reasoning model, but prompting the model to think step by step (called “chain of thought”) can be an effective way for a model to break down problems into more manageable pieces, solve them, and improve overall output quality, with the tradeoff of higher cost and latency associated with using more output tokens. The model has been trained to perform well at agentic reasoning about and real-world problem solving, so it shouldn’t require much prompting to perform well.
+
+We recommend starting with this basic chain-of-thought instruction at the end of your prompt:
+```
+...
+
+First, think carefully step by step about what documents are needed to answer the query. Then, print out the TITLE and ID of each document. Then, format the IDs into a list.
+```
+From there, you should improve your chain-of-thought (CoT) prompt by auditing failures in your particular examples and evals, and addressing systematic planning and reasoning errors with more explicit instructions. In the unconstrained CoT prompt, there may be variance in the strategies it tries, and if you observe an approach that works well, you can codify that strategy in your prompt. Generally speaking, errors tend to occur from misunderstanding user intent, insufficient context gathering or analysis, or insufficient or incorrect step by step thinking, so watch out for these and try to address them with more opinionated instructions.
+
+Here is an example prompt instructing the model to focus more methodically on analyzing user intent and considering relevant context before proceeding to answer.
+```
+# Reasoning Strategy
+1. Query Analysis: Break down and analyze the query until you're confident about what it might be asking. Consider the provided context to help clarify any ambiguous or confusing information.
+2. Context Analysis: Carefully select and analyze a large set of potentially relevant documents. Optimize for recall - it's okay if some are irrelevant, but the correct documents must be in this list, otherwise your final answer will be wrong. Analysis steps for each:
+	a. Analysis: An analysis of how it may or may not be relevant to answering the query.
+	b. Relevance rating: [high, medium, low, none]
+3. Synthesis: summarize which documents are most relevant and why, including all documents with a relevance rating of medium or higher.
+
+# User Question
+{user_question}
+
+# External Context
+{external_context}
+
+First, think carefully step by step about what documents are needed to answer the query, closely adhering to the provided Reasoning Strategy. Then, print out the TITLE and ID of each document. Then, format the IDs into a list.
+```
+# 4. Instruction Following
+
+GPT-4.1 exhibits outstanding instruction-following performance, which developers can leverage to precisely shape and control the outputs for their particular use cases. Developers often extensively prompt for agentic reasoning steps, response tone and voice, tool calling information, output formatting, topics to avoid, and more. However, since the model follows instructions more literally, developers may need to include explicit specification around what to do or not to do. Furthermore, existing prompts optimized for other models may not immediately work with this model, because existing instructions are followed more closely and implicit rules are no longer being as strongly inferred.
+## Recommended Workflow
+
+Here is our recommended workflow for developing and debugging instructions in prompts:
+
+    Start with an overall “Response Rules” or “Instructions” section with high-level guidance and bullet points.
+    If you’d like to change a more specific behavior, add a section to specify more details for that category, like # Sample Phrases.
+    If there are specific steps you’d like the model to follow in its workflow, add an ordered list and instruct the model to follow these steps.
+    If behavior still isn’t working as expected:
+        Check for conflicting, underspecified, or wrong instructions and examples. If there are conflicting instructions, GPT-4.1 tends to follow the one closer to the end of the prompt.
+        Add examples that demonstrate desired behavior; ensure that any important behavior demonstrated in your examples are also cited in your rules.
+        It’s generally not necessary to use all-caps or other incentives like bribes or tips. We recommend starting without these, and only reaching for these if necessary for your particular prompt. Note that if your existing prompts include these techniques, it could cause GPT-4.1 to pay attention to it too strictly.
+
+Note that using your preferred AI-powered IDE can be very helpful for iterating on prompts, including checking for consistency or conflicts, adding examples, or making cohesive updates like adding an instruction and updating instructions to demonstrate that instruction.
+## Common Failure Modes
+
+These failure modes are not unique to GPT-4.1, but we share them here for general awareness and ease of debugging.
+
+    Instructing a model to always follow a specific behavior can occasionally induce adverse effects. For instance, if told “you must call a tool before responding to the user,” models may hallucinate tool inputs or call the tool with null values if they do not have enough information. Adding “if you don’t have enough information to call the tool, ask the user for the information you need” should mitigate this.
+    When provided sample phrases, models can use those quotes verbatim and start to sound repetitive to users. Ensure you instruct the model to vary them as necessary.
+    Without specific instructions, some models can be eager to provide additional prose to explain their decisions, or output more formatting in responses than may be desired. Provide instructions and potentially examples to help mitigate.
+
+## Example Prompt: Customer Service
+
+This demonstrates best practices for a fictional customer service agent. Observe the diversity of rules, the specificity, the use of additional sections for greater detail, and an example to demonstrate precise behavior that incorporates all prior rules.
+
+Try running the following notebook cell - you should see both a user message and tool call, and the user message should start with a greeting, then echo back their answer, then mention they're about to call a tool. Try changing the instructions to shape the model behavior, or trying other user messages, to test instruction following performance.
+```python
+SYS_PROMPT_CUSTOMER_SERVICE = """You are a helpful customer service agent working for NewTelco, helping a user efficiently fulfill their request while adhering closely to provided guidelines.
+
+# Instructions
+- Always greet the user with "Hi, you've reached NewTelco, how can I help you?"
+- Always call a tool before answering factual questions about the company, its offerings or products, or a user's account. Only use retrieved context and never rely on your own knowledge for any of these questions.
+    - However, if you don't have enough information to properly call the tool, ask the user for the information you need.
+- Escalate to a human if the user requests.
+- Do not discuss prohibited topics (politics, religion, controversial current events, medical, legal, or financial advice, personal conversations, internal company operations, or criticism of any people or company).
+- Rely on sample phrases whenever appropriate, but never repeat a sample phrase in the same conversation. Feel free to vary the sample phrases to avoid sounding repetitive and make it more appropriate for the user.
+- Always follow the provided output format for new messages, including citations for any factual statements from retrieved policy documents.
+- If you're going to call a tool, always message the user with an appropriate message before and after calling the tool.
+- Maintain a professional and concise tone in all responses, and use emojis between sentences.
+- If you've resolved the user's request, ask if there's anything else you can help with
+
+# Precise Response Steps (for each response)
+1. If necessary, call tools to fulfill the user's desired action. Always message the user before and after calling a tool to keep them in the loop.
+2. In your response to the user
+    a. Use active listening and echo back what you heard the user ask for.
+    b. Respond appropriately given the above guidelines.
+
+# Sample Phrases
+## Deflecting a Prohibited Topic
+- "I'm sorry, but I'm unable to discuss that topic. Is there something else I can help you with?"
+- "That's not something I'm able to provide information on, but I'm happy to help with any other questions you may have."
+
+## Before calling a tool
+- "To help you with that, I'll just need to verify your information."
+- "Let me check that for you—one moment, please."
+- "I'll retrieve the latest details for you now."
+
+## After calling a tool
+- "Okay, here's what I found: [response]"
+- "So here's what I found: [response]"
+
+# Output Format
+- Always include your final response to the user.
+- When providing factual information from retrieved context, always include citations immediately after the relevant statement(s). Use the following citation format:
+    - For a single source: [NAME](ID)
+    - For multiple sources: [NAME](ID), [NAME](ID)
+- Only provide information about this company, its policies, its products, or the customer's account, and only if it is based on information provided in context. Do not answer questions outside this scope.
+
+# Example
+## User
+Can you tell me about your family plan options?
+
+## Assistant Response 1
+### Message
+"Hi, you've reached NewTelco, how can I help you? 😊🎉\n\nYou'd like to know about our family plan options. 🤝 Let me check that for you—one moment, please. 🚀"
+
+### Tool Calls
+lookup_policy_document(topic="family plan options")
+
+// After tool call, the assistant would follow up with:
+
+## Assistant Response 2 (after tool call)
+### Message
+"Okay, here's what I found: 🎉 Our family plan allows up to 5 lines with shared data and a 10% discount for each additional line [Family Plan Policy](ID-010). 📱 Is there anything else I can help you with today? 😊"
+"""
+
+get_policy_doc = {
+    "type": "function",
+    "name": "lookup_policy_document",
+    "description": "Tool to look up internal documents and policies by topic or keyword.",
+    "parameters": {
+        "strict": True,
+        "type": "object",
+        "properties": {
+            "topic": {
+                "type": "string",
+                "description": "The topic or keyword to search for in company policies or documents.",
+            },
+        },
+        "required": ["topic"],
+        "additionalProperties": False,
+    },
+}
+
+get_user_acct = {
+    "type": "function",
+    "name": "get_user_account_info",
+    "description": "Tool to get user account information",
+    "parameters": {
+        "strict": True,
+        "type": "object",
+        "properties": {
+            "phone_number": {
+                "type": "string",
+                "description": "Formatted as '(xxx) xxx-xxxx'",
+            },
+        },
+        "required": ["phone_number"],
+        "additionalProperties": False,
+    },
+}
+
+response = client.responses.create(
+    instructions=SYS_PROMPT_CUSTOMER_SERVICE,
+    model="gpt-4.1-2025-04-14",
+    tools=[get_policy_doc, get_user_acct],
+    input="How much will it cost for international service? I'm traveling to France.",
+    # input="Why was my last bill so high?"
+)
+
+response.to_dict()["output"]
+```
+```
+[{'id': 'msg_67fe92d431548191b7ca6cd604b4784b06efc5beb16b3c5e',
+  'content': [{'annotations': [],
+    'text': "Hi, you've reached NewTelco, how can I help you? 🌍✈️\n\nYou'd like to know the cost of international service while traveling to France. 🇫🇷 Let me check the latest details for you—one moment, please. 🕑",
+    'type': 'output_text'}],
+  'role': 'assistant',
+  'status': 'completed',
+  'type': 'message'},
+ {'arguments': '{"topic":"international service cost France"}',
+  'call_id': 'call_cF63DLeyhNhwfdyME3ZHd0yo',
+  'name': 'lookup_policy_document',
+  'type': 'function_call',
+  'id': 'fc_67fe92d5d6888191b6cd7cf57f707e4606efc5beb16b3c5e',
+  'status': 'completed'}]
+```
+# 5. General Advice
+## Prompt Structure
+
+For reference, here is a good starting point for structuring your prompts.
+```
+# Role and Objective
+
+# Instructions
+
+## Sub-categories for more detailed instructions
+
+# Reasoning Steps
+
+# Output Format
+
+# Examples
+## Example 1
+
+# Context
+
+# Final instructions and prompt to think step by step
+```
+Add or remove sections to suit your needs, and experiment to determine what’s optimal for your usage.
+Delimiters
+
+Here are some general guidelines for selecting the best delimiters for your prompt. Please refer to the Long Context section for special considerations for that context type.
+
+1. Markdown: We recommend starting here, and using markdown titles for major sections and subsections (including deeper hierarchy, to H4+). Use inline backticks or backtick blocks to precisely wrap code, and standard numbered or bulleted lists as needed.
+2. XML: These also perform well, and we have improved adherence to information in XML with this model. XML is convenient to precisely wrap a section including start and end, add metadata to the tags for additional context, and enable nesting. Here is an example of using XML tags to nest examples in an example section, with inputs and outputs for each:
+```
+<examples>
+<example1 type="Abbreviate">
+<input>San Francisco</input>
+<output>- SF</output>
+</example1>
+</examples>
+```
+3. JSON is highly structured and well understood by the model particularly in coding contexts. However it can be more verbose, and require character escaping that can add overhead.
+
+Guidance specifically for adding a large number of documents or files to input context:
+
+    XML performed well in our long context testing.
+        Example: <doc id='1' title='The Fox'>The quick brown fox jumps over the lazy dog</doc>
+    This format, proposed by Lee et al. (ref), also performed well in our long context testing.
+        Example: ID: 1 | TITLE: The Fox | CONTENT: The quick brown fox jumps over the lazy dog
+    JSON performed particularly poorly.
+        Example: [{'id': 1, 'title': 'The Fox', 'content': 'The quick brown fox jumped over the lazy dog'}]
+
+The model is trained to robustly understand structure in a variety of formats. Generally, use your judgement and think about what will provide clear information and “stand out” to the model. For example, if you’re retrieving documents that contain lots of XML, an XML-based delimiter will likely be less effective.
+## Caveats
+
+    In some isolated cases we have observed the model being resistant to producing very long, repetitive outputs, for example, analyzing hundreds of items one by one. If this is necessary for your use case, instruct the model strongly to output this information in full, and consider breaking down the problem or using a more concise approach.
+    We have seen some rare instances of parallel tool calls being incorrect. We advise testing this, and considering setting the parallel_tool_calls param to false if you’re seeing issues.
+
+# Appendix: Generating and Applying File Diffs
+
+Developers have provided us feedback that accurate and well-formed diff generation is a critical capability to power coding-related tasks. To this end, the GPT-4.1 family features substantially improved diff capabilities relative to previous GPT models. Moreover, while GPT-4.1 has strong performance generating diffs of any format given clear instructions and examples, we open-source here one recommended diff format, on which the model has been extensively trained. We hope that in particular for developers just starting out, that this will take much of the guesswork out of creating diffs yourself.
+Apply Patch
+
+See the example below for a prompt that applies our recommended tool call correctly.
+```python
+APPLY_PATCH_TOOL_DESC = """This is a custom utility that makes it more convenient to add, remove, move, or edit code files. `apply_patch` effectively allows you to execute a diff/patch against a file, but the format of the diff specification is unique to this task, so pay careful attention to these instructions. To use the `apply_patch` command, you should pass a message of the following structure as "input":
+
+%%bash
+apply_patch <<"EOF"
+*** Begin Patch
+[YOUR_PATCH]
+*** End Patch
+EOF
+
+Where [YOUR_PATCH] is the actual content of your patch, specified in the following V4A diff format.
+
+*** [ACTION] File: [path/to/file] -> ACTION can be one of Add, Update, or Delete.
+For each snippet of code that needs to be changed, repeat the following:
+[context_before] -> See below for further instructions on context.
+- [old_code] -> Precede the old code with a minus sign.
++ [new_code] -> Precede the new, replacement code with a plus sign.
+[context_after] -> See below for further instructions on context.
+
+For instructions on [context_before] and [context_after]:
+- By default, show 3 lines of code immediately above and 3 lines immediately below each change. If a change is within 3 lines of a previous change, do NOT duplicate the first change’s [context_after] lines in the second change’s [context_before] lines.
+- If 3 lines of context is insufficient to uniquely identify the snippet of code within the file, use the @@ operator to indicate the class or function to which the snippet belongs. For instance, we might have:
+@@ class BaseClass
+[3 lines of pre-context]
+- [old_code]
++ [new_code]
+[3 lines of post-context]
+
+- If a code block is repeated so many times in a class or function such that even a single @@ statement and 3 lines of context cannot uniquely identify the snippet of code, you can use multiple `@@` statements to jump to the right context. For instance:
+
+@@ class BaseClass
+@@ 	def method():
+[3 lines of pre-context]
+- [old_code]
++ [new_code]
+[3 lines of post-context]
+
+Note, then, that we do not use line numbers in this diff format, as the context is enough to uniquely identify code. An example of a message that you might pass as "input" to this function, in order to apply a patch, is shown below.
+
+%%bash
+apply_patch <<"EOF"
+*** Begin Patch
+*** Update File: pygorithm/searching/binary_search.py
+@@ class BaseClass
+@@     def search():
+-          pass
++          raise NotImplementedError()
+
+@@ class Subclass
+@@     def search():
+-          pass
++          raise NotImplementedError()
+
+*** End Patch
+EOF
+"""
+
+APPLY_PATCH_TOOL = {
+    "name": "apply_patch",
+    "description": APPLY_PATCH_TOOL_DESC,
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "input": {
+                "type": "string",
+                "description": " The apply_patch command that you wish to execute.",
+            }
+        },
+        "required": ["input"],
+    },
+}
+```
+## Reference Implementation: apply_patch.py
+
+Here’s a reference implementation of the apply_patch tool that we used as part of model training. You’ll need to make this an executable and available as `apply_patch` from the shell where the model will execute commands:
+```python
+#!/usr/bin/env python3
+
+"""
+A self-contained **pure-Python 3.9+** utility for applying human-readable
+“pseudo-diff” patch files to a collection of text files.
+"""
+
+from __future__ import annotations
+
+import pathlib
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import (
+    Callable,
+    Dict,
+    List,
+    Optional,
+    Tuple,
+    Union,
+)
+
+
+# --------------------------------------------------------------------------- #
+#  Domain objects
+# --------------------------------------------------------------------------- #
+class ActionType(str, Enum):
+    ADD = "add"
+    DELETE = "delete"
+    UPDATE = "update"
+
+
+@dataclass
+class FileChange:
+    type: ActionType
+    old_content: Optional[str] = None
+    new_content: Optional[str] = None
+    move_path: Optional[str] = None
+
+
+@dataclass
+class Commit:
+    changes: Dict[str, FileChange] = field(default_factory=dict)
+
+
+# --------------------------------------------------------------------------- #
+#  Exceptions
+# --------------------------------------------------------------------------- #
+class DiffError(ValueError):
+    """Any problem detected while parsing or applying a patch."""
+
+
+# --------------------------------------------------------------------------- #
+#  Helper dataclasses used while parsing patches
+# --------------------------------------------------------------------------- #
+@dataclass
+class Chunk:
+    orig_index: int = -1
+    del_lines: List[str] = field(default_factory=list)
+    ins_lines: List[str] = field(default_factory=list)
+
+
+@dataclass
+class PatchAction:
+    type: ActionType
+    new_file: Optional[str] = None
+    chunks: List[Chunk] = field(default_factory=list)
+    move_path: Optional[str] = None
+
+
+@dataclass
+class Patch:
+    actions: Dict[str, PatchAction] = field(default_factory=dict)
+
+
+# --------------------------------------------------------------------------- #
+#  Patch text parser
+# --------------------------------------------------------------------------- #
+@dataclass
+class Parser:
+    current_files: Dict[str, str]
+    lines: List[str]
+    index: int = 0
+    patch: Patch = field(default_factory=Patch)
+    fuzz: int = 0
+
+    # ------------- low-level helpers -------------------------------------- #
+    def _cur_line(self) -> str:
+        if self.index >= len(self.lines):
+            raise DiffError("Unexpected end of input while parsing patch")
+        return self.lines[self.index]
+
+    @staticmethod
+    def _norm(line: str) -> str:
+        """Strip CR so comparisons work for both LF and CRLF input."""
+        return line.rstrip("\r")
+
+    # ------------- scanning convenience ----------------------------------- #
+    def is_done(self, prefixes: Optional[Tuple[str, ...]] = None) -> bool:
+        if self.index >= len(self.lines):
+            return True
+        if (
+            prefixes
+            and len(prefixes) > 0
+            and self._norm(self._cur_line()).startswith(prefixes)
+        ):
+            return True
+        return False
+
+    def startswith(self, prefix: Union[str, Tuple[str, ...]]) -> bool:
+        return self._norm(self._cur_line()).startswith(prefix)
+
+    def read_str(self, prefix: str) -> str:
+        """
+        Consume the current line if it starts with *prefix* and return the text
+        **after** the prefix.  Raises if prefix is empty.
+        """
+        if prefix == "":
+            raise ValueError("read_str() requires a non-empty prefix")
+        if self._norm(self._cur_line()).startswith(prefix):
+            text = self._cur_line()[len(prefix) :]
+            self.index += 1
+            return text
+        return ""
+
+    def read_line(self) -> str:
+        """Return the current raw line and advance."""
+        line = self._cur_line()
+        self.index += 1
+        return line
+
+    # ------------- public entry point -------------------------------------- #
+    def parse(self) -> None:
+        while not self.is_done(("*** End Patch",)):
+            # ---------- UPDATE ---------- #
+            path = self.read_str("*** Update File: ")
+            if path:
+                if path in self.patch.actions:
+                    raise DiffError(f"Duplicate update for file: {path}")
+                move_to = self.read_str("*** Move to: ")
+                if path not in self.current_files:
+                    raise DiffError(f"Update File Error - missing file: {path}")
+                text = self.current_files[path]
+                action = self._parse_update_file(text)
+                action.move_path = move_to or None
+                self.patch.actions[path] = action
+                continue
+
+            # ---------- DELETE ---------- #
+            path = self.read_str("*** Delete File: ")
+            if path:
+                if path in self.patch.actions:
+                    raise DiffError(f"Duplicate delete for file: {path}")
+                if path not in self.current_files:
+                    raise DiffError(f"Delete File Error - missing file: {path}")
+                self.patch.actions[path] = PatchAction(type=ActionType.DELETE)
+                continue
+
+            # ---------- ADD ---------- #
+            path = self.read_str("*** Add File: ")
+            if path:
+                if path in self.patch.actions:
+                    raise DiffError(f"Duplicate add for file: {path}")
+                if path in self.current_files:
+                    raise DiffError(f"Add File Error - file already exists: {path}")
+                self.patch.actions[path] = self._parse_add_file()
+                continue
+
+            raise DiffError(f"Unknown line while parsing: {self._cur_line()}")
+
+        if not self.startswith("*** End Patch"):
+            raise DiffError("Missing *** End Patch sentinel")
+        self.index += 1  # consume sentinel
+
+    # ------------- section parsers ---------------------------------------- #
+    def _parse_update_file(self, text: str) -> PatchAction:
+        action = PatchAction(type=ActionType.UPDATE)
+        lines = text.split("\n")
+        index = 0
+        while not self.is_done(
+            (
+                "*** End Patch",
+                "*** Update File:",
+                "*** Delete File:",
+                "*** Add File:",
+                "*** End of File",
+            )
+        ):
+            def_str = self.read_str("@@ ")
+            section_str = ""
+            if not def_str and self._norm(self._cur_line()) == "@@":
+                section_str = self.read_line()
+
+            if not (def_str or section_str or index == 0):
+                raise DiffError(f"Invalid line in update section:\n{self._cur_line()}")
+
+            if def_str.strip():
+                found = False
+                if def_str not in lines[:index]:
+                    for i, s in enumerate(lines[index:], index):
+                        if s == def_str:
+                            index = i + 1
+                            found = True
+                            break
+                if not found and def_str.strip() not in [
+                    s.strip() for s in lines[:index]
+                ]:
+                    for i, s in enumerate(lines[index:], index):
+                        if s.strip() == def_str.strip():
+                            index = i + 1
+                            self.fuzz += 1
+                            found = True
+                            break
+
+            next_ctx, chunks, end_idx, eof = peek_next_section(self.lines, self.index)
+            new_index, fuzz = find_context(lines, next_ctx, index, eof)
+            if new_index == -1:
+                ctx_txt = "\n".join(next_ctx)
+                raise DiffError(
+                    f"Invalid {'EOF ' if eof else ''}context at {index}:\n{ctx_txt}"
+                )
+            self.fuzz += fuzz
+            for ch in chunks:
+                ch.orig_index += new_index
+                action.chunks.append(ch)
+            index = new_index + len(next_ctx)
+            self.index = end_idx
+        return action
+
+    def _parse_add_file(self) -> PatchAction:
+        lines: List[str] = []
+        while not self.is_done(
+            ("*** End Patch", "*** Update File:", "*** Delete File:", "*** Add File:")
+        ):
+            s = self.read_line()
+            if not s.startswith("+"):
+                raise DiffError(f"Invalid Add File line (missing '+'): {s}")
+            lines.append(s[1:])  # strip leading '+'
+        return PatchAction(type=ActionType.ADD, new_file="\n".join(lines))
+
+
+# --------------------------------------------------------------------------- #
+#  Helper functions
+# --------------------------------------------------------------------------- #
+def find_context_core(
+    lines: List[str], context: List[str], start: int
+) -> Tuple[int, int]:
+    if not context:
+        return start, 0
+
+    for i in range(start, len(lines)):
+        if lines[i : i + len(context)] == context:
+            return i, 0
+    for i in range(start, len(lines)):
+        if [s.rstrip() for s in lines[i : i + len(context)]] == [
+            s.rstrip() for s in context
+        ]:
+            return i, 1
+    for i in range(start, len(lines)):
+        if [s.strip() for s in lines[i : i + len(context)]] == [
+            s.strip() for s in context
+        ]:
+            return i, 100
+    return -1, 0
+
+
+def find_context(
+    lines: List[str], context: List[str], start: int, eof: bool
+) -> Tuple[int, int]:
+    if eof:
+        new_index, fuzz = find_context_core(lines, context, len(lines) - len(context))
+        if new_index != -1:
+            return new_index, fuzz
+        new_index, fuzz = find_context_core(lines, context, start)
+        return new_index, fuzz + 10_000
+    return find_context_core(lines, context, start)
+
+
+def peek_next_section(
+    lines: List[str], index: int
+) -> Tuple[List[str], List[Chunk], int, bool]:
+    old: List[str] = []
+    del_lines: List[str] = []
+    ins_lines: List[str] = []
+    chunks: List[Chunk] = []
+    mode = "keep"
+    orig_index = index
+
+    while index < len(lines):
+        s = lines[index]
+        if s.startswith(
+            (
+                "@@",
+                "*** End Patch",
+                "*** Update File:",
+                "*** Delete File:",
+                "*** Add File:",
+                "*** End of File",
+            )
+        ):
+            break
+        if s == "***":
+            break
+        if s.startswith("***"):
+            raise DiffError(f"Invalid Line: {s}")
+        index += 1
+
+        last_mode = mode
+        if s == "":
+            s = " "
+        if s[0] == "+":
+            mode = "add"
+        elif s[0] == "-":
+            mode = "delete"
+        elif s[0] == " ":
+            mode = "keep"
+        else:
+            raise DiffError(f"Invalid Line: {s}")
+        s = s[1:]
+
+        if mode == "keep" and last_mode != mode:
+            if ins_lines or del_lines:
+                chunks.append(
+                    Chunk(
+                        orig_index=len(old) - len(del_lines),
+                        del_lines=del_lines,
+                        ins_lines=ins_lines,
+                    )
+                )
+            del_lines, ins_lines = [], []
+
+        if mode == "delete":
+            del_lines.append(s)
+            old.append(s)
+        elif mode == "add":
+            ins_lines.append(s)
+        elif mode == "keep":
+            old.append(s)
+
+    if ins_lines or del_lines:
+        chunks.append(
+            Chunk(
+                orig_index=len(old) - len(del_lines),
+                del_lines=del_lines,
+                ins_lines=ins_lines,
+            )
+        )
+
+    if index < len(lines) and lines[index] == "*** End of File":
+        index += 1
+        return old, chunks, index, True
+
+    if index == orig_index:
+        raise DiffError("Nothing in this section")
+    return old, chunks, index, False
+
+
+# --------------------------------------------------------------------------- #
+#  Patch → Commit and Commit application
+# --------------------------------------------------------------------------- #
+def _get_updated_file(text: str, action: PatchAction, path: str) -> str:
+    if action.type is not ActionType.UPDATE:
+        raise DiffError("_get_updated_file called with non-update action")
+    orig_lines = text.split("\n")
+    dest_lines: List[str] = []
+    orig_index = 0
+
+    for chunk in action.chunks:
+        if chunk.orig_index > len(orig_lines):
+            raise DiffError(
+                f"{path}: chunk.orig_index {chunk.orig_index} exceeds file length"
+            )
+        if orig_index > chunk.orig_index:
+            raise DiffError(
+                f"{path}: overlapping chunks at {orig_index} > {chunk.orig_index}"
+            )
+
+        dest_lines.extend(orig_lines[orig_index : chunk.orig_index])
+        orig_index = chunk.orig_index
+
+        dest_lines.extend(chunk.ins_lines)
+        orig_index += len(chunk.del_lines)
+
+    dest_lines.extend(orig_lines[orig_index:])
+    return "\n".join(dest_lines)
+
+
+def patch_to_commit(patch: Patch, orig: Dict[str, str]) -> Commit:
+    commit = Commit()
+    for path, action in patch.actions.items():
+        if action.type is ActionType.DELETE:
+            commit.changes[path] = FileChange(
+                type=ActionType.DELETE, old_content=orig[path]
+            )
+        elif action.type is ActionType.ADD:
+            if action.new_file is None:
+                raise DiffError("ADD action without file content")
+            commit.changes[path] = FileChange(
+                type=ActionType.ADD, new_content=action.new_file
+            )
+        elif action.type is ActionType.UPDATE:
+            new_content = _get_updated_file(orig[path], action, path)
+            commit.changes[path] = FileChange(
+                type=ActionType.UPDATE,
+                old_content=orig[path],
+                new_content=new_content,
+                move_path=action.move_path,
+            )
+    return commit
+
+
+# --------------------------------------------------------------------------- #
+#  User-facing helpers
+# --------------------------------------------------------------------------- #
+def text_to_patch(text: str, orig: Dict[str, str]) -> Tuple[Patch, int]:
+    lines = text.splitlines()  # preserves blank lines, no strip()
+    if (
+        len(lines) < 2
+        or not Parser._norm(lines[0]).startswith("*** Begin Patch")
+        or Parser._norm(lines[-1]) != "*** End Patch"
+    ):
+        raise DiffError("Invalid patch text - missing sentinels")
+
+    parser = Parser(current_files=orig, lines=lines, index=1)
+    parser.parse()
+    return parser.patch, parser.fuzz
+
+
+def identify_files_needed(text: str) -> List[str]:
+    lines = text.splitlines()
+    return [
+        line[len("*** Update File: ") :]
+        for line in lines
+        if line.startswith("*** Update File: ")
+    ] + [
+        line[len("*** Delete File: ") :]
+        for line in lines
+        if line.startswith("*** Delete File: ")
+    ]
+
+
+def identify_files_added(text: str) -> List[str]:
+    lines = text.splitlines()
+    return [
+        line[len("*** Add File: ") :]
+        for line in lines
+        if line.startswith("*** Add File: ")
+    ]
+
+
+# --------------------------------------------------------------------------- #
+#  File-system helpers
+# --------------------------------------------------------------------------- #
+def load_files(paths: List[str], open_fn: Callable[[str], str]) -> Dict[str, str]:
+    return {path: open_fn(path) for path in paths}
+
+
+def apply_commit(
+    commit: Commit,
+    write_fn: Callable[[str, str], None],
+    remove_fn: Callable[[str], None],
+) -> None:
+    for path, change in commit.changes.items():
+        if change.type is ActionType.DELETE:
+            remove_fn(path)
+        elif change.type is ActionType.ADD:
+            if change.new_content is None:
+                raise DiffError(f"ADD change for {path} has no content")
+            write_fn(path, change.new_content)
+        elif change.type is ActionType.UPDATE:
+            if change.new_content is None:
+                raise DiffError(f"UPDATE change for {path} has no new content")
+            target = change.move_path or path
+            write_fn(target, change.new_content)
+            if change.move_path:
+                remove_fn(path)
+
+
+def process_patch(
+    text: str,
+    open_fn: Callable[[str], str],
+    write_fn: Callable[[str, str], None],
+    remove_fn: Callable[[str], None],
+) -> str:
+    if not text.startswith("*** Begin Patch"):
+        raise DiffError("Patch text must start with *** Begin Patch")
+    paths = identify_files_needed(text)
+    orig = load_files(paths, open_fn)
+    patch, _fuzz = text_to_patch(text, orig)
+    commit = patch_to_commit(patch, orig)
+    apply_commit(commit, write_fn, remove_fn)
+    return "Done!"
+
+
+# --------------------------------------------------------------------------- #
+#  Default FS helpers
+# --------------------------------------------------------------------------- #
+def open_file(path: str) -> str:
+    with open(path, "rt", encoding="utf-8") as fh:
+        return fh.read()
+
+
+def write_file(path: str, content: str) -> None:
+    target = pathlib.Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with target.open("wt", encoding="utf-8") as fh:
+        fh.write(content)
+
+
+def remove_file(path: str) -> None:
+    pathlib.Path(path).unlink(missing_ok=True)
+
+
+# --------------------------------------------------------------------------- #
+#  CLI entry-point
+# --------------------------------------------------------------------------- #
+def main() -> None:
+    import sys
+
+    patch_text = sys.stdin.read()
+    if not patch_text:
+        print("Please pass patch text through stdin", file=sys.stderr)
+        return
+    try:
+        result = process_patch(patch_text, open_file, write_file, remove_file)
+    except DiffError as exc:
+        print(exc, file=sys.stderr)
+        return
+    print(result)
+
+
+if __name__ == "__main__":
+    main()
+```
+Other Effective Diff Formats
+
+If you want to try using a different diff format, we found in testing that the SEARCH/REPLACE diff format used in Aider’s polyglot benchmark, as well as a pseudo-XML format with no internal escaping, both had high success rates.
+
+These diff formats share two key aspects: (1) they do not use line numbers, and (2) they provide both the exact code to be replaced, and the exact code with which to replace it, with clear delimiters between the two.
+```python
+SEARCH_REPLACE_DIFF_EXAMPLE = """
+path/to/file.py
+
+>>>>>>> SEARCH
+def search():
+    pass
+=======
+def search():
+   raise NotImplementedError()
+<<<<<<< REPLACE
+"""
+
+PSEUDO_XML_DIFF_EXAMPLE = """
+<edit>
+<file>
+path/to/file.py
+</file>
+<old_code>
+def search():
+    pass
+</old_code>
+<new_code>
+def search():
+   raise NotImplementedError()
+</new_code>
+</edit>
+"""
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ghchris2021
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,234 @@
+# [OpenAI Cookbook Pro](https://chatgpt.com/canvas/shared/6825e9f6e8d88191bf9ef4de00b29b0f)
+### Developer Tools: [Universal Runtime](https://github.com/davidkimai/universal-runtime) | [Universal Developer](https://github.com/davidkimai/universal-developer)
+
+**An Advanced Implementation Guide to GPT-4.1: Real-World Applications, Prompting Strategies, and Agent Workflows**
+
+Welcome to **OpenAI Cookbook Pro** — a comprehensive, practical, and fully extensible resource tailored for engineers, developers, and researchers working with the GPT-4.1 API and related OpenAI tools. This repository distills best practices, integrates field-tested strategies, and supports high-performing workflows with enhanced reliability, precision, and developer autonomy.
+
+> If you're familiar with the original OpenAI Cookbook, think of this project as an expanded version designed for production-grade deployments, advanced prompt development, tool integration, and agent design.
+
+
+## 🔧 What This Cookbook Offers
+
+* **Structured examples** of effective prompting for instruction following, planning, tool usage, and dynamic interactions.
+* **Agent design frameworks** built around persistent task completion and context-aware iteration.
+* **Tool integration patterns** using OpenAI's native tool-calling API — optimized for accuracy and reliability.
+* **Custom workflows** for coding tasks, debugging, testing, and patch management.
+* **Long-context strategies** including prompt shaping, content selection, and information compression for up to 1M tokens.
+* **Production-aligned system prompts** for customer service, support bots, and autonomous coding agents.
+
+Whether you're building an agent to manage codebases or optimizing a high-context knowledge retrieval system, the examples here aim to be direct, reproducible, and extensible.
+
+
+## 📘 Table of Contents
+
+1. [Getting Started](#getting-started)
+2. [Prompting for Instruction Following](#prompting-for-instruction-following)
+3. [Designing Agent Workflows](#designing-agent-workflows)
+4. [Tool Use and Integration](#tool-use-and-integration)
+5. [Chain of Thought and Planning](#chain-of-thought-and-planning)
+6. [Handling Long Contexts](#handling-long-contexts)
+7. [Code Fixing and Diff Management](#code-fixing-and-diff-management)
+8. [Real-World Deployment Scenarios](#real-world-deployment-scenarios)
+9. [Prompt Engineering Reference Guide](#prompt-engineering-reference-guide)
+10. [API Usage Examples](#api-usage-examples)
+
+
+## Getting Started
+
+OpenAI Cookbook Pro assumes a basic working knowledge of OpenAI’s Python SDK, the GPT-4.1 API, and how to use the `functions`, `tools`, and `system prompt` fields.
+
+If you're new to OpenAI's tools, start here:
+
+* [OpenAI Platform Documentation](https://platform.openai.com/docs)
+* [Original OpenAI Cookbook](https://github.com/openai/openai-cookbook)
+
+This project builds on those foundations, layering in advanced workflows and reproducible examples for:
+
+* Task persistence
+* Iterative debugging
+* Prompt shaping and behavior targeting
+* Multi-step tool planning
+
+
+## Prompting for Instruction Following
+
+GPT-4.1’s instruction-following capabilities have been significantly improved. To ensure the model performs consistently:
+
+* Be explicit. Literal instruction following means subtle ambiguities may derail output.
+* Use clear formatting for instruction sets (Markdown, XML, or numbered lists).
+* Place instructions **at both the top and bottom** of long prompts if the context window exceeds 100K tokens.
+
+### Example: Instruction Template
+
+```markdown
+# Instructions
+1. Read the user’s message carefully.
+2. Do not generate a response until you've gathered all needed context.
+3. Use a tool if more information is required.
+4. Only respond when you can complete the request correctly.
+```
+
+> See `/examples/instruction-following.md` for more variations and system prompt styles.
+
+
+## Designing Agent Workflows
+
+GPT-4.1 supports agentic workflows that require multi-step planning, tool usage, and long turn durations. Designing effective agents starts with a disciplined structure:
+
+### Include Three System Prompt Anchors:
+
+* **Persistence**: Emphasize that the model should continue until task completion.
+* **Tool usage**: Make it clear that it must use tools if it lacks context.
+* **Planning**: Encourage the model to write out plans and reflect after each action.
+
+See `/agent_design/swe_bench_agent.md` for a complete agent example that solves live bugs in open-source repositories.
+
+
+## Tool Use and Integration
+
+Leverage the `tools` parameter in OpenAI's API to define functional calls. Avoid embedding tool descriptions in prompts — the model performs better when tools are registered explicitly.
+
+### Tool Guidelines
+
+* Name your tools clearly.
+* Keep descriptions concise but specific.
+* Provide optional examples in a dedicated `# Examples` section.
+
+> Tool-based prompting increases reliability, reduces hallucinations, and helps maintain output consistency.
+
+
+## Chain of Thought and Planning
+
+While GPT-4.1 does not inherently perform internal reasoning, it can be prompted to **think out loud**:
+
+```markdown
+First, identify what documents may be relevant. Then list their titles and relevance. Finally, provide a list of IDs sorted by importance.
+```
+
+Use structured strategies to enforce planning:
+
+1. Break down the query.
+2. Retrieve and assess context.
+3. Prioritize response steps.
+4. Deliver a refined output.
+
+> See `/prompting/chain_of_thought.md` for templates and performance impact.
+
+
+## Handling Long Contexts
+
+GPT-4.1 supports up to **1 million tokens**. To manage this effectively:
+
+* Use structure: XML or markdown sections help the model parse relevance.
+* Repeat critical instructions **at the top and bottom** of your prompt.
+* Scope responses by separating external context from user queries.
+
+### Example Format
+
+```xml
+<instructions>
+Only answer based on External Context. Do not make assumptions.
+</instructions>
+<user_query>
+How does the billing policy apply to usage overages?
+</user_query>
+<context>
+<doc id="12" title="Billing Policy">
+[...]
+</doc>
+</context>
+```
+
+> See `/examples/long-context-formatting.md` for formatting guidance.
+
+
+## Code Fixing and Diff Management
+
+GPT-4.1 includes support for a **tool-compatible diff format** that enables:
+
+* Patch generation
+* File updates
+* Inline modifications with full context
+
+Use the `apply_patch` tool with the recommended V4A diff format. Always:
+
+* Use clear before/after code snippets
+* Avoid relying on line numbers
+* Use `@@` markers to indicate scope
+
+> See `/tools/apply_patch_examples/` for real-world patch workflows.
+
+
+## Real-World Deployment Scenarios
+
+### Use Cases
+
+* **Support automation** using grounded answers and clear tool policies
+* **Code refactoring bots** that operate on large repositories
+* **Document summarization** across thousands of pages
+* **High-integrity report generation** from structured prompt templates
+
+Each scenario includes:
+
+* Prompt formats
+* Tool definitions
+* Behavior checks
+
+> Explore the `/scenarios/` folder for ready-to-run templates.
+
+
+## Prompt Engineering Reference Guide
+
+A distilled reference for designing robust prompts across various tasks.
+
+### Sections:
+
+* General prompt structures
+* Common failure patterns
+* Formatting styles (Markdown, XML, JSON)
+* Long-context techniques
+* Instruction conflict resolution
+
+> Found in `/reference/prompting_guide.md`
+
+
+## API Usage Examples
+
+Includes starter scripts and walkthroughs for:
+
+* Tool registration
+* Chat prompt design
+* Instruction tuning
+* Streaming outputs
+
+All examples use official OpenAI SDK patterns and can be run locally.
+
+
+## Contributing
+
+We welcome contributions that:
+
+* Improve clarity
+* Extend agent workflows
+* Add new prompt techniques
+* Introduce tool examples
+
+To contribute:
+
+1. Fork the repo
+2. Create a new folder under `/examples` or `/tools`
+3. Submit a PR with a brief description of your addition
+
+
+## License
+
+This project is released under the MIT License.
+
+
+## Acknowledgments
+
+This repository builds upon the foundational work of the original [OpenAI Cookbook](https://github.com/openai/openai-cookbook). All strategies are derived from real-world testing, usage analysis, and OpenAI’s 4.1 Prompting Guide (April 2025).
+
+
+For support or suggestions, feel free to open an issue or connect via [OpenAI Developer Forum](https://community.openai.com).

api_usage.md

@@ -0,0 +1,326 @@
+# [API Usage Examples with GPT-4.1](https://chatgpt.com/canvas/shared/6825f96694a48191af7648cad2996158)
+
+## Overview
+
+This guide provides detailed, real-world examples of using the OpenAI GPT-4.1 API effectively, with a focus on instruction-following, tool integration, agent persistence, and prompt structuring. These examples are designed to help developers and engineers build resilient, production-ready systems using GPT-4.1 across various applications, including customer service, bug fixing, document analysis, and data labeling.
+
+Each example illustrates system prompt construction, tool schema definitions, interaction workflows, and failure mitigation strategies.
+
+
+
+## Example 1: Customer Support Agent with Tool Use
+
+### Objective
+
+Deploy a GPT-4.1 assistant to handle user questions about policies and account status.
+
+### System Prompt
+
+```markdown
+You are a helpful assistant for NewTelco. Your job is to assist users with account and policy information.
+
+# Instructions
+- Always greet the user.
+- Use tools to retrieve account and policy information.
+- If needed data is missing, ask the user before calling tools.
+- Avoid internal knowledge on restricted topics.
+
+# Workflow
+1. Identify intent
+2. Call tools if sufficient input
+3. Message user before and after tool calls
+4. Cite results
+```
+
+### Tools
+
+```json
+[
+  {
+    "name": "lookup_policy_document",
+    "description": "Searches internal docs by topic",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "topic": {"type": "string"}
+      },
+      "required": ["topic"]
+    }
+  },
+  {
+    "name": "get_user_account_info",
+    "description": "Retrieves account details using phone number",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "phone_number": {"type": "string"}
+      },
+      "required": ["phone_number"]
+    }
+  }
+]
+```
+
+### User Input
+
+```text
+How much will it cost for international service in France?
+```
+
+### Assistant Output
+
+```text
+Hi, you've reached NewTelco, how can I help you? 🌍✈️
+
+You're asking about international service while traveling to France. Let me check that for you — one moment, please. 🕑
+```
+
+### Tool Call
+
+```json
+{
+  "name": "lookup_policy_document",
+  "arguments": {"topic": "international service cost France"}
+}
+```
+
+
+
+## Example 2: Software Bug Fix Agent with Diff Application
+
+### Objective
+
+Use GPT-4.1 to investigate and fix a bug in a codebase using the `apply_patch` tool.
+
+### System Prompt Highlights
+
+```markdown
+# Objective
+Fix the issue provided by the user.
+
+# Instructions
+- Plan each step
+- Reflect after each function call
+- Never guess code — read it first using tools
+- Only stop when all tests pass
+
+# Workflow
+1. Understand issue deeply
+2. Investigate codebase
+3. Draft patch
+4. Apply patch
+5. Run tests
+6. Reflect and finalize
+```
+
+### Tool Definition
+
+```json
+{
+  "name": "python",
+  "description": "Execute code or apply a patch",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "input": {"type": "string"}
+    },
+    "required": ["input"]
+  }
+}
+```
+
+### Tool Call Example
+
+```bash
+%%bash
+apply_patch <<"EOF"
+*** Begin Patch
+*** Update File: src/core.py
+@@ def is_valid():
+-    return False
++    return True
+*** End Patch
+EOF
+```
+
+### Test Execution
+
+```json
+{
+  "name": "python",
+  "arguments": {"input": "!python3 run_tests.py"}
+}
+```
+
+
+
+## Example 3: Long-Context Document Analyzer
+
+### Objective
+
+Summarize and extract insights from up to 1M tokens of context.
+
+### Prompt Sections
+
+```markdown
+# Instructions
+- Process documents in 10k token blocks
+- Reflect after each segment
+- Label relevance and extract core ideas
+
+# Strategy
+1. Read → summarize
+2. Score relevance
+3. Synthesize into unified output
+```
+
+### Input Format
+
+```xml
+<doc id="21" title="Policy Update">
+<summary>Changes to international billing rules</summary>
+<content>...</content>
+</doc>
+```
+
+### Assistant Behavior
+
+* Chunk input into 10k token sections
+* After each, provide a summary and document scores
+* Compile findings at end
+
+
+
+## Example 4: Data Labeling Assistant
+
+### Objective
+
+Assist with structured classification tasks.
+
+### Prompt Template
+
+```markdown
+# Instructions
+- Label each entry using the provided schema
+- Do not guess; if unsure, flag for human
+
+# Labeling Categories
+- Urgent
+- Normal
+- Spam
+
+# Output Format
+{"text": ..., "label": ...}
+
+# Example
+{"text": "Win money now!", "label": "Spam"}
+```
+
+### User Input
+
+```json
+[
+  "New system update available",
+  "Limited time offer! Click now",
+  "Server crashed, need help ASAP"
+]
+```
+
+### Assistant Output
+
+```json
+[
+  {"text": "New system update available", "label": "Normal"},
+  {"text": "Limited time offer! Click now", "label": "Spam"},
+  {"text": "Server crashed, need help ASAP", "label": "Urgent"}
+]
+```
+
+
+
+## Example 5: Chain-of-Thought for Multi-Hop Reasoning
+
+### Objective
+
+Support a planning task by explicitly breaking down the steps.
+
+### Prompt Template
+
+```markdown
+# Instructions
+First, think carefully step by step. Then output the result.
+
+# Reasoning Strategy
+1. Identify user question
+2. Extract context
+3. Connect information across documents
+4. Output answer
+```
+
+### Example Input
+
+```markdown
+# User Question
+How did the billing policy change after 2022?
+
+# Context
+<doc id="10" title="Policy 2022">...</doc>
+<doc id="12" title="Policy 2023">...</doc>
+```
+
+### Model Output
+
+```text
+Step 1: Identify relevant documents → IDs 10, 12
+Step 2: Compare clauses
+Step 3: 2022 had flat rates, 2023 added time-of-use billing
+Answer: Billing policy changed to time-based pricing in 2023.
+```
+
+
+
+## General Prompt Formatting Guidelines
+
+### Preferred Structure
+
+```markdown
+# Role
+# Instructions
+# Workflow (optional)
+# Reasoning Strategy (optional)
+# Output Format
+# Examples (optional)
+```
+
+### Tool Use Reminders
+
+* Only call tools when sufficient information is available
+* Always notify the user before and after calls
+* Use example-triggered calls for teaching tool behavior
+
+### Output Patterns
+
+* JSON or markdown preferred
+* Cite source documents if used
+* Include fallback responses if uncertain (e.g., "Insufficient context")
+
+
+
+## Best Practices Summary
+
+| Element      | Best Practice                                 |
+| ------------ | --------------------------------------------- |
+| Tool Calls   | Always define schema with strong param names  |
+| Planning     | Enforce pre- and post-action reflection       |
+| Output       | Enforce format, validate JSON before response |
+| Long Context | Use structured delimiters (Markdown, XML)     |
+| Labeling     | Use few-shot examples and explicit categories |
+| Diff Format  | Use V4A patch format for code updates         |
+
+
+
+## Final Note
+
+These examples are starting templates. Each system will benefit from iterative refinements, structured logging, and real-world user testing. Maintain modular prompts and tool schemas, and adopt evaluation frameworks to monitor performance over time.
+
+**Clarity, structure, and instruction adherence are the cornerstones of production-grade GPT-4.1 API design.**

chain_of_thought_planning.md

@@ -0,0 +1,195 @@
+# [Chain of Thought and Planning in GPT-4.1](https://chatgpt.com/canvas/shared/6825f035f4b8819188e481e6e5cab29e)
+## Overview
+
+This document serves as a comprehensive and standalone guide for implementing effective chain-of-thought prompting and planning techniques with the OpenAI GPT-4.1 model family. It draws from official prompt engineering strategies outlined in the OpenAI 4.1 Cookbook and translates them into an accessible, implementation-ready format for developers, researchers, and product engineers.
+
+## Key Goals
+
+1. Enable step-by-step problem-solving via structured reasoning.
+2. Amplify agentic behavior in tool-using contexts.
+3. Minimize hallucinations by encouraging reflective planning.
+4. Improve task completion rates in software engineering and knowledge work.
+5. Align prompt design with model strengths in instruction-following and long-context awareness.
+
+## Core Principles
+
+### 1. Chain-of-Thought (CoT) Induction
+
+GPT-4.1 does not natively reason before answering; however, it can be prompted to simulate reasoning through structured instructions. This is known as "chain-of-thought prompting."
+
+**Prompting Template:**
+
+> "Before answering, think step by step about what’s needed to solve the task. Then begin executing."
+
+Chain-of-thought is especially effective when applied to:
+
+* Multi-hop reasoning questions
+* Complex analytical tasks
+* Document triage and synthesis
+* Code tracing and debugging
+
+### 2. Agentic Planning
+
+The model can be transformed into a more proactive, autonomous agent through three types of reminders:
+
+* **Persistence Reminder:** Encourages continuation across multiple turns.
+* **Tool-Use Reminder:** Discourages guessing; reinforces fact-finding.
+* **Planning Reminder:** Encourages step-by-step thinking before and after tool use.
+
+**Agentic Prompting Snippet:**
+
+```text
+You are an agent. Keep going until the query is fully resolved. Use tools instead of guessing. Plan your actions and reflect after each step.
+```
+
+This significantly increases model adherence to goals and improves results in complex domains like software engineering, particularly on structured benchmarks like SWE-bench Verified.
+
+### 3. Explicit Workflow Structuring
+
+Providing workflows as ordered lists increases adherence and performance. This creates a "mental model" the assistant follows.
+
+**Example Workflow:**
+
+```text
+1. Understand the query.
+2. Identify relevant context.
+3. Create a solution plan.
+4. Execute steps incrementally.
+5. Verify and test.
+6. Reflect and iterate.
+```
+
+This structure serves dual purpose: guiding the model and signaling users the assistant's reasoning process.
+
+### 4. Contextual Grounding
+
+In long-context situations (e.g., 100K+ token sessions), instruction placement matters:
+
+* **Place instructions at both start and end of context blocks.**
+* **Use markdown or XML delimiters for structure.**
+
+Avoid JSON when loading multiple documents; XML or structured markdown outperforms.
+
+### 5. Output Control Through Instruction Templates
+
+Instruction adherence improves when you:
+
+* Start with high-level **Response Rules**.
+* Follow with a **Step-by-Step Plan**.
+* Include examples demonstrating the expected behavior.
+* End with an instruction to think step by step.
+
+**Example Prompt Structure:**
+
+```markdown
+# Instructions
+- Respond concisely.
+- Think before acting.
+- Use only tools provided.
+
+# Steps
+1. Interpret the question.
+2. Search the context.
+3. Synthesize the answer.
+
+# Example
+**Q:** What caused the error?
+**A:** Let's review the logs first...
+
+# Final Thought Instruction
+Think step by step before answering.
+```
+
+## Planning in Practice
+
+Below is a sample prompt segment leveraging all core planning and chain-of-thought features:
+
+```text
+You must:
+- Plan extensively before calling any function.
+- Reflect on outcomes after each call.
+- Do not chain tools blindly.
+- Be cautious of false positives or early stopping.
+- Your solution must pass all tests, including hidden ones.
+
+Always verify:
+- Is your solution logically sound?
+- Have you tested edge cases?
+- Are additional test cases required?
+```
+
+This style boosts planning performance by up to 4% in SWE-bench according to OpenAI’s own testing.
+
+## Debugging Chain-of-Thought Failures
+
+Chain-of-thought prompts may fail due to:
+
+* Ambiguous user intent
+* Misidentification of relevant context
+* Overly abstract plans without execution
+
+**Countermeasures:**
+
+* Break user queries into sub-components.
+* Have the model rate the relevance of documents.
+* Include specific test cases as checksums for correct reasoning.
+
+**Correction Template:**
+
+```text
+Let’s revise. Where did the plan fail? What assumption was wrong? Was context misused?
+```
+
+## Long-Context Planning Strategies
+
+When context windows expand to 1M tokens:
+
+* Encourage summarization between reasoning steps.
+* Anchor sub-conclusions before proceeding.
+* Repeat critical instructions at interval checkpoints.
+
+**Chunked Reasoning Pattern:**
+
+```text
+Summarize findings every 10,000 tokens.
+Checkpoint progress with titles and delimiters.
+Reflect before moving to the next section.
+```
+
+## Tool Use Integration
+
+GPT-4.1 supports structured tool calls (functions, APIs, CLI commands). Effective planning enhances tool use via:
+
+* Context-aware parameter setting
+* Post-tool-call reflection
+* Avoiding premature tool use
+
+**Tool Use Best Practices:**
+
+* Name tools clearly and descriptively
+* Provide concise, structured descriptions
+* Offer usage examples outside of the tool schema
+
+## Practical Use Cases
+
+* **Software Agents**: Reliable plan-execute-reflect loops
+* **Data Analysis**: Step-by-step exploration of CSVs or logs
+* **Scientific Reasoning**: Layered hypothesis evaluation
+* **Customer Service Bots**: Pre-check user input → tool call → output validation
+
+## Future-Proofing Your Prompts
+
+Prompting is an empirical, iterative process. Maintain versioned prompt libraries and monitor:
+
+* Performance regressions
+* Latency vs. completeness tradeoffs
+* Tool call efficiency
+* Instruction adherence
+
+Track systematic errors over time and codify high-performing reasoning strategies into your core prompts.
+
+## Summary
+
+Chain-of-thought and planning, when intentionally embedded in GPT-4.1 prompts, unlock powerful new workflows for complex reasoning, debugging, and autonomous task completion. While GPT-4.1 does not reason innately, its ability to simulate planning and stepwise logic makes it a potent co-processor for advanced tasks.
+
+**Start with clarity. Plan before acting. Reflect after execution.** That is the path to leveraging GPT-4.1 effectively for sophisticated agentic behavior.

code_fixing_and_diff.md

@@ -0,0 +1,254 @@
+# [Code Fixing and Diff Management in GPT-4.1](https://chatgpt.com/canvas/shared/6825f21e65388191b9fb0baa737c1f18)
+
+## Overview
+
+This document provides a comprehensive implementation guide for code fixing and diff generation strategies using the OpenAI GPT-4.1 model. It is designed to help developers and tool builders harness the model’s improved agentic behavior, tool integration, and patch application capabilities. The guidance herein is based on OpenAI’s internal agentic workflows, as tested on SWE-bench Verified and related coding benchmarks.
+
+
+## Objectives
+
+* Enable GPT-4.1 to autonomously fix software bugs with minimal user intervention
+* Standardize high-performance diff formats that GPT-4.1 understands well
+* Leverage tool-calling strategies that minimize hallucination and improve precision
+* Scaffold workflows for validation, patch application, and iterative debugging
+
+
+## Core Principles for Effective Bug Fixing
+
+### 1. Persistent Multi-Step Execution
+
+To prevent premature termination, always instruct the model to:
+
+```text
+Continue working until the issue is fully resolved. Do not return control to the user unless the fix is complete and validated.
+```
+
+This aligns GPT-4.1’s behavior with full agent-mode operation.
+
+### 2. Tool-Use Encouragement
+
+Rather than letting the model hallucinate file contents:
+
+```text
+Use your tools to examine the file system or source code. Never guess.
+```
+
+This ensures queries are grounded in actual project state.
+
+### 3. Planning and Reflection Enforcement
+
+Prompt the model to:
+
+* Plan before tool calls
+* Reflect after each execution
+* Avoid chains of back-to-back tool calls without synthesis in between
+
+**Prompt Template:**
+
+```text
+You MUST plan extensively before calling a function, and reflect thoroughly on its output before deciding your next step.
+```
+
+
+## Workflow Structure
+
+### High-Level Task Phases
+
+1. **Understand the Bug**
+2. **Explore the Codebase**
+3. **Plan the Fix**
+4. **Edit the Code**
+5. **Debug and Test**
+6. **Reflect and Finalize**
+
+Each of these phases should be scaffolded in the prompt or system instructions.
+
+### Recommended Prompt Structure
+
+```markdown
+# Instructions
+- Fix the bug completely before ending.
+- Use available tools.
+- Think step-by-step before and after each action.
+
+# Workflow
+1. Understand the issue.
+2. Investigate the source files.
+3. Plan an incremental fix.
+4. Apply and validate patch.
+5. Test extensively.
+6. Reflect and iterate.
+```
+
+
+## The V4A Patch Format (Recommended)
+
+GPT-4.1 performs best with this clear, human-readable patch format:
+
+```bash
+*** Begin Patch
+*** Update File: path/to/file.py
+@@ def some_function():
+ context_before
+-    buggy_code()
++    fixed_code()
+ context_after
+*** End Patch
+```
+
+### Diff Format Rules
+
+* Use `*** Update File:` to mark the file.
+* Use `@@` to denote function or class scope.
+* Precede old code lines with `-`, new code with `+`.
+* Include 3 lines of context above and below the change.
+* If needed, add nested `@@` scopes for disambiguation.
+
+**Avoid line numbers**; GPT-4.1 does not rely on them. It uses code context instead.
+
+
+## Tool Configuration: `apply_patch`
+
+To simulate developer workflows, define a function tool with this pattern:
+
+```json
+{
+  "name": "apply_patch",
+  "description": "Apply V4A diff patches to source files",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "input": { "type": "string" }
+    },
+    "required": ["input"]
+  }
+}
+```
+
+**Input Example:**
+
+```bash
+%%bash
+apply_patch <<"EOF"
+*** Begin Patch
+*** Update File: mymodule/core.py
+@@ def validate():
+-    return False
++    return True
+*** End Patch
+EOF
+```
+
+The `apply_patch` tool accepts multi-file patches. Each file must be preceded by its action (`Add`, `Update`, or `Delete`).
+
+
+## Testing Strategy
+
+### Manual Testing within Prompt:
+
+Prompt the model to run tests after every change:
+
+```text
+Run all unit tests using `!python3 run_tests.py`. Do not assume success without verification.
+```
+
+### Encourage Reflection:
+
+```text
+Did the test results indicate success? Were any edge cases missed? Do you need to write new tests?
+```
+
+### Output Evaluation:
+
+* If tests fail, model should explain why and iterate
+* If tests pass, model should reflect before finalizing
+
+
+## Debugging and Investigation Techniques
+
+### Investigation Plan Example:
+
+```text
+I will begin by reading the test file that triggered the error, then locate the corresponding implementation file. From there, I’ll trace the logic and verify any assumptions.
+```
+
+### Debugging Prompt Reminders:
+
+* Never change code without full context
+* Use tools to inspect contents before editing
+* Print debug output if necessary
+
+
+## Failure Mode Mitigations
+
+| Failure Mode                 | Fix Strategy                                                            |
+| ---------------------------- | ----------------------------------------------------------------------- |
+| Patch applied in wrong place | Add more surrounding context or use double `@@` scope                   |
+| Patch fails silently         | Check patch syntax and apply logs before "Done!" line                   |
+| Model ends before testing    | Insert reminder: "Do not conclude until all tests are validated."       |
+| Partial bug fixes            | Require model to re-verify against original issue and user expectations |
+
+
+## Final Validation Phase
+
+Before finalizing a solution, prompt the model to:
+
+* Re-read the original problem description
+* Confirm alignment between intent and fix
+* Run a fresh test suite
+* Draft additional tests for uncovered scenarios
+* Watch for silent failures or fragile patches
+
+### Final Prompt Template:
+
+```text
+Think about the original bug and the goal. Is your fix logically complete? Did you run all tests? Are hidden edge cases covered?
+```
+
+
+## Alternative Diff Formats
+
+If you need variations, GPT-4.1 performs well with:
+
+### Search/Replace Format
+
+```text
+path/to/file.py
+>>>>>> SEARCH
+def broken():
+    pass
+=======
+def broken():
+    raise Exception("Fix me")
+<<<<<< REPLACE
+```
+
+### Pseudo-XML Format
+
+```xml
+<edit>
+  <file>path/to/file.py</file>
+  <old_code>def old(): pass</old_code>
+  <new_code>def old(): raise NotImplementedError()</new_code>
+</edit>
+```
+
+These are most useful in pipeline or IDE-integrated settings.
+
+
+## Best Practices Summary
+
+| Principle                 | Practice                                               |
+| ------------------------- | ------------------------------------------------------ |
+| Persistent Agent Behavior | Model must keep going until the fix is verified        |
+| Reflection                | Insert plan-and-reflect instructions at each phase     |
+| Patch Format              | Use V4A or equivalent context-driven diff structure    |
+| Testing                   | Prompt to test after every step                        |
+| Finalization              | Always include a validation + extra test writing phase |
+
+
+## Conclusion
+
+GPT-4.1 can serve as a robust code-fixing agent when scaffolded with precise patch formats, rigorous test validation, and persistent reflection mechanisms. By integrating tool calls such as `apply_patch` and emphasizing validation over completion, developers can reliably use the model for end-to-end issue resolution workflows.
+
+**Build the fix. Test the outcome. Validate the solution.** That’s the foundation for agentic software repair with GPT-4.1.

cookbook_pro.md

@@ -0,0 +1,288 @@
+# [OpenAI Cookbook Pro: Comprehensive GPT-4.1 Application Framework](https://chatgpt.com/canvas/shared/6825fb38b0e0819184bb3153a3eb1a52)
+
+## Introduction
+
+This document represents a fully evolved, professional-grade implementation of the OpenAI 4.1 Cookbook. It serves as a unified, production-ready guide for applied large language model deployment using GPT-4.1. Each section draws from OpenAI's internal best practices and external application patterns to provide a durable blueprint for advanced AI developers, architects, and researchers.
+
+This Cookbook Pro version encapsulates:
+
+* High-performance agentic prompting workflows
+* Instruction literalism and planning strategies
+* Long-context structuring methods
+* Tool-calling schemas and evaluation principles
+* Diff management and debugging strategies
+
+---
+
+## Part I — Agentic Workflows
+
+### 1.1 Prompt Harness Configuration
+
+#### Three Essential Prompt Reminders:
+
+```markdown
+# Persistence
+You are an agent—keep working until the task is fully resolved. Do not yield control prematurely.
+
+# Tool-Calling
+If unsure about file or codebase content, use tools to gather accurate information. Do not guess.
+
+# Planning
+Before and after every function call, explicitly plan and reflect. Avoid tool-chaining without synthesis.
+```
+
+These instructions significantly increase performance and enable stateful execution in multi-message tasks.
+
+### 1.2 Example: SWE-Bench Verified Prompt
+
+```markdown
+# Objective
+Fully resolve a software bug from an open-source issue.
+
+# Workflow
+1. Understand the problem.
+2. Explore relevant files.
+3. Plan incremental fix steps.
+4. Apply code patches.
+5. Test thoroughly.
+6. Reflect and iterate until all tests pass.
+
+# Constraint
+Only end the session when the problem is fully fixed and verified.
+```
+
+---
+
+## Part II — Instruction Following & Output Control
+
+### 2.1 Instruction Clarity Protocol
+
+Use:
+
+* `# Instructions`: General rules
+* `## Subsections`: Detailed formatting and behavioral constraints
+* Explicit instruction/response pairings
+
+### 2.2 Sample Format
+
+```markdown
+# Instructions
+- Always greet the user.
+- Avoid internal knowledge for company-specific questions.
+- Cite retrieved content.
+
+# Workflow
+1. Acknowledge the user.
+2. Call tools before answering.
+3. Reflect and respond.
+
+# Output Format
+Use: JSON with `title`, `answer`, `source` fields.
+```
+
+---
+
+## Part III — Tool Integration and Execution
+
+### 3.1 Schema Guidelines
+
+Define tools via the `tools` API parameter, not inline prompt injection.
+
+#### Tool Schema Template
+
+```json
+{
+  "name": "lookup_policy_document",
+  "description": "Retrieve company policy details by topic.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "topic": {"type": "string"}
+    },
+    "required": ["topic"]
+  }
+}
+```
+
+### 3.2 Tool Usage Best Practices
+
+* Define sample tool calls in `# Examples` sections
+* Never overload the `description` field
+* Validate inputs with required keys
+* Prompt model to message user before and after calls
+
+---
+
+## Part IV — Planning and Chain-of-Thought Induction
+
+### 4.1 Step-by-Step Prompting Pattern
+
+```markdown
+# Reasoning Strategy
+1. Query breakdown
+2. Context extraction
+3. Document relevance ranking
+4. Answer synthesis
+
+# Instruction
+Think step by step. Summarize relevant documents before answering.
+```
+
+### 4.2 Failure Mitigation Strategies
+
+| Problem           | Fix                                         |
+| ----------------- | ------------------------------------------- |
+| Early response    | Add: “Don’t conclude until fully resolved.” |
+| Tool guess        | Add: “Use tool or ask for missing data.”    |
+| CoT inconsistency | Prompt: “Summarize findings at each step.”  |
+
+---
+
+## Part V — Long Context Optimization
+
+### 5.1 Instruction Anchoring
+
+* Repeat instructions at both top and bottom of long input
+* Use structured section headers (Markdown/XML)
+
+### 5.2 Effective Delimiters
+
+| Type     | Example                 | Use Case           |                        |
+| -------- | ----------------------- | ------------------ | ---------------------- |
+| Markdown | `## Section Title`      | General purpose    |                        |
+| XML      | `<doc id='1'>...</doc>` | Document ingestion |                        |
+| ID/Title | \`ID: 3                 | TITLE: ...\`       | Knowledge base parsing |
+
+### 5.3 Example Prompt
+
+```markdown
+# Instructions
+Use only documents provided. Reflect every 10K tokens.
+
+# Long Context Input
+<doc id="14" title="Security Policy">...</doc>
+<doc id="15" title="Update Note">...</doc>
+
+# Final Instruction
+List all relevant IDs, then synthesize a summary.
+```
+
+---
+
+## Part VI — Diff Generation and Patch Application
+
+### 6.1 Recommended Format: V4A Diff
+
+```bash
+*** Begin Patch
+*** Update File: src/utils.py
+@@ def sanitize()
+-    return text
++    return text.strip()
+*** End Patch
+```
+
+### 6.2 Diff Patch Execution Tool
+
+```json
+{
+  "name": "apply_patch",
+  "description": "Apply structured code patches to files",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "input": {"type": "string"}
+    },
+    "required": ["input"]
+  }
+}
+```
+
+### 6.3 Workflow
+
+1. Investigate issue
+2. Draft V4A patch
+3. Call `apply_patch`
+4. Run tests
+5. Reflect
+
+### 6.4 Edge Case Handling
+
+| Symptom             | Action                              |
+| ------------------- | ----------------------------------- |
+| Incorrect placement | Add `@@ def` or class scope headers |
+| Test failures       | Revise patch + rerun                |
+| Silent error        | Check for malformed format          |
+
+---
+
+## Part VII — Output Evaluation Framework
+
+### 7.1 Metrics to Track
+
+| Metric                     | Description                                          |
+| -------------------------- | ---------------------------------------------------- |
+| Tool Call Accuracy         | Valid input usage and correct function selection     |
+| Response Format Compliance | Matches expected schema (e.g., JSON)                 |
+| Instruction Adherence      | Follows rules and workflow order                     |
+| Plan Reflection Rate       | Frequency and quality of plan → act → reflect cycles |
+
+### 7.2 Eval Tags for Audit
+
+```markdown
+# Eval: TOOL_USE_FAIL
+# Eval: INSTRUCTION_MISINTERPRET
+# Eval: OUTPUT_FORMAT_OK
+```
+
+---
+
+## Part VIII — Unified Prompt Template
+
+Use this as a base structure for all GPT-4.1 projects:
+
+```markdown
+# Role
+You are a [role] tasked with [objective].
+
+# Instructions
+[List core rules here.]
+
+## Response Rules
+- Always use structured formatting
+- Never repeat phrases verbatim
+
+## Workflow
+[Include ordered plan.]
+
+## Reasoning Strategy
+[Optional — for advanced reasoning tasks.]
+
+# Output Format
+[Specify format, e.g., JSON or Markdown.]
+
+# Examples
+## Example 1
+Input: "..."
+Output: {...}
+```
+
+---
+
+## Final Notes
+
+GPT-4.1 represents a leap forward in real-world agentic performance, tool adherence, long-context reliability, and instruction precision. However, performance hinges on prompt clarity, structured reasoning scaffolds, and modular tool integration.
+
+To deploy GPT-4.1 at professional scale:
+
+* Treat every prompt as a program
+* Document assumptions
+* Version control your system messages
+* Build continuous evals for regression prevention
+
+**Structure drives performance. Precision enables autonomy.**
+
+Welcome to Cookbook Pro.
+
+—End of Guide—
+

designing_agent_workflows.md

@@ -0,0 +1,354 @@
+# [Designing Agent Workflows](https://chatgpt.com/canvas/shared/6825ece10cac819189e14d95e8ecd032)
+
+## Overview
+
+The GPT-4.1 model introduces significant improvements in agentic capabilities, making it ideal for designing multi-turn workflows that rely on persistence, planning, and structured tool interaction. Whether you’re building automated software agents, coding assistants, customer service bots, or task execution systems, designing for success in GPT-4.1 requires careful coordination between prompt design, system instructions, tool usage, and behavior monitoring.
+
+This guide provides a comprehensive framework for designing effective agent workflows using GPT-4.1, detailing structural components, implementation strategies, tool invocation principles, behavioral anchors, and debugging techniques.
+
+Each section can be reused as a design module for your own applications, while contributing to the broader library of effective agent patterns.
+
+
+## What Is an Agent Workflow?
+
+An agent workflow is a sequence of steps managed by the model in which it:
+
+1. Interprets the user’s task or goal
+2. Selects and applies the right tools
+3. Iterates until the goal is fully accomplished
+4. Manages context, planning, and persistence internally
+5. Responds only after verifiable success criteria are met
+
+This process transforms GPT-4.1 from a turn-based assistant into a semi-autonomous task manager.
+
+
+## Key Model Behaviors That Enable Agent Design
+
+### Literal Instruction Compliance
+
+GPT-4.1 follows instructions with high fidelity. This includes step ordering, constraints, and termination rules. The model is more responsive to direct, formatted behavioral cues than its predecessors.
+
+### Persistent Multi-Turn Context Management
+
+The model maintains internal state across extended interactions. You can program it to persist in a loop, waiting to exit only once defined conditions are met.
+
+### Planning and Reflection
+
+Though not a reasoning-first model, GPT-4.1 can be prompted to externalize plans, reflect on outcomes, and improve with each iteration when prompted properly.
+
+### Integrated Tool Use
+
+The `tools` parameter in the API allows for direct invocation of functional calls (file inspection, patch application, database lookups, etc.) — making agentic behavior verifiable and extendable.
+
+
+## Core Agent Workflow Template
+
+### 🧩 System Prompt Template
+
+```markdown
+# Agent Instructions
+You are a multi-step problem-solving agent. Do not terminate until you have fully completed the assigned task.
+
+## Persistence
+- Continue until task completion is verified.
+- Do not yield to the user before the solution is complete.
+
+## Tool Use
+- Use tools to gather information. Do not guess.
+- Only proceed with actions when all necessary data is available.
+
+## Planning
+- Before taking an action, create a plan.
+- After each step, reflect on success/failure.
+
+# Output Format
+- Step number
+- Action taken
+- Result
+- Updated plan (if any)
+
+# Final Output
+Summarize the solution, include test results if applicable.
+```
+
+This format primes GPT-4.1 for proactive execution, tool integration, and termination control.
+
+
+## Task Archetypes: Common Agent Patterns
+
+| Task Type                | Characteristics                                                        | GPT-4.1 Design Notes                                |
+| ------------------------ | ---------------------------------------------------------------------- | --------------------------------------------------- |
+| **Code Fixing Agent**    | Requires bug reproduction, patch generation, validation via tests      | Use `apply_patch` tool + persistent reflection loop |
+| **Data Lookup Agent**    | Accesses external data via tool calls and summarizes findings          | Tool use must be verified before user response      |
+| **Support Agent**        | Answers factual queries with context validation and escalation support | Include step-by-step message plan and constraints   |
+| **Document Synth Agent** | Parses, filters, and summarizes from long context                      | Use instructions at top and bottom of prompt        |
+
+
+## Designing for Persistence
+
+Persistence is the foundation of reliable agent behavior. Without it, the model will default to single-turn chat behavior.
+
+### Design Pattern
+
+```markdown
+You must NOT yield back to the user until the task is fully complete.
+Check that all steps are verified. Repeat steps as needed. Only stop when all tests pass or instructions say to stop.
+```
+
+Reinforce this message early and late in the prompt. In tests, models were 19% more likely to complete complex multi-step tasks when given persistent execution reminders.
+
+
+## Designing for Tool Use
+
+The most reliable agents use tools for verifiable context access.
+
+### Tool Integration Best Practices
+
+* Register tools in the `tools` parameter of the OpenAI API, not embedded in prompt text.
+* Keep tool names simple and descriptive: `run_tests`, `apply_patch`, `lookup_invoice`.
+* Provide clear descriptions and optionally list examples in a separate section.
+
+### Example Tool Schema
+
+```json
+{
+  "name": "apply_patch",
+  "description": "Apply a structured diff patch to a file.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "input": {"type": "string", "description": "The formatted patch text"}
+    },
+    "required": ["input"]
+  }
+}
+```
+
+### Tool Usage Prompts
+
+```markdown
+If you do not have enough context to proceed, pause and use the tools provided.
+Do not guess about code, structure, or missing data. Always verify by tool.
+```
+
+
+## Planning and Reflection Prompts
+
+Planning and reflection are the structural anchors of agentic reasoning.
+
+### Pre-Action Planning Prompt
+
+```markdown
+Before proceeding:
+1. Restate the goal in your own words
+2. Write a short plan of how you will solve it
+3. List any tools you will need
+```
+
+### Post-Action Reflection Prompt
+
+```markdown
+After taking an action:
+1. Summarize the result
+2. List any unexpected outcomes
+3. Determine if the goal is met
+4. If not, update your plan and try again
+```
+
+These templates increase accuracy in multi-step execution by enforcing self-monitoring.
+
+
+## Full Agent Walkthrough: SWE-bench Example
+
+### System Prompt (Extracted from OpenAI's internal best practices)
+
+```markdown
+You are a coding agent tasked with solving bugs in open-source software.
+
+## Task Requirements
+- Always plan before you act
+- Use tools to inspect files and apply patches
+- Validate your fix with rigorous tests
+
+## Workflow
+1. Understand the bug deeply
+2. Investigate the codebase using tools
+3. Plan a fix
+4. Apply the fix in small, testable steps
+5. Run tests frequently
+6. Iterate until all visible and hidden tests pass
+7. Reflect and finalize
+
+## Rules
+- Do not stop unless all tests pass
+- If a fix fails, debug the failure and reattempt
+- Document your process
+```
+
+### Tool Call: `apply_patch`
+
+```bash
+apply_patch <<"EOF"
+*** Begin Patch
+*** Update File: src/module/handler.py
+@@ def process_input():
+-    if input:
++    if input is not None:
+     handle(input)
+*** End Patch
+EOF
+```
+
+### Tool Call: `run_tests`
+
+```bash
+!python3 -m unittest discover
+```
+
+### Agent Response (Example)
+
+```
+Step 1: Analyzed stack trace and confirmed null check missing
+Step 2: Planned patch using apply_patch tool
+Step 3: Applied patch successfully
+Step 4: Ran tests – 1 failure in edge case
+Step 5: Revised patch
+Step 6: Re-ran tests – all passed
+Task complete. Final patch validated.
+```
+
+
+## Failure Modes and Mitigations
+
+| Failure Type                   | Symptom                               | Mitigation Tip                               |
+| ------------------------------ | ------------------------------------- | -------------------------------------------- |
+| Premature Turn Yield           | Agent ends before solving             | Add explicit no-yield rules in system prompt |
+| Tool Hallucination             | Tool called with invalid or null data | Instruct agent to ask for data if missing    |
+| No Planning or Reflection      | Skips step-by-step reasoning          | Add planning and reflection anchors          |
+| Ignoring Final Validation Step | Says task complete before verifying   | Add final verification checklist to prompt   |
+
+
+## Output Format Suggestions
+
+A consistent output format improves interpretability and downstream usage.
+
+### Recommended Layout
+
+```markdown
+# Task Status: In Progress
+
+## Current Step: Plan and Execute Fix
+- Tool used: apply_patch
+- Patch outcome: Success
+
+## Next Step
+- Run full tests
+- Validate output for edge cases
+```
+
+You can train GPT-4.1 to adopt consistent internal status reporting with a format guide provided in each system prompt.
+
+
+## Escalation, Recovery, and Termination
+
+### Escalation
+
+Encourage the model to escalate to the user when required:
+
+```markdown
+If more data or permissions are needed, ask the user explicitly.
+If a step cannot be completed after three attempts, escalate.
+```
+
+### Recovery
+
+Allow the model to acknowledge failure and retry with adjustments:
+
+```markdown
+If your fix fails tests, reflect and revise the patch.
+List new hypotheses and retry using a modified plan.
+```
+
+### Termination
+
+Use clear termination rules:
+
+```markdown
+Only end your session when:
+- All tests pass
+- The task is fully verified
+- You have summarized your actions for the user
+```
+
+
+## Behavioral Design Tips
+
+| Technique                     | Effect                                              |
+| ----------------------------- | --------------------------------------------------- |
+| System prompt layering        | Prioritizes stable task framing                     |
+| Mid-prompt behavior resets    | Reinforces correct tool usage after failed attempts |
+| Named sections (Markdown/XML) | Improves adherence to plan and formatting           |
+| Soft conditionals             | Encourages resilience (“If X fails, try Y…”)        |
+
+
+## Designing for Developer Control
+
+Create parameterized prompts for easier tuning and behavior adjustment.
+
+### Template with Parameters
+
+```python
+AGENT_TEMPLATE = f"""
+# Role: {role}
+# Task: {task_description}
+# Output Format: {format_spec}
+# Tools: {', '.join(tool_names)}
+# Planning Required: {'Yes' if planning else 'No'}
+"""
+```
+
+Use this model to power dashboards, agent templates, and UI-driven behavior controls.
+
+
+## Testing Agent Workflows
+
+Use evaluation harnesses to test agent performance:
+
+* Track step completion
+* Analyze tool usage logs
+* Compare plan quality across variants
+
+Key metrics:
+
+* Task success rate
+* Iteration count per completion
+* Tool error frequency
+* Response length and structure fidelity
+
+
+## Summary
+
+Agent workflows in GPT-4.1 are structured, reliable, and controllable — provided the design follows consistent instruction patterns, plans for tool usage, and includes persistence logic.
+
+Follow these principles:
+
+* Anchor every agent with clear, literal instructions
+* Use tool APIs instead of embedded tool descriptions
+* Require planning and reflection around actions
+* Validate every output with structured criteria
+
+By shaping agent workflows as formal task managers, developers can build systems that reliably complete complex operations in a safe, verifiable manner.
+
+
+## Next Steps
+
+Explore these additional modules to expand your agent capabilities:
+
+* [`Prompting for Instruction Following`](./Prompting%20for%20Instruction%20Following.md)
+* [`Long Context Strategies`](./Long%20Context.md)
+* [`Tool Calling and Integration`](./Tool%20Use%20and%20Integration.md)
+
+For more agent-ready templates, visit the `/agent_design/` directory in the main repository.
+
+
+For contributions or questions, open an issue or submit a pull request to `/agent_design/Designing Agent Workflows.md`.

handling_long_contexts.md

@@ -0,0 +1,279 @@
+# [Handling Long Contexts in GPT-4.1](https://chatgpt.com/canvas/shared/6825f136fb448191aadfd3cded6defe5)
+
+## Overview
+
+This guide focuses on how to effectively structure, prompt, and manage long contexts when working with GPT-4.1. With support for a 1 million-token context window, GPT-4.1 unlocks new possibilities for processing, reasoning, and extracting information from large datasets and documents. However, the benefits of long context can only be realized when prompts are precisely structured and context is meaningfully prioritized. This guide outlines practical techniques for context formatting, instruction design, and reasoning support across extended input windows.
+
+## Objectives
+
+* Help developers utilize the full long-context capability of GPT-4.1
+* Mitigate degradation in response quality due to token overflow or disorganized input
+* Establish formatting and reasoning best practices that align with OpenAI’s tested strategies
+* Enable document processing, re-ranking, retrieval, and multi-hop reasoning across long inputs
+
+
+## 1. Understanding Long Context Use Cases
+
+GPT-4.1 is capable of processing up to 1 million tokens of input, making it suitable for a wide range of applications including:
+
+* **Structured Document Parsing**: Legal documents, scientific papers, contracts, etc.
+* **Retrieval-Augmented Generation (RAG)**: Combining long contexts with internal and external tools
+* **Knowledge Graph Construction**: Extracting structured relationships from unstructured data
+* **Log and Trace Analysis**: Reviewing extended server logs or output sequences
+* **Multi-hop Reasoning**: Synthesizing answers from distributed pieces of information
+
+While the model can technically parse vast inputs, developers must implement strategies to avoid cognitive overload and focus model attention effectively.
+
+
+## 2. Context Organization Principles
+
+### 2.1 Optimal Instruction Placement
+
+OpenAI’s internal experiments found that the **positioning of prompt instructions significantly affects model performance**. Key guidelines include:
+
+* **Dual placement**: Repeat key instructions at both the beginning and end of the prompt.
+* **Top-loading**: If instructions are only placed once, placing them at the beginning is more effective than the end.
+* **Segmented framing**: Use sectional titles to clearly mark transitions.
+
+### 2.2 Delimiter Selection
+
+To help the model parse structure in large blocks of text, delimiters must be used consistently and appropriately:
+
+| Delimiter Format               | Description                  | Use Case                              |
+| ------------------------------ | ---------------------------- | ------------------------------------- |
+| **Markdown (`#`, `##`, `-`)**  | Clean sectioning, readable   | General-purpose long context parsing  |
+| **XML (`<doc>`, `<section>`)** | Best for document modeling   | Structured multi-document input       |
+| **Inline backticks**           | For code, queries, and data  | Code and SQL parsing, tool parameters |
+| **Avoid JSON**                 | Inefficient parsing at scale | Do not use for >10K token lists       |
+
+Markdown and XML structures yield better attention modeling across long contexts, while JSON often introduces parsing inefficiencies beyond a few thousand tokens.
+
+
+## 3. Strategies for Long-Context Prompting
+
+### 3.1 Context-Aware Instructioning
+
+When dealing with large input windows, standard prompt formats must evolve. Use detailed scaffolds that define model behavior across each phase:
+
+```markdown
+# Instructions
+- Use only the documents provided.
+- Focus on relevance before synthesis.
+- Reflect after each major section.
+
+# Reasoning Strategy
+1. Read and segment.
+2. Rank relevance.
+3. Synthesize step-by-step.
+
+# Final Reminder
+Adhere strictly to section boundaries and reason incrementally.
+```
+
+### 3.2 Step-by-Step Processing with Summarization
+
+Break the long input into **logical checkpoints**. After each checkpoint:
+
+* Summarize progress.
+* List open questions.
+* Forecast the next reasoning step.
+
+This promotes internal alignment without hardcoding logic into tool calls.
+
+**Example Prompt Snippet:**
+
+```text
+After reading the next 5,000 tokens, summarize key entities mentioned and note unresolved questions. Then continue.
+```
+
+
+## 4. Long-Context Reasoning Patterns
+
+### 4.1 Needle-in-a-Haystack Retrieval
+
+GPT-4.1 performs reliably at locating information embedded deep within large corpora. Best practices for precision include:
+
+* **Unique section headers** to guide location memory
+* **Explicit re-ranking instructions** after initial search
+* **Preliminary entity listing** to establish anchors
+
+### 4.2 Document Relevance Rating
+
+When feeding dozens or hundreds of documents into the model, instruct it to:
+
+1. Score each document based on a relevance scale
+2. Justify the score with reference to query terms
+3. Select only medium/high relevance docs for synthesis
+
+**Example Snippet:**
+
+```text
+Rate each doc on relevance to the query [high, medium, low]. Provide one sentence justification per doc. Use only high/medium docs in the final answer.
+```
+
+### 4.3 Multi-Hop Document Synthesis
+
+For complex queries requiring synthesis from several different inputs:
+
+* Start by identifying all possibly relevant documents
+* Extract one-sentence summaries from each
+* Weigh the evidence to converge on an answer
+
+This scaffolds model behavior in a transparent and verifiable way.
+
+
+## 5. Managing Instructional Interference
+
+As context grows, risk increases that initial instructions may be forgotten or overridden. To address this:
+
+* **Insert refresher instructions at each major context segment**
+* **Bold or delimit** instructional snippets to create visual attention anchors
+* **Use hierarchical structure**: Title → Sub-section → Instruction → Content
+
+Example:
+
+```markdown
+## Part 3: Analyze Error Logs
+**Reminder:** Focus only on logs mentioning `TimeoutError`. Ignore unrelated traces.
+```
+
+
+## 6. Failure Modes and Fixes
+
+### 6.1 Early Context Drift
+
+**Symptom:** The model misinterprets a query due to overemphasis on the early documents.
+
+**Solution:** Insert a midway reflection point:
+
+```text
+Pause and verify: Are we still on track based on the original query?
+```
+
+### 6.2 Instruction Overload
+
+**Symptom:** Model ignores or selectively follows prompt instructions.
+
+**Solution:** Simplify instruction blocks. Group similar guidance. Use numbered checklists.
+
+### 6.3 Latency and Token Limitations
+
+**Symptom:** Prompting becomes slow or the output is truncated.
+
+**Solution:**
+
+* Shorten low-salience sections.
+* Summarize documents before passing into prompt.
+* Use a retrieval step to filter top-k relevant items.
+
+
+## 7. Formatting Techniques for Long Contexts
+
+### 7.1 Title-ID Pairing
+
+Helpful in multi-document prompts.
+
+```text
+ID: 001 | TITLE: Terms of Use | CONTENT: The user agrees to...
+```
+
+This increases model ability to re-reference sections.
+
+### 7.2 XML Embedding for Hierarchical Structure
+
+```xml
+<doc id="34" title="Security Policy">
+<summary>Contains threat classifications and countermeasures</summary>
+<content>...</content>
+</doc>
+```
+
+This formatting supports multi-pass parsing and structured memory.
+
+
+## 8. Alignment Between Internal and External Knowledge
+
+In long-context tasks, decisions must be made about how much to rely on provided context vs. internal knowledge.
+
+**Guideline Matrix:**
+
+| Mode             | Model Should...                                                     |
+| ---------------- | ------------------------------------------------------------------- |
+| Strict Retrieval | Only use external documents. If unsure, say "Not enough info."      |
+| Hybrid Mode      | Use context first, but fill in with internal knowledge when needed. |
+| Pure Generation  | Use own knowledge; ignore prompt context.                           |
+
+When prompting, make mode explicit:
+
+```text
+Use only the following context. If insufficient, reply: "Insufficient data."
+```
+
+
+## 9. Tools and Token Budgeting
+
+### 9.1 Token Allocation Strategy
+
+When constructing long prompts, divide tokens based on relevance and priority:
+
+| Section               | Suggested Max Tokens | Notes                                   |
+| --------------------- | -------------------- | --------------------------------------- |
+| Instructions          | 1,000                | Include high-priority guidance twice    |
+| Context Documents     | 900,000              | Use title delimiters, sort by relevance |
+| Task-Specific Prompts | 50,000               | Include reasoning strategy scaffolds    |
+
+Prioritize content by query salience and clarity.
+
+### 9.2 Intermediate Tool Use
+
+Encourage the model to use tools mid-way:
+
+* Re-rank document clusters
+* Extract named entities
+* Visualize flow or graph relationships
+
+Encouraging this tool interaction creates checkpoints and avoids reasoning drift.
+
+
+## 10. Testing and Evaluation
+
+When evaluating prompt effectiveness in long-context scenarios:
+
+* Measure correctness, latency, and coverage
+* Track hallucination and false-positive rates
+* Use automated evals with known answer corpora
+
+### Recommended Metrics:
+
+* Precision\@k for retrieval
+* Response coherence score (human or model-rated)
+* Instruction adherence rate
+
+Incorporate feedback loops to update prompts based on failure analysis.
+
+
+## 11. Summary and Best Practices
+
+| Principle             | Best Practice                     |
+| --------------------- | --------------------------------- |
+| Instruction Placement | Use top and bottom                |
+| Context Segmentation  | Insert checkpoints, summaries     |
+| Delimiters            | Prefer Markdown/XML over JSON     |
+| Tool Usage            | Mid-task tool calls preferred     |
+| Evaluation            | Test adherence, accuracy, latency |
+
+Effective long-context prompting is not about more data—it’s about better structure, thoughtful pacing, and precision anchoring.
+
+
+## Final Notes
+
+GPT-4.1’s long-context capabilities can power a new generation of document-heavy applications. However, successful deployment requires more than dropping text into a prompt. It requires:
+
+* Clear segment boundaries
+* Frequent alignment checkpoints
+* Purpose-driven formatting
+* Strategic memory reinforcement
+
+With these principles in place, the model not only reads—it understands.
+
+Begin with structure. Sustain with clarity. Close with alignment.

prompt_engineering_guide.md

@@ -0,0 +1,298 @@
+# [Prompt Engineering Reference Guide for GPT-4.1](https://chatgpt.com/canvas/shared/6825f88d7170819180b56e101e8b9d31)
+
+## Overview
+
+This reference guide consolidates OpenAI’s latest findings and recommendations for effective prompt engineering with GPT-4.1. It is designed for developers, researchers, and applied AI engineers who seek reliable, reproducible results from GPT-4.1 in both experimental and production settings. The techniques presented here are rooted in empirical validation across use cases ranging from agent workflows to structured tool integration, long-context processing, and instruction-following optimization.
+
+This document emphasizes concrete prompt patterns, scaffolding techniques, and deployment-tested prompt modularity.
+
+
+## Key Prompting Concepts
+
+### 1. Instruction Literalism
+
+GPT-4.1 follows instructions **more precisely** than its predecessors. Developers should:
+
+* Avoid vague or underspecified prompts
+* Be explicit about desired behaviors, output formats, and prohibitions
+* Expect literal compliance with phrasing, including negations and scope restrictions
+
+### 2. Planning Induction
+
+GPT-4.1 does not natively plan before answering but can be prompted to simulate step-by-step reasoning.
+
+**Template:**
+
+```text
+Think carefully step by step. Break down the task into manageable parts. Then begin.
+```
+
+Planning prompts should be framed before actions and reinforced between reasoning phases.
+
+### 3. Agentic Harnessing
+
+Use GPT-4.1’s enhanced persistence and tool adherence by specifying three types of reminders:
+
+* **Persistence**: “Keep working until the problem is fully resolved.”
+* **Tool usage**: “Use available tools to inspect files—do not guess.”
+* **Planning enforcement**: “Plan and reflect before and after every function call.”
+
+These drastically increase the model’s task completion rate when integrated at the top of a system prompt.
+
+
+## Prompt Structure Blueprint
+
+A recommended modular scaffold:
+
+```markdown
+# Role and Objective
+You are a [role] tasked with [goal].
+
+# Instructions
+- Bullet-point rules or constraints
+- Output format expectations
+- Prohibited topics or phrasing
+
+# Workflow (Optional)
+1. Step-by-step plan
+2. Reflection checkpoints
+3. Tool interaction order
+
+# Reasoning Strategy (Optional)
+Describes how the model should analyze input or context before generating output.
+
+# Output Format
+JSON, Markdown, YAML, or prose specification
+
+# Examples (Optional)
+Demonstrates expected input/output behavior
+```
+
+This format increases predictability and flexibility during live prompt debugging and iteration.
+
+
+## Long-Context Prompting
+
+GPT-4.1 supports up to **1M token inputs**, enabling:
+
+* Multi-document ingestion
+* Codebase-wide searches
+* Contextual re-ranking and synthesis
+
+### Strategies:
+
+* **Repeat instructions at top and bottom**
+* **Use markdown/XML tags** for structure
+* **Insert reasoning checkpoints every 5–10k tokens**
+* **Avoid JSON for large document embedding**
+
+**Effective Delimiters:**
+
+| Format   | Use Case                             |
+| -------- | ------------------------------------ |
+| Markdown | General sectioning                   |
+| XML      | Hierarchical document parsing        |
+| Title/ID | Multi-document input structuring     |
+| JSON     | Code/tool tasks only; avoid for text |
+
+
+## Tool-Calling Integration
+
+### Schema-Based Tool Usage
+
+Define tools in the OpenAI `tools` field, not inline. Provide:
+
+* **Name** (clear and descriptive)
+* **Parameters** (structured JSON)
+* **Usage examples** (in `# Examples` section, not in `description`)
+
+**Tool Example:**
+
+```json
+{
+  "name": "get_user_info",
+  "description": "Fetches user details from the database",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "user_id": { "type": "string" }
+    },
+    "required": ["user_id"]
+  }
+}
+```
+
+### Prompt Reinforcement:
+
+```markdown
+# Tool Instructions
+- Use tools before answering factual queries
+- If info is missing, request input from user
+```
+
+### Failure Mitigation:
+
+| Issue              | Fix                                         |
+| ------------------ | ------------------------------------------- |
+| Null tool calls    | Prompt: “Ask for missing info if needed”    |
+| Over-calling tools | Add reasoning delay + post-call reflection  |
+| Missed call        | Add output format block and trigger keyword |
+
+
+## Instruction Following Optimization
+
+GPT-4.1 is optimized for literal and structured instruction parsing. Improve reliability with:
+
+### Multi-Tiered Rules
+
+Use layers:
+
+* `# Instructions`: High-level
+* `## Response Style`: Format and tone
+* `## Error Handling`: Edge case mitigation
+
+### Ordered Workflows
+
+Use numbered sequences to enforce step-by-step logic.
+
+**Prompt Snippet:**
+
+```markdown
+# Instructions
+- Greet the user
+- Request missing parameters
+- Avoid repeating exact phrasing
+- Escalate on request
+
+# Workflow
+1. Confirm intent
+2. Call tool
+3. Reflect
+4. Respond
+```
+
+
+## Chain-of-Thought Prompting (CoT)
+
+Chain-of-thought induces linear reasoning. Works best for:
+
+* Logic puzzles
+* Multi-hop QA
+* Comparative analysis
+
+**CoT Example:**
+
+```text
+Let’s think through this. First, identify what the question is asking. Then examine context. Finally, synthesize an answer.
+```
+
+**Advanced Prompt (Modular):**
+
+```markdown
+# Reasoning Strategy
+1. Query analysis
+2. Context selection
+3. Evidence synthesis
+
+# Final Instruction
+Think step by step using the strategy above.
+```
+
+
+## Failure Modes and Fixes
+
+| Problem            | Mitigation                                                     |
+| ------------------ | -------------------------------------------------------------- |
+| Tool hallucination | Require tool call block, validate schema                       |
+| Early termination  | Add: "Do not yield until goal achieved."                       |
+| Verbose repetition | Add paraphrasing constraint and variation list                 |
+| Overcompliance     | If model follows a sample phrase verbatim, instruct to vary it |
+
+
+## Evaluation Strategy
+
+Prompt effectiveness should be evaluated across:
+
+* **Instruction adherence**
+* **Tool utilization accuracy**
+* **Reasoning coherence**
+* **Failure mode frequency**
+* **Latency and cost tradeoffs**
+
+### Recommended Methodology:
+
+* Create a test suite with edge-case prompts
+* Log errors and model divergence cases
+* Use eval tags (`# Eval:`) in prompt for meta-analysis
+
+
+## Delimiter Comparison Table
+
+| Delimiter Type | Format Example     | GPT-4.1 Performance             |          |
+| -------------- | ------------------ | ------------------------------- | -------- |
+| Markdown       | `## Section Title` | Excellent                       |          |
+| XML            | `<doc>` tags       | Excellent                       |          |
+| JSON           | `{"text": "..."}`  | High (in code), Poor (in prose) |          |
+| Pipe-delimited | \`TITLE            | CONTENT\`                       | Moderate |
+
+### Best Practice:
+
+Use Markdown or XML for general structure; JSON for code/tools only.
+
+
+## Example: Prompt Debugging Workflow
+
+### Step 1: Identify Goal
+
+E.g., summarizing medical trial documents with context weighting.
+
+### Step 2: Draft Prompt Template
+
+```markdown
+# Objective
+Summarize each trial based on outcome clarity and trial scale.
+
+# Workflow
+1. Parse hypothesis/result
+2. Score for clarity
+3. Output structured summary
+
+# Output Format
+{"trial_id": ..., "clarity_score": ..., "summary": ...}
+```
+
+### Step 3: Insert Sample
+
+```json
+{"trial_id": "T01", "clarity_score": 8, "summary": "Well-documented results..."}
+```
+
+### Step 4: Validate Output
+
+Ensure model adheres to output format, logic, and reasoning instructions.
+
+
+## Summary: Prompt Engineering Heuristics
+
+| Technique                  | When to Use                         |
+| -------------------------- | ----------------------------------- |
+| Instruction Bullets        | All prompts                         |
+| Chain-of-Thought           | Any task requiring logic or steps   |
+| Workflow Lists             | Multiphase reasoning tasks          |
+| Tool Block                 | Any prompt using API/tool calls     |
+| Reflection Reminders       | Long context, debugging, validation |
+| Dual Instruction Placement | Long documents (>100K tokens)       |
+
+
+## Final Notes
+
+Prompt engineering is empirical, not theoretical. Every use case is different. To engineer effectively with GPT-4.1:
+
+* Maintain modular, versioned prompt templates
+* Use structured instructions and output formats
+* Enforce explicit planning and tool behavior
+* Iterate prompts based on logs and evals
+
+**Start simple. Add structure. Evaluate constantly.**
+
+This guide is designed to be expanded. Use it as your baseline and evolve it as your systems scale.

prompting_for_instruction_following.md

@@ -0,0 +1,293 @@
+# [Prompting for Instruction Following](https://chatgpt.com/canvas/shared/6825ebe022148191bceb9fa5473a34eb)
+
+## Overview
+
+GPT-4.1 represents a significant shift in how developers should structure prompts for reliable, deterministic, and consistent behavior. Unlike earlier models which often inferred intent liberally, GPT-4.1 adheres to instructions in a far more literal, detail-sensitive manner. This brings both increased control and greater responsibility for developers: well-designed prompts yield exceptional results, while ambiguous or conflicting instructions may result in brittle or unexpected behavior.
+
+This guide outlines best practices, real-world examples, and design patterns to fully utilize GPT-4.1’s instruction-following improvements across a variety of applications. It is structured to help you:
+
+* Understand GPT-4.1’s instruction handling behavior
+* Design high-integrity prompt scaffolds
+* Debug prompt failures and mitigate ambiguity
+* Align instructions with OpenAI’s guidance around tool usage, task persistence, and planning
+
+This file is designed to stand alone for practical use and is fully aligned with the broader `openai-cookbook-pro` repository.
+
+
+## Why Instruction-Following Matters
+
+Instruction following is central to:
+
+* **Agent behavior**: models acting in multi-step environments must reliably interpret commands
+* **Tool use**: execution hinges on clearly-defined tool invocation criteria
+* **Support workflows**: factual grounding depends on accurate boundary adherence
+* **Security and safety**: systems must not misinterpret prohibitions or fail to enforce policy constraints
+
+With GPT-4.1’s shift toward literal interpretation, instruction scaffolding becomes the primary control interface.
+
+
+## GPT-4.1 Instruction Characteristics
+
+### 1. **Literal Compliance**
+
+GPT-4.1 follows instructions with minimal assumption. If a step is missing or unclear, the model is less likely to “fill in” or guess the user’s intent.
+
+* **Previous behavior**: interpreted vague prompts broadly
+* **Current behavior**: waits for or requests clarification
+
+This improves safety and traceability but also increases fragility in loosely written prompts.
+
+### 2. **Order-Sensitive Resolution**
+
+When instructions conflict, GPT-4.1 favors those listed **last** in the prompt. This means developers should order rules hierarchically:
+
+* General rules go early
+* Specific overrides go later
+
+Example:
+
+```markdown
+# Instructions
+- Do not guess if unsure
+- Use your knowledge if a tool isn’t available
+- If both options are available, prefer the tool
+```
+
+### 3. **Format-Aware Behavior**
+
+GPT-4.1 performs better with clearly formatted instructions. Prefer structured formats:
+
+* Markdown with headers and lists
+* XML with nested tags
+* Structured sections like `# Steps`, `# Output Format`
+
+Poorly formatted, unsegmented prompts lead to instruction bleed and undesired merging of behaviors.
+
+
+## Recommended Prompt Structure
+
+Organize your prompt using a structure that mirrors OpenAI’s internal evaluation standards.
+
+### 📁 Standard Sections
+
+```markdown
+# Role and Objective
+# Instructions
+## Sub-categories for Specific Behavior
+# Workflow Steps (Optional)
+# Output Format
+# Examples (Optional)
+# Final Reminder
+```
+
+### Example Prompt Template
+
+```markdown
+# Role and Objective
+You are a customer service assistant. Your job is to resolve user issues efficiently, using tools when needed.
+
+# Instructions
+- Greet the user politely.
+- Use a tool before answering any account-related question.
+- If unsure how to proceed, ask the user for clarification.
+- If a user requests escalation, refer them to a human agent.
+
+## Output Format
+- Always use a friendly tone.
+- Format your answer in plain text.
+- Include a summary at the end of your response.
+
+## Final Reminder
+Do not rely on prior knowledge. Use provided tools and context only.
+```
+
+
+## Instruction Categories
+
+### 1. **Task Definition**
+
+Clearly state the model’s job in the opening lines. Be explicit:
+
+✅ “You are an assistant that reviews and edits legal contracts.”
+
+🚫 “Help with contracts.”
+
+### 2. **Behavioral Constraints**
+
+List what the model must or must not do:
+
+* Must call tools before responding to factual queries
+* Must ask for clarification if user input is incomplete
+* Must not provide financial or legal advice
+
+### 3. **Response Style**
+
+Define tone, length, formality, and structure.
+
+* “Keep responses under 250 words.”
+* “Avoid lists unless asked.”
+* “Use a neutral tone.”
+
+### 4. **Tool Use Protocols**
+
+Models often hallucinate tools unless guided:
+
+* “If you don’t have enough information to use a tool, ask the user for more.”
+* “Always confirm tool usage before responding.”
+
+
+## Debugging Instruction Failures
+
+Instruction-following failures often stem from the following:
+
+### Common Causes
+
+* Ambiguous rule phrasing
+* Conflicting instructions (e.g., both asking to guess and not guess)
+* Implicit behaviors expected, not stated
+* Overloaded instructions without formatting
+
+### Diagnosis Steps
+
+1. Read the full prompt in sequence
+2. Identify potential ambiguity
+3. Reorder to clarify precedence
+4. Break complex rules into atomic steps
+5. Test with structured evals
+
+
+## Instruction Layering: The 3-Tier Model
+
+When designing prompts for multi-step tasks, layer your instructions in tiers:
+
+| Tier | Layer Purpose               | Example                                    |
+| ---- | --------------------------- | ------------------------------------------ |
+| 1    | Role Declaration            | “You are an assistant for legal tasks.”    |
+| 2    | Global Behavior Constraints | “Always cite sources.”                     |
+| 3    | Task-Specific Instructions  | “In contracts, highlight ambiguous terms.” |
+
+Each layer helps disambiguate behavior and provides a fallback structure if downstream instructions fail.
+
+
+## Long Context Instruction Handling
+
+In prompts exceeding 50,000 tokens:
+
+* Place **key instructions** both **before and after** the context.
+* Use format anchors (`# Instructions`, `<rules>`) to signal boundaries.
+* Avoid relying solely on the top-of-prompt instructions.
+
+GPT-4.1 is trained to respect these placements, especially when consistent structure is maintained.
+
+
+## Literal vs. Flexible Models
+
+| Capability             | GPT-3.5 / GPT-4-turbo | GPT-4.1         |
+| ---------------------- | --------------------- | --------------- |
+| Implicit inference     | High                  | Low             |
+| Literal compliance     | Moderate              | High            |
+| Prompt flexibility     | Higher tolerance      | Lower tolerance |
+| Instruction debug cost | Lower                 | Higher          |
+
+GPT-4.1 performs better **when prompts are precise**. Treat prompt engineering as API design — clear, testable, and version-controlled.
+
+
+## Tips for Designing Instruction-Sensitive Prompts
+
+### ✔️ DO:
+
+* Use structured formatting
+* Scope behaviors into separate bullet points
+* Use examples to anchor expected output
+* Rewrite ambiguous instructions into atomic steps
+* Add conditionals explicitly (e.g., “if X, then Y”)
+
+### ❌ DON’T:
+
+* Assume the model will “understand what you meant”
+* Use overloaded sentences with multiple actions
+* Rely on invisible or implied rules
+* Assume formatting styles (e.g., bullets) are optional
+
+
+## Example: Instruction-Controlled Code Agent
+
+```markdown
+# Objective
+You are a code assistant that fixes bugs in open-source projects.
+
+# Instructions
+- Always use the tools provided to inspect code.
+- Do not make edits unless you have confirmed the bug’s root cause.
+- If a change is proposed, validate using tests.
+- Do not respond unless the patch is applied.
+
+## Output Format
+1. Description of bug
+2. Explanation of root cause
+3. Tool output (e.g., patch result)
+4. Confirmation message
+
+## Final Note
+Do not guess. If you are unsure, use tools or ask.
+```
+
+> For a complete walkthrough, see `/examples/code-agent-instructions.md`
+
+
+## Instruction Evolution Across Iterations
+
+As your prompts grow, preserve instruction integrity using:
+
+* Versioned templates
+* Structured diffs for instruction edits
+* Commented rules for traceability
+
+Example diff:
+
+```diff
+- Always answer user questions.
++ Only answer user questions after validating tool output.
+```
+
+Maintain a changelog for prompts as you would with source code. This ensures instructional integrity during collaborative development.
+
+
+## Testing and Evaluation
+
+Prompt engineering is empirical. Validate instruction design using:
+
+* **A/B tests**: Compare variants with and without behavioral scaffolds
+* **Prompt evals**: Use deterministic queries to test edge case behavior
+* **Behavioral matrices**: Track compliance with instruction categories
+
+Example matrix:
+
+| Instruction Category | Prompt A Pass | Prompt B Pass |
+| -------------------- | ------------- | ------------- |
+| Ask if unsure        | ✅             | ❌             |
+| Use tools first      | ✅             | ✅             |
+| Avoid sensitive data | ❌             | ✅             |
+
+
+## Final Reminders
+
+GPT-4.1 is exceptionally effective **when paired with well-structured, comprehensive instructions**. Follow these principles:
+
+* Instructions should be modular and auditable.
+* Avoid unnecessary repetition, but reinforce critical rules.
+* Use formatting styles that clearly separate content.
+* Assume literalism — write prompts as if programming a function, not chatting with a person.
+
+Every prompt is a contract. GPT-4.1 honors that contract, but only if written clearly.
+
+
+## See Also
+
+* [`Agent Workflows`](../agent_design/swe_bench_agent.md)
+* [`Prompt Format Reference`](../reference/prompting_guide.md)
+* [`Long Context Strategies`](../examples/long-context-formatting.md)
+* [`OpenAI 4.1 Prompting Guide`](https://platform.openai.com/docs/guides/prompting)
+
+
+For questions, suggestions, or prompt design contributions, submit a pull request to `/examples/instruction-following.md` or open an issue in the main repo.

real_world_deployment.md

@@ -0,0 +1,282 @@
+# [Real-World Deployment Scenarios for GPT-4.1](https://chatgpt.com/canvas/shared/6825f3194b888191ae2417991002dcbd)
+
+## Overview
+
+This guide provides implementation-ready strategies for deploying GPT-4.1 in real-world systems. It outlines robust practices for integrating the model across diverse operational environments—from customer support automation to software development pipelines—while leveraging OpenAI's guidance on agentic workflows, instruction adherence, and tool integration.
+
+The focus is on reliability, agent autonomy, and system-level alignment for production use. This document emphasizes scenario-based implementation blueprints, including prompt structure, tool configuration, risk mitigation, and iterative deployment cycles.
+
+
+## Objectives
+
+* Showcase tested deployment architectures for GPT-4.1 in applied domains
+* Illustrate structured prompting strategies aligned with OpenAI's latest harness recommendations
+* Codify best practices for tool integration, planning induction, and agent persistence
+* Support enterprise-grade use through modular scenario blueprints
+
+
+## Deployment Pattern 1: Customer Service Agent
+
+### Use Case
+
+Deploy GPT-4.1 as a first-line support agent capable of greeting users, answering account-related questions, handling tool lookups, and escalating edge cases.
+
+### Prompt Structure
+
+```markdown
+# Role
+You are a helpful customer service assistant for NewTelco.
+
+# Instructions
+- Always greet the user.
+- Call tools before answering factual queries.
+- Never rely on internal knowledge for billing/account issues.
+- Ask for missing parameters if insufficient input.
+- Vary phrasing to avoid repetition.
+- Always escalate when asked.
+- Prohibited topics: [List Redacted].
+
+# Sample Interaction
+## User: Can I get my last bill?
+## Assistant:
+Hi, you've reached NewTelco. Let me retrieve that for you—one moment.
+[Calls `get_user_bill` tool]
+```
+
+### Tool Schema
+
+```json
+{
+  "name": "get_user_bill",
+  "description": "Retrieve a user's latest billing information.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "phone_number": { "type": "string" }
+    },
+    "required": ["phone_number"]
+  }
+}
+```
+
+### Best Practices
+
+* Use a formal output format block.
+* Include tool call before every factual output.
+* Cite retrieved source when answering.
+
+### Failure Mitigation
+
+| Risk                     | Prevention                                |
+| ------------------------ | ----------------------------------------- |
+| Repetitive responses     | Vary phrasing with sample lists           |
+| Tool skipping            | Require tool call before factual response |
+| Prohibited topic leakage | Reinforce restriction list + test in QA   |
+
+
+## Deployment Pattern 2: Codebase Maintenance Agent
+
+### Use Case
+
+An agent responsible for identifying and fixing bugs using diffs, applying patches, running tests, and confirming bug resolution.
+
+### Prompt Highlights
+
+```markdown
+# Instructions
+- Read all context before patching.
+- Plan changes first.
+- Apply patches with `apply_patch`.
+- Run tests before finalizing.
+- Keep going until all tests pass.
+
+# Patch Format
+*** Begin Patch
+*** Update File: path/to/file.py
+@@ def buggy():
+-    broken()
++    fixed()
+*** End Patch
+```
+
+### Tool Schema
+
+```json
+{
+  "name": "apply_patch",
+  "description": "Applies human-readable code patches",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "input": { "type": "string" }
+    },
+    "required": ["input"]
+  }
+}
+```
+
+### Agent Workflow
+
+1. Understand the bug
+2. Explore relevant files
+3. Propose and apply patch
+4. Run `!python3 run_tests.py`
+5. Reflect and iterate until success
+
+### Notes
+
+* Use `@@` headers to specify scope
+* Plan before every action
+* Reflect after test results
+
+
+## Deployment Pattern 3: Long Document Analyst
+
+### Use Case
+
+A document triage and synthesis agent for use with 100k–1M token context windows.
+
+### Prompt Setup
+
+```markdown
+# Instructions
+- Focus on relevance.
+- Reflect every 10k tokens.
+- Summarize findings by section.
+
+# Strategy
+1. Read → rate relevance
+2. Extract high-salience content
+3. Synthesize across documents
+```
+
+### Input Format Guidance
+
+* Prefer `# Section`, `<doc>` tags, or ID/TITLE headers
+* Avoid JSON for >10k tokens
+* Repeat instructions at start and end
+
+### Best Practices
+
+* Insert checkpoints every 5–10k tokens
+* Ask model to pause and reflect: “Are we on track?”
+* Evaluate document relevance before synthesis
+
+
+## Deployment Pattern 4: Data Labeling Assistant
+
+### Use Case
+
+Assist in labeling structured or unstructured data with schema validation and few-shot learning.
+
+### Prompt Structure
+
+```markdown
+# Labeling Instructions
+- Label each entry using valid categories
+- Format: {"text": ..., "label": ...}
+
+# Categories
+- Urgent
+- Normal
+- Spam
+
+# Example
+{"text": "Free money now!", "label": "Spam"}
+```
+
+### API Integration
+
+Validate against schema on submit. Add real-time audit checks for consistency.
+
+### Evaluation
+
+* Measure label precision
+* Flag outliers for review
+* Use `tool_call` to suggest schema fixes
+
+
+## Deployment Pattern 5: Research Assistant
+
+### Use Case
+
+Used by analysts to extract, summarize, and contrast findings across large research corpora.
+
+### Core Prompt Blocks
+
+```markdown
+# Objective
+Identify similarities and differences across these studies.
+
+# Step-by-Step Plan
+1. Break each study into hypothesis, method, result
+2. Extract claims
+3. Compare claim alignment or contradiction
+```
+
+### Ideal Format
+
+Use XML-structured context for each paper:
+
+```xml
+<doc id="23" title="Study A">
+<hypothesis>...</hypothesis>
+<method>...</method>
+<results>...</results>
+</doc>
+```
+
+### Output Pattern
+
+```json
+[
+  {"id": "23", "summary": "Study A supports..."},
+  {"id": "47", "summary": "Study B challenges..."},
+  {"alignment": false, "conflict_reason": "Different control group"}
+]
+```
+
+
+## Deployment Best Practices
+
+### Prompting
+
+* Use bullet-style `# Instructions`
+* Add `# Reasoning Strategy` section to guide workflow
+* Repeat instructions at top and bottom for long input
+
+### Tool Integration
+
+* Pass tools in API schema, not inline
+* Provide examples in `# Examples` section
+* Use clear tool names and parameter descriptions
+
+### Output Handling
+
+* Define expected format in advance
+* Use schema validation for structured outputs
+* Log every tool call and agent action
+
+### Iterative Evaluation
+
+* Audit performance per use case
+* Evaluate edge-case behavior explicitly
+* Collect examples of failure modes
+* Adjust prompts, tools, and planning steps accordingly
+
+
+## Summary
+
+GPT-4.1 is deployable across a wide range of real-world systems. Success depends not only on model capability but on prompt structure, tool schema clarity, planning enforcement, and continual evaluation. Each scenario benefits from opinionated workflows, persistent agent behaviors, and clearly delimited responsibilities.
+
+**Start with structured instructions. Plan agent actions. Validate at every step.**
+
+
+## Additional Notes
+
+* Always measure: accuracy, tool latency, format compliance, adherence
+* Use internal QA and sandbox environments before production
+* Document all agentic patterns and update based on logs
+* Prefer long-term performance tracking over one-off evals
+
+Deployment is not one prompt—it’s a living system. Maintain, monitor, and adapt.

tool_use_and_integration.md

@@ -0,0 +1,317 @@
+# [Tool Use and Integration](https://chatgpt.com/canvas/shared/6825ee7dbfd081919e67bd643748f8de)
+
+## Overview
+
+GPT-4.1 introduces robust capabilities for working with tools directly through the OpenAI API’s `tools` parameter. Rather than relying solely on the model's internal knowledge, developers can now extend functionality, reduce hallucination, and enforce reliable workflows by integrating explicitly defined tools into their applications.
+
+This document offers a comprehensive guide for designing and deploying tool-augmented applications using GPT-4.1. It includes best practices for tool registration, prompting strategies, tool schema design, usage examples, and debugging common tool invocation failures. Each section is modular and designed to help you build reliable systems that scale across contexts, task types, and user interfaces.
+
+
+## What is a Tool in GPT-4.1?
+
+A **tool** is an explicitly defined function or utility passed to the GPT-4.1 API, allowing the model to trigger predefined operations such as:
+
+* Running code or bash commands
+* Retrieving documents or structured data
+* Performing API calls
+* Applying file patches or diffs
+* Looking up user account information
+
+Tools are defined in a structured JSON schema and passed via the `tools` parameter. When the model determines a tool is required, it emits a function call rather than plain text. This enables **precise execution**, **auditable behavior**, and **tight application integration**.
+
+
+## Why Use Tools?
+
+| Benefit                        | Description                                                                |
+| ------------------------------ | -------------------------------------------------------------------------- |
+| **Reduces hallucination**      | Encourages the model to call real-world functions instead of guessing      |
+| **Improves traceability**      | Tool calls are logged and interpretable as function outputs                |
+| **Enables complex workflows**  | Offloads parts of the task to external systems (e.g., shell, Python, APIs) |
+| **Enhances compliance**        | Limits model responses to grounded tool outputs                            |
+| **Improves agent performance** | Required for persistent, multi-turn agentic workflows                      |
+
+
+## Tool Definition: The Schema
+
+Tools are defined using a JSON schema object that includes:
+
+* `name`: A short, unique identifier
+* `description`: A concise explanation of what the tool does
+* `parameters`: A standard JSON Schema describing expected input
+
+### Example: Python Execution Tool
+
+```json
+{
+  "type": "function",
+  "name": "python",
+  "description": "Run Python code or terminal commands in a secure environment.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "string",
+        "description": "The code or command to run"
+      }
+    },
+    "required": ["input"]
+  }
+}
+```
+
+### Best Practices for Schema Design
+
+* Use clear names: `run_tests`, `lookup_policy`, `apply_patch`
+* Keep descriptions actionable: Describe *when* and *why* to use
+* Minimize complexity: Use shallow parameter objects where possible
+* Use enums or constraints to reduce ambiguous calls
+
+
+## Registering Tools in the API
+
+In the Python SDK:
+
+```python
+response = client.chat.completions.create(
+    model="gpt-4.1",
+    messages=chat_history,
+    tools=[python_tool, get_user_info_tool],
+    tool_choice="auto"
+)
+```
+
+Set `tool_choice` to:
+
+* `"auto"`: Allow the model to choose when to call
+* A specific tool name: Force one call
+* `"none"`: Prevent tool usage (useful for testing)
+
+
+## Prompting for Tool Use
+
+### Tool Use Prompting Guidelines
+
+To guide GPT-4.1 toward proper tool usage:
+
+* **Don’t rely on the model to infer when to call a tool.** Tell it explicitly when tools are required.
+* **Prompt for failure cases**: Tell the model what to do when it lacks information (e.g., “ask the user” or “pause”).
+* **Avoid ambiguity**: Be clear about tool invocation order and data requirements.
+
+### Example Prompt Snippet
+
+```markdown
+Before answering any user question about billing, check if the necessary context is available.
+If not, use the `lookup_policy_document` tool to find relevant information.
+Never answer without citing a retrieved document.
+```
+
+### Escalation Pattern
+
+```markdown
+If the tool fails to return the necessary data, ask the user for clarification.
+If the user cannot provide it, explain the limitation and pause further action.
+```
+
+
+## Tool Use in Agent Workflows
+
+Tool usage is foundational to agent design in GPT-4.1.
+
+### Multi-Stage Task Example: Bug Fix Agent
+
+```markdown
+1. Use `read_file` to inspect code
+2. Analyze and plan a fix
+3. Use `apply_patch` to update the file
+4. Use `run_tests` to verify changes
+5. Reflect and reattempt if needed
+```
+
+Each tool call is logged as a JSON event and can be parsed programmatically.
+
+
+## Apply Patch: Recommended Format
+
+One of the most powerful GPT-4.1 patterns is **patch generation** using a diff-like format.
+
+### Patch Structure
+
+```bash
+apply_patch <<"EOF"
+*** Begin Patch
+*** Update File: path/to/file.py
+@@ def function():
+-    old_code()
++    new_code()
+*** End Patch
+EOF
+```
+
+### Tool Behavior
+
+* No line numbers required
+* Context determined by `@@` anchors and 3 lines of code before/after
+* Errors must be handled gracefully and logged
+
+See `/examples/apply_patch/` for templates and error-handling techniques.
+
+
+## Tool Examples by Use Case
+
+| Use Case              | Tool Name       | Description                                |
+| --------------------- | --------------- | ------------------------------------------ |
+| Execute code          | `python`        | Runs code or shell commands                |
+| Apply file diff       | `apply_patch`   | Applies a patch to a source file           |
+| Fetch document        | `lookup_policy` | Retrieves structured policy text           |
+| Get user account data | `get_user_info` | Fetches user account info via phone number |
+| Log analytics         | `log_event`     | Sends metadata to your analytics platform  |
+
+
+## Error Handling and Recovery
+
+Tool failure is inevitable in complex systems. Plan for it.
+
+### Guidelines for GPT-4.1:
+
+* Detect and summarize tool errors
+* Ask for missing input
+* Retry if safe
+* Escalate to user if unresolvable
+
+### Prompt Pattern: Failure Response
+
+```markdown
+If a tool fails with an error, summarize the issue clearly for the user.
+Only retry if the cause of failure is known and correctable.
+If not, explain the problem and ask the user for next steps.
+```
+
+
+## Tool Debugging and Logging
+
+Enable structured logging to track model-tool interactions:
+
+* **Log call attempts**: Include input parameters and timestamps
+* **Log success/failure outcomes**: Include model reflections
+* **Log retry logic**: Show how failures were handled
+
+This creates full traceability for AI-involved actions.
+
+### Sample Tool Call Log (JSON)
+
+```json
+{
+  "tool_name": "run_tests",
+  "input": "!python3 -m unittest discover",
+  "result": "3 tests passed, 1 failed",
+  "timestamp": "2025-05-15T14:32:12Z"
+}
+```
+
+
+## Tool Evaluation and Performance Monitoring
+
+Track tool usage metrics:
+
+* **Tool Call Rate**: How often a tool is invoked
+* **Tool Completion Rate**: How often tools finish without failure
+* **Tool Contribution Score**: Impact on final task completion
+* **Average Attempts per Task**: Retry behavior over time
+
+Use this data to refine prompting and improve tool schema design.
+
+
+## Common Pitfalls and Solutions
+
+| Issue                        | Likely Cause                                   | Solution                                             |
+| ---------------------------- | ---------------------------------------------- | ---------------------------------------------------- |
+| Tool called with empty input | Missing required parameter                     | Prompt model to validate input presence              |
+| Tool ignored                 | Tool not described clearly in schema or prompt | Add clear instruction for when to use tool           |
+| Repeated failed calls        | No failure mitigation logic                    | Add conditionals to check and respond to tool errors |
+| Model mixes tool names       | Ambiguous tool naming                          | Use short, specific, unambiguous names               |
+
+
+## Combining Tools with Instructions
+
+When combining tools with detailed instruction sets:
+
+* Include a `# Tools` section in your system prompt
+* Define when and why each tool should be used
+* Link tool calls to reasoning steps in `# Workflow`
+
+### Example Combined Prompt
+
+```markdown
+# Role
+You are a bug-fix agent using provided tools to solve code issues.
+
+# Tools
+- `read_file`: Inspect code files
+- `apply_patch`: Apply structured diffs
+- `run_tests`: Validate code after changes
+
+# Instructions
+1. Always start with file inspection
+2. Plan before making changes
+3. Test after every patch
+4. Do not finish until all tests pass
+
+# Output
+Include patch summaries, test outcomes, and current status.
+```
+
+
+## Tool Testing Templates
+
+Create test cases that validate:
+
+* Input formatting
+* Response validation
+* Prompt-tool alignment
+* Handling of edge cases
+
+Use both synthetic and real examples:
+
+```markdown
+## Tool Call Test: run_tests
+**Input**: Code with known error
+**Expected Output**: Test failure summary
+**Follow-up Behavior**: Retry with fixed patch
+```
+
+
+## Tool Choice Design
+
+Choose between model-directed or developer-directed tool invocation:
+
+| Mode          | Behavior                                    | Use Case                           |
+| ------------- | ------------------------------------------- | ---------------------------------- |
+| `auto`        | Model decides whether and when to use tools | General assistants, exploration    |
+| `none`        | Model cannot use tools                      | Testing model reasoning only       |
+| `forced` name | Developer instructs tool call immediately   | Known pipeline steps, unit testing |
+
+Choose based on control needs and task constraints.
+
+
+## Summary: Best Practices for Tool Integration
+
+| Area             | Best Practice                                            |
+| ---------------- | -------------------------------------------------------- |
+| Tool Naming      | Use action-based, unambiguous names                      |
+| Prompt Structure | Clearly define when and how tools should be used         |
+| Tool Invocation  | Register tools in API, not in plain prompt text          |
+| Failure Handling | Provide instructions for retrying or asking the user     |
+| Schema Design    | Use JSON Schema with constraints to reduce invalid input |
+| Evaluation       | Track tool call success rate and contribution to outcome |
+
+
+## Further Exploration
+
+* [`Designing Agent Workflows`](./Designing%20Agent%20Workflows.md)
+* [`Prompting for Instruction Following`](./Prompting%20for%20Instruction%20Following.md)
+* [`Long Context Strategies`](./Long%20Context.md)
+
+For community templates and tool libraries, explore the `/tools/` and `/examples/` directories in the main repository.
+
+
+For contributions, open a pull request or submit an issue in `/tools/Tool Use and Integration.md`.