mirror of
https://github.com/github/awesome-copilot.git
synced 2026-02-21 19:05: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
209
cookbook/copilot-sdk/nodejs/ralph-loop.md
Normal file
209
cookbook/copilot-sdk/nodejs/ralph-loop.md
Normal file
@@ -0,0 +1,209 @@
|
||||
# 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.ts](recipe/ralph-loop.ts)
|
||||
>
|
||||
> ```bash
|
||||
> cd nodejs/recipe
|
||||
> npm install
|
||||
> npx tsx ralph-loop.ts
|
||||
> ```
|
||||
|
||||
## 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
|
||||
|
||||
```typescript
|
||||
import { CopilotClient } from "@github/copilot-sdk";
|
||||
|
||||
class RalphLoop {
|
||||
private client: CopilotClient;
|
||||
private iteration: number = 0;
|
||||
private maxIterations: number;
|
||||
private completionPromise: string;
|
||||
private lastResponse: string | null = null;
|
||||
|
||||
constructor(maxIterations: number = 10, completionPromise: string = "COMPLETE") {
|
||||
this.client = new CopilotClient();
|
||||
this.maxIterations = maxIterations;
|
||||
this.completionPromise = completionPromise;
|
||||
}
|
||||
|
||||
async run(initialPrompt: string): Promise<string> {
|
||||
await this.client.start();
|
||||
const session = await this.client.createSession({ model: "gpt-5" });
|
||||
|
||||
try {
|
||||
while (this.iteration < this.maxIterations) {
|
||||
this.iteration++;
|
||||
console.log(`\n--- Iteration ${this.iteration}/${this.maxIterations} ---`);
|
||||
|
||||
// Build prompt including previous response as context
|
||||
const prompt = this.iteration === 1
|
||||
? initialPrompt
|
||||
: `${initialPrompt}\n\nPrevious attempt:\n${this.lastResponse}\n\nContinue improving...`;
|
||||
|
||||
const response = await session.sendAndWait({ prompt });
|
||||
this.lastResponse = response?.data.content || "";
|
||||
|
||||
console.log(`Response (${this.lastResponse.length} chars)`);
|
||||
|
||||
// Check for completion promise
|
||||
if (this.lastResponse.includes(this.completionPromise)) {
|
||||
console.log(`✓ Completion promise detected: ${this.completionPromise}`);
|
||||
return this.lastResponse;
|
||||
}
|
||||
|
||||
console.log(`Continuing to iteration ${this.iteration + 1}...`);
|
||||
}
|
||||
|
||||
throw new Error(
|
||||
`Max iterations (${this.maxIterations}) reached without completion promise`
|
||||
);
|
||||
} finally {
|
||||
await session.destroy();
|
||||
await this.client.stop();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Usage
|
||||
const loop = new RalphLoop(5, "COMPLETE");
|
||||
const result = await loop.run("Your task here");
|
||||
console.log(result);
|
||||
```
|
||||
|
||||
## With File Persistence
|
||||
|
||||
For tasks involving code generation, persist state to files so the AI can see changes:
|
||||
|
||||
```typescript
|
||||
import fs from "fs/promises";
|
||||
import path from "path";
|
||||
import { CopilotClient } from "@github/copilot-sdk";
|
||||
|
||||
class PersistentRalphLoop {
|
||||
private client: CopilotClient;
|
||||
private workDir: string;
|
||||
private iteration: number = 0;
|
||||
private maxIterations: number;
|
||||
|
||||
constructor(workDir: string, maxIterations: number = 10) {
|
||||
this.client = new CopilotClient();
|
||||
this.workDir = workDir;
|
||||
this.maxIterations = maxIterations;
|
||||
}
|
||||
|
||||
async run(initialPrompt: string): Promise<string> {
|
||||
await fs.mkdir(this.workDir, { recursive: true });
|
||||
await this.client.start();
|
||||
const session = await this.client.createSession({ model: "gpt-5" });
|
||||
|
||||
try {
|
||||
// Store initial prompt
|
||||
await fs.writeFile(path.join(this.workDir, "prompt.md"), initialPrompt);
|
||||
|
||||
while (this.iteration < this.maxIterations) {
|
||||
this.iteration++;
|
||||
console.log(`\n--- Iteration ${this.iteration} ---`);
|
||||
|
||||
// Build context from previous outputs
|
||||
let context = initialPrompt;
|
||||
const prevOutputFile = path.join(this.workDir, `output-${this.iteration - 1}.txt`);
|
||||
try {
|
||||
const prevOutput = await fs.readFile(prevOutputFile, "utf-8");
|
||||
context += `\n\nPrevious iteration:\n${prevOutput}`;
|
||||
} catch {
|
||||
// No previous output yet
|
||||
}
|
||||
|
||||
const response = await session.sendAndWait({ prompt: context });
|
||||
const output = response?.data.content || "";
|
||||
|
||||
// Persist output
|
||||
await fs.writeFile(
|
||||
path.join(this.workDir, `output-${this.iteration}.txt`),
|
||||
output
|
||||
);
|
||||
|
||||
if (output.includes("COMPLETE")) {
|
||||
return output;
|
||||
}
|
||||
}
|
||||
|
||||
throw new Error("Max iterations reached");
|
||||
} finally {
|
||||
await session.destroy();
|
||||
await this.client.stop();
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
```typescript
|
||||
const 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`;
|
||||
|
||||
const loop = new RalphLoop(10, "COMPLETE");
|
||||
const result = await loop.run(prompt);
|
||||
```
|
||||
|
||||
## Handling Failures
|
||||
|
||||
```typescript
|
||||
try {
|
||||
const result = await loop.run(prompt);
|
||||
console.log("Task completed successfully!");
|
||||
} catch (error) {
|
||||
console.error("Task failed:", error.message);
|
||||
// Analyze 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
|
||||
121
cookbook/copilot-sdk/nodejs/recipe/ralph-loop.ts
Normal file
121
cookbook/copilot-sdk/nodejs/recipe/ralph-loop.ts
Normal file
@@ -0,0 +1,121 @@
|
||||
import { CopilotClient } from "@github/copilot-sdk";
|
||||
|
||||
/**
|
||||
* RALPH-loop implementation: 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.
|
||||
*/
|
||||
class RalphLoop {
|
||||
private client: CopilotClient;
|
||||
private iteration: number = 0;
|
||||
private readonly maxIterations: number;
|
||||
private readonly completionPromise: string;
|
||||
public lastResponse: string | null = null;
|
||||
|
||||
constructor(maxIterations: number = 10, completionPromise: string = "COMPLETE") {
|
||||
this.client = new CopilotClient();
|
||||
this.maxIterations = maxIterations;
|
||||
this.completionPromise = completionPromise;
|
||||
}
|
||||
|
||||
/**
|
||||
* Run the RALPH-loop until completion promise is detected or max iterations reached.
|
||||
*/
|
||||
async run(initialPrompt: string): Promise<string> {
|
||||
await this.client.start();
|
||||
const session = await this.client.createSession({
|
||||
model: "gpt-5.1-codex-mini"
|
||||
});
|
||||
|
||||
try {
|
||||
while (this.iteration < this.maxIterations) {
|
||||
this.iteration++;
|
||||
console.log(`\n=== Iteration ${this.iteration}/${this.maxIterations} ===`);
|
||||
|
||||
// Build the prompt for this iteration
|
||||
const currentPrompt = this.buildIterationPrompt(initialPrompt);
|
||||
console.log(`Sending prompt (length: ${currentPrompt.length})...`);
|
||||
|
||||
const response = await session.sendAndWait({ prompt: currentPrompt }, 300_000);
|
||||
this.lastResponse = response?.data.content || "";
|
||||
|
||||
// Display response summary
|
||||
const summary = this.lastResponse.length > 200
|
||||
? this.lastResponse.substring(0, 200) + "..."
|
||||
: this.lastResponse;
|
||||
console.log(`Response: ${summary}`);
|
||||
|
||||
// Check for completion promise
|
||||
if (this.lastResponse.includes(this.completionPromise)) {
|
||||
console.log(`\n✓ Success! Completion promise detected: '${this.completionPromise}'`);
|
||||
return this.lastResponse;
|
||||
}
|
||||
|
||||
console.log(`Iteration ${this.iteration} complete. Checking for next iteration...`);
|
||||
}
|
||||
|
||||
// Max iterations reached without completion
|
||||
throw new Error(
|
||||
`Maximum iterations (${this.maxIterations}) reached without detecting completion promise: '${this.completionPromise}'`
|
||||
);
|
||||
} catch (error) {
|
||||
console.error(`\nError during RALPH-loop: ${error instanceof Error ? error.message : String(error)}`);
|
||||
throw error;
|
||||
} finally {
|
||||
await session.destroy();
|
||||
await this.client.stop();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Build the prompt for the current iteration, including previous output as context.
|
||||
*/
|
||||
private buildIterationPrompt(initialPrompt: string): string {
|
||||
if (this.iteration === 1) {
|
||||
// First iteration: just the initial prompt
|
||||
return initialPrompt;
|
||||
}
|
||||
|
||||
// Subsequent iterations: include previous output as context
|
||||
return `${initialPrompt}
|
||||
|
||||
=== CONTEXT FROM PREVIOUS ITERATION ===
|
||||
${this.lastResponse}
|
||||
=== END CONTEXT ===
|
||||
|
||||
Continue working on this task. Review the previous attempt and improve upon it.`;
|
||||
}
|
||||
}
|
||||
|
||||
// Example usage demonstrating RALPH-loop
|
||||
async function main() {
|
||||
const 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 (str, 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`;
|
||||
|
||||
const loop = new RalphLoop(5, "COMPLETE");
|
||||
|
||||
try {
|
||||
const result = await loop.run(prompt);
|
||||
console.log("\n=== FINAL RESULT ===");
|
||||
console.log(result);
|
||||
} catch (error) {
|
||||
console.error(`\nTask did not complete: ${error instanceof Error ? error.message : String(error)}`);
|
||||
if (loop.lastResponse) {
|
||||
console.log(`\nLast attempt:\n${loop.lastResponse}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
main().catch(console.error);
|
||||
Reference in New Issue
Block a user