mirror of
https://github.com/github/awesome-copilot.git
synced 2026-02-22 19:35:13 +00:00
Add RALPH-loop recipe to Copilot SDK cookbook
Add iterative RALPH-loop (Read, Act, Log, Persist, Halt) pattern implementations for all four supported languages: - C#/.NET: ralph-loop.cs with documentation - Node.js/TypeScript: ralph-loop.ts with documentation - Python: ralph_loop.py with documentation (async API) - Go: ralph-loop.go with documentation Each recipe demonstrates: - Self-referential iteration where AI reviews its own output - Completion promise detection to halt the loop - Max iteration safety limits - File persistence between iterations Verified against real Copilot SDK APIs: - Python: fully verified end-to-end with github-copilot-sdk - Node.js: fully verified end-to-end with @github/copilot-sdk - C#: compiles and runs successfully with GitHub.Copilot.SDK - Go: compiles against github.com/github/copilot-sdk/go v0.1.23
This commit is contained in:
Anthony Shaw
238
cookbook/copilot-sdk/dotnet/ralph-loop.md
Normal file
238
cookbook/copilot-sdk/dotnet/ralph-loop.md
Normal file
@@ -0,0 +1,238 @@
|
||||
# RALPH-loop: Iterative Self-Referential AI Loops
|
||||
|
||||
Implement self-referential feedback loops where an AI agent iteratively improves work by reading its own previous output.
|
||||
|
||||
> **Runnable example:** [recipe/ralph-loop.cs](recipe/ralph-loop.cs)
|
||||
>
|
||||
> ```bash
|
||||
> cd dotnet/recipe
|
||||
> dotnet run ralph-loop.cs
|
||||
> ```
|
||||
|
||||
## What is RALPH-loop?
|
||||
|
||||
RALPH-loop is a development methodology for iterative AI-powered task completion. Named after the Ralph Wiggum technique, it embodies the philosophy of persistent iteration:
|
||||
|
||||
- **One prompt, multiple iterations**: The same prompt is processed repeatedly
|
||||
- **Self-referential feedback**: The AI reads its own previous work (file changes, git history)
|
||||
- **Completion detection**: Loop exits when a completion promise is detected in output
|
||||
- **Safety limits**: Always include a maximum iteration count to prevent infinite loops
|
||||
|
||||
## Example Scenario
|
||||
|
||||
You need to iteratively improve code until all tests pass. Instead of asking Claude to "write perfect code," you use RALPH-loop to:
|
||||
|
||||
1. Send the initial prompt with clear success criteria
|
||||
2. Claude writes code and tests
|
||||
3. Claude runs tests and sees failures
|
||||
4. Loop automatically re-sends the prompt
|
||||
5. Claude reads test output and previous code, fixes issues
|
||||
6. Repeat until all tests pass and completion promise is output
|
||||
|
||||
## Basic Implementation
|
||||
|
||||
```csharp
|
||||
using GitHub.Copilot.SDK;
|
||||
|
||||
public class RalphLoop
|
||||
{
|
||||
private readonly CopilotClient _client;
|
||||
private int _iteration = 0;
|
||||
private readonly int _maxIterations;
|
||||
private readonly string _completionPromise;
|
||||
private string? _lastResponse;
|
||||
|
||||
public RalphLoop(int maxIterations = 10, string completionPromise = "COMPLETE")
|
||||
{
|
||||
_client = new CopilotClient();
|
||||
_maxIterations = maxIterations;
|
||||
_completionPromise = completionPromise;
|
||||
}
|
||||
|
||||
public async Task<string> RunAsync(string prompt)
|
||||
{
|
||||
await _client.StartAsync();
|
||||
var session = await _client.CreateSessionAsync(new SessionConfig { Model = "gpt-5" });
|
||||
|
||||
try
|
||||
{
|
||||
while (_iteration < _maxIterations)
|
||||
{
|
||||
_iteration++;
|
||||
Console.WriteLine($"\n--- Iteration {_iteration} ---");
|
||||
|
||||
var done = new TaskCompletionSource<string>();
|
||||
session.On(evt =>
|
||||
{
|
||||
if (evt is AssistantMessageEvent msg)
|
||||
{
|
||||
_lastResponse = msg.Data.Content;
|
||||
done.SetResult(msg.Data.Content);
|
||||
}
|
||||
});
|
||||
|
||||
// Send prompt (on first iteration) or continuation
|
||||
var messagePrompt = _iteration == 1
|
||||
? prompt
|
||||
: $"{prompt}\n\nPrevious attempt:\n{_lastResponse}\n\nContinue iterating...";
|
||||
|
||||
await session.SendAsync(new MessageOptions { Prompt = messagePrompt });
|
||||
var response = await done.Task;
|
||||
|
||||
// Check for completion promise
|
||||
if (response.Contains(_completionPromise))
|
||||
{
|
||||
Console.WriteLine($"✓ Completion promise detected: {_completionPromise}");
|
||||
return response;
|
||||
}
|
||||
|
||||
Console.WriteLine($"Iteration {_iteration} complete. Continuing...");
|
||||
}
|
||||
|
||||
throw new InvalidOperationException(
|
||||
$"Max iterations ({_maxIterations}) reached without completion promise");
|
||||
}
|
||||
finally
|
||||
{
|
||||
await session.DisposeAsync();
|
||||
await _client.StopAsync();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Usage
|
||||
var loop = new RalphLoop(maxIterations: 5, completionPromise: "DONE");
|
||||
var result = await loop.RunAsync("Your task here");
|
||||
Console.WriteLine(result);
|
||||
```
|
||||
|
||||
## With File Persistence
|
||||
|
||||
For tasks involving code generation, persist state to files so the AI can see changes:
|
||||
|
||||
```csharp
|
||||
public class PersistentRalphLoop
|
||||
{
|
||||
private readonly string _workDir;
|
||||
private readonly CopilotClient _client;
|
||||
private int _iteration = 0;
|
||||
|
||||
public PersistentRalphLoop(string workDir, int maxIterations = 10)
|
||||
{
|
||||
_workDir = workDir;
|
||||
Directory.CreateDirectory(_workDir);
|
||||
_client = new CopilotClient();
|
||||
}
|
||||
|
||||
public async Task<string> RunAsync(string prompt)
|
||||
{
|
||||
await _client.StartAsync();
|
||||
var session = await _client.CreateSessionAsync(new SessionConfig { Model = "gpt-5" });
|
||||
|
||||
try
|
||||
{
|
||||
// Store initial prompt
|
||||
var promptFile = Path.Combine(_workDir, "prompt.md");
|
||||
await File.WriteAllTextAsync(promptFile, prompt);
|
||||
|
||||
while (_iteration < 10)
|
||||
{
|
||||
_iteration++;
|
||||
Console.WriteLine($"\n--- Iteration {_iteration} ---");
|
||||
|
||||
// Build context including previous work
|
||||
var contextBuilder = new StringBuilder(prompt);
|
||||
var previousOutput = Path.Combine(_workDir, $"output-{_iteration - 1}.txt");
|
||||
if (File.Exists(previousOutput))
|
||||
{
|
||||
contextBuilder.AppendLine($"\nPrevious iteration output:\n{await File.ReadAllTextAsync(previousOutput)}");
|
||||
}
|
||||
|
||||
var done = new TaskCompletionSource<string>();
|
||||
string response = "";
|
||||
session.On(evt =>
|
||||
{
|
||||
if (evt is AssistantMessageEvent msg)
|
||||
{
|
||||
response = msg.Data.Content;
|
||||
done.SetResult(msg.Data.Content);
|
||||
}
|
||||
});
|
||||
|
||||
await session.SendAsync(new MessageOptions { Prompt = contextBuilder.ToString() });
|
||||
await done.Task;
|
||||
|
||||
// Persist output
|
||||
await File.WriteAllTextAsync(
|
||||
Path.Combine(_workDir, $"output-{_iteration}.txt"),
|
||||
response);
|
||||
|
||||
if (response.Contains("COMPLETE"))
|
||||
{
|
||||
return response;
|
||||
}
|
||||
}
|
||||
|
||||
throw new InvalidOperationException("Max iterations reached");
|
||||
}
|
||||
finally
|
||||
{
|
||||
await session.DisposeAsync();
|
||||
await _client.StopAsync();
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Write clear completion criteria**: Include exactly what "done" looks like
|
||||
2. **Use output markers**: Include `<promise>COMPLETE</promise>` or similar in completion condition
|
||||
3. **Always set max iterations**: Prevents infinite loops on impossible tasks
|
||||
4. **Persist state**: Save files so AI can see what changed between iterations
|
||||
5. **Include context**: Feed previous iteration output back as context
|
||||
6. **Monitor progress**: Log each iteration to track what's happening
|
||||
|
||||
## Example: Iterative Code Generation
|
||||
|
||||
```csharp
|
||||
var prompt = @"Write a function that:
|
||||
1. Parses CSV data
|
||||
2. Validates required fields
|
||||
3. Returns parsed records or error
|
||||
4. Has unit tests
|
||||
5. Output <promise>COMPLETE</promise> when done";
|
||||
|
||||
var loop = new RalphLoop(maxIterations: 10, completionPromise: "COMPLETE");
|
||||
var result = await loop.RunAsync(prompt);
|
||||
```
|
||||
|
||||
## Handling Failures
|
||||
|
||||
```csharp
|
||||
try
|
||||
{
|
||||
var result = await loop.RunAsync(prompt);
|
||||
Console.WriteLine("Task completed successfully!");
|
||||
}
|
||||
catch (InvalidOperationException ex) when (ex.Message.Contains("Max iterations"))
|
||||
{
|
||||
Console.WriteLine("Task did not complete within iteration limit.");
|
||||
Console.WriteLine($"Last response: {loop.LastResponse}");
|
||||
// Document what was attempted and suggest alternatives
|
||||
}
|
||||
```
|
||||
|
||||
## When to Use RALPH-loop
|
||||
|
||||
**Good for:**
|
||||
- Code generation with automatic verification (tests, linters)
|
||||
- Tasks with clear success criteria
|
||||
- Iterative refinement where each attempt learns from previous failures
|
||||
- Unattended long-running improvements
|
||||
|
||||
**Not good for:**
|
||||
- Tasks requiring human judgment or design input
|
||||
- One-shot operations
|
||||
- Tasks with vague success criteria
|
||||
- Real-time interactive debugging
|
||||
132
cookbook/copilot-sdk/dotnet/recipe/ralph-loop.cs
Normal file
132
cookbook/copilot-sdk/dotnet/recipe/ralph-loop.cs
Normal file
@@ -0,0 +1,132 @@
|
||||
#:package GitHub.Copilot.SDK@*
|
||||
#:property PublishAot=false
|
||||
|
||||
using GitHub.Copilot.SDK;
|
||||
using System.Text;
|
||||
|
||||
// RALPH-loop: Iterative self-referential AI loops.
|
||||
// The same prompt is sent repeatedly, with AI reading its own previous output.
|
||||
// Loop continues until completion promise is detected in the response.
|
||||
|
||||
var prompt = @"You are iteratively building a small library. Follow these phases IN ORDER.
|
||||
Do NOT skip ahead — only do the current phase, then stop and wait for the next iteration.
|
||||
|
||||
Phase 1: Design a DataValidator class that validates records against a schema.
|
||||
- Schema defines field names, types (string, int, float, bool), and whether required.
|
||||
- Return a list of validation errors per record.
|
||||
- Show the class code only. Do NOT output COMPLETE.
|
||||
|
||||
Phase 2: Write at least 4 unit tests covering: missing required field, wrong type,
|
||||
valid record, and empty input. Show test code only. Do NOT output COMPLETE.
|
||||
|
||||
Phase 3: Review the code from phases 1 and 2. Fix any bugs, add docstrings, and add
|
||||
an extra edge-case test. Show the final consolidated code with all fixes.
|
||||
When this phase is fully done, output the exact text: COMPLETE";
|
||||
|
||||
var loop = new RalphLoop(maxIterations: 5, completionPromise: "COMPLETE");
|
||||
|
||||
try
|
||||
{
|
||||
var result = await loop.RunAsync(prompt);
|
||||
Console.WriteLine("\n=== FINAL RESULT ===");
|
||||
Console.WriteLine(result);
|
||||
}
|
||||
catch (InvalidOperationException ex)
|
||||
{
|
||||
Console.WriteLine($"\nTask did not complete: {ex.Message}");
|
||||
if (loop.LastResponse != null)
|
||||
{
|
||||
Console.WriteLine($"\nLast attempt:\n{loop.LastResponse}");
|
||||
}
|
||||
}
|
||||
|
||||
// --- RalphLoop class definition ---
|
||||
|
||||
public class RalphLoop
|
||||
{
|
||||
private readonly CopilotClient _client;
|
||||
private int _iteration = 0;
|
||||
private readonly int _maxIterations;
|
||||
private readonly string _completionPromise;
|
||||
private string? _lastResponse;
|
||||
|
||||
public RalphLoop(int maxIterations = 10, string completionPromise = "COMPLETE")
|
||||
{
|
||||
_client = new CopilotClient();
|
||||
_maxIterations = maxIterations;
|
||||
_completionPromise = completionPromise;
|
||||
}
|
||||
|
||||
public string? LastResponse => _lastResponse;
|
||||
|
||||
public async Task<string> RunAsync(string initialPrompt)
|
||||
{
|
||||
await _client.StartAsync();
|
||||
var session = await _client.CreateSessionAsync(new SessionConfig
|
||||
{
|
||||
Model = "gpt-5.1-codex-mini"
|
||||
});
|
||||
|
||||
try
|
||||
{
|
||||
while (_iteration < _maxIterations)
|
||||
{
|
||||
_iteration++;
|
||||
Console.WriteLine($"\n=== Iteration {_iteration}/{_maxIterations} ===");
|
||||
|
||||
var done = new TaskCompletionSource<string>();
|
||||
session.On(evt =>
|
||||
{
|
||||
if (evt is AssistantMessageEvent msg)
|
||||
{
|
||||
_lastResponse = msg.Data.Content;
|
||||
done.SetResult(msg.Data.Content);
|
||||
}
|
||||
});
|
||||
|
||||
var currentPrompt = BuildIterationPrompt(initialPrompt);
|
||||
Console.WriteLine($"Sending prompt (length: {currentPrompt.Length})...");
|
||||
|
||||
await session.SendAsync(new MessageOptions { Prompt = currentPrompt });
|
||||
var response = await done.Task;
|
||||
|
||||
var summary = response.Length > 200
|
||||
? response.Substring(0, 200) + "..."
|
||||
: response;
|
||||
Console.WriteLine($"Response: {summary}");
|
||||
|
||||
if (response.Contains(_completionPromise))
|
||||
{
|
||||
Console.WriteLine($"\n✓ Completion promise detected: '{_completionPromise}'");
|
||||
return response;
|
||||
}
|
||||
|
||||
Console.WriteLine($"Iteration {_iteration} complete. Continuing...");
|
||||
}
|
||||
|
||||
throw new InvalidOperationException(
|
||||
$"Max iterations ({_maxIterations}) reached without completion promise: '{_completionPromise}'");
|
||||
}
|
||||
finally
|
||||
{
|
||||
await session.DisposeAsync();
|
||||
await _client.StopAsync();
|
||||
}
|
||||
}
|
||||
|
||||
private string BuildIterationPrompt(string initialPrompt)
|
||||
{
|
||||
if (_iteration == 1)
|
||||
return initialPrompt;
|
||||
|
||||
var sb = new StringBuilder();
|
||||
sb.AppendLine(initialPrompt);
|
||||
sb.AppendLine();
|
||||
sb.AppendLine("=== CONTEXT FROM PREVIOUS ITERATION ===");
|
||||
sb.AppendLine(_lastResponse);
|
||||
sb.AppendLine("=== END CONTEXT ===");
|
||||
sb.AppendLine();
|
||||
sb.AppendLine("Continue working on this task. Review the previous attempt and improve upon it.");
|
||||
return sb.ToString();
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user