### LLM Configuration - API Setup (YAML)

Source: https://context7.com/phureewat29/sspo/llms.txt

YAML files are used to configure Large Language Model (LLM) API credentials and parameters. This includes specifying the API type, base URL, API key, temperature, and top_p for different models, allowing for easy management of multiple LLM integrations.

```yaml
# File: src/config/config.yaml

models:
  # Default model configuration
  gpt-4o-mini:
    api_type: "openai"
    base_url: "https://api.openai.com/v1"
    api_key: "sk-your-actual-api-key-here"
    temperature: 1
    top_p: 1

  # Alternative model configuration
  gpt-4o:
    api_type: "openai"
    base_url: "https://api.openai.com/v1"
    api_key: "sk-your-actual-api-key-here"
    temperature: 0.7
    top_p: 1

  # Custom endpoint example
  custom-llm:
    api_type: "openai"
    base_url: "https://your-custom-endpoint.com/v1"
    api_key: "your-custom-key"
    temperature: 0.8
    top_p: 0.95
```

--------------------------------

### Install and Build Project

Source: https://github.com/phureewat29/sspo/blob/main/README.md

Installs project dependencies using npm and compiles the TypeScript code into JavaScript. This is a prerequisite for running the SSPO application.

```bash
npm install
npm run build
```

--------------------------------

### Define Task Template

Source: https://github.com/phureewat29/sspo/blob/main/README.md

Defines the structure and content for a specific task, including prompt instructions, requirements, and example question-answer pairs. This template guides the prompt optimization process.

```yaml
prompt: |
  Please solve the following problem.

requirements: |
  Generate more detailed explanations and use clear reasoning steps.

count: 50

qa:
  - question: |
      What is 2 + 2?
    answer: |
      4

  - question: |
      Explain photosynthesis.
    answer: |
      Photosynthesis is the process by which plants convert sunlight into energy...
```

--------------------------------

### Initialize and Run PromptOptimizer in TypeScript

Source: https://context7.com/phureewat29/sspo/llms.txt

This snippet demonstrates how to initialize the LLM configurations and create an instance of the `PromptOptimizer` class. It then shows how to run the optimization process, which iteratively refines prompts based on self-evaluation. The output is stored in a specified workspace directory.

```typescript
import { SPO_LLM, PromptOptimizer } from 'sspo';

// Initialize the LLM configurations for optimization, evaluation, and execution
SPO_LLM.initialize(
  { model: 'gpt-4o-mini', temperature: 0.7 },  // Optimization model (higher temp for creativity)
  { model: 'gpt-4o-mini', temperature: 0.3 },  // Evaluation model (lower temp for consistency)
  { model: 'gpt-4o-mini', temperature: 0 },    // Execution model (deterministic)
  'base_model'  // Mode: 'base_model' or 'reasoning_model'
);

// Create optimizer instance
const optimizer = new PromptOptimizer(
  'workspace',      // Output directory for results
  1,                // Starting round number
  10,               // Maximum optimization rounds
  'my-project',     // Project name (creates subfolder)
  'template.yaml'   // YAML template with prompt and questions
);

// Run the optimization process
await optimizer.optimize();

// Output structure:
// workspace/
//   my-project/
//     prompts/
//       results.json          // All rounds with success metrics
//       round_1/
//         prompt.txt          // Optimized prompt text
//         answers.txt         // Generated answers
//       round_2/
//         prompt.txt
//         answers.txt
```

--------------------------------

### Prompt Testing with QuickExecute and QuickEvaluate in TypeScript

Source: https://context7.com/phureewat29/sspo/llms.txt

QuickExecute and QuickEvaluate classes facilitate rapid prompt execution and evaluation for optimization tasks. They require LLM initialization via SPO_LLM. Inputs include prompts and result data structures; outputs are execution results and comparison indicators.

```typescript
import { QuickExecute, QuickEvaluate } from 'sspo';

// Initialize LLM first
import { SPO_LLM } from 'sspo';
SPO_LLM.initialize(
  { model: 'gpt-4o-mini', temperature: 0.7 },
  { model: 'gpt-4o-mini', temperature: 0.3 },
  { model: 'gpt-4o-mini', temperature: 0 },
  'base_model'
);

// Execute a prompt against all test questions
const executor = new QuickExecute('Solve this problem step by step');
const results = await executor.promptExecute();

results.forEach((result, index) => {
  console.log(`Q${index + 1}: ${result.question}`);
  console.log(`A${index + 1}: ${result.answer}`);
});

// Evaluate two sets of results to determine which is better
const evaluator = new QuickEvaluate();

const samplesA = {
  round: 1,
  prompt: 'Answer concisely',
  answers: [
    { question: 'What is AI?', answer: 'Artificial Intelligence is machine intelligence.' }
  ]
};

const samplesB = {
  round: 2,
  prompt: 'Answer with detailed explanation',
  answers: [
    { question: 'What is AI?', answer: 'Artificial Intelligence is the simulation of human intelligence processes by machines, including learning, reasoning, and self-correction.' }
  ]
};

// Returns true if B is better, false if A is better
const isBBetter = await evaluator.promptEvaluate(samplesA, samplesB);
console.log(`Sample B is better: ${isBBetter}`);

// Note: The evaluation randomly swaps A and B positions to eliminate bias
// It runs 4 times by default and uses majority voting
```

--------------------------------

### Manage LLM Interactions with SPO_LLM in TypeScript

Source: https://context7.com/phureewat29/sspo/llms.txt

This snippet illustrates the usage of the `SPO_LLM` singleton class, which manages distinct LLM instances for optimization, evaluation, and execution with configurable temperature settings. It shows how to initialize these models and perform different types of requests, including optimization, evaluation, and execution, as well as extracting structured content from responses.

```typescript
import { SPO_LLM, RequestType } from 'sspo';

// Initialize with different models and temperatures for different tasks
SPO_LLM.initialize(
  { model: 'gpt-4o-mini', temperature: 0.7 },  // Optimizer: creative modifications
  { model: 'gpt-4o-mini', temperature: 0.3 },  // Evaluator: consistent judgments
  { model: 'gpt-4o-mini', temperature: 0 },    // Executor: deterministic outputs
  'base_model'
);

// Get the singleton instance
const llm = SPO_LLM.getInstance();

// Make different types of requests
const optimizeMessages = [
  { role: 'user', content: 'Optimize this prompt: ...' }
];
const optimizedPrompt = await llm.responser(RequestType.OPTIMIZE, optimizeMessages);

const evaluateMessages = [
  { role: 'user', content: 'Compare answer A vs B: ...' }
];
const evaluation = await llm.responser(RequestType.EVALUATE, evaluateMessages);

const executeMessages = [
  { role: 'user', content: 'Answer this question: What is 2+2?' }
];
const answer = await llm.responser(RequestType.EXECUTE, executeMessages);

// Extract structured content from XML-tagged responses
import { extractContent } from 'sspo';
const modification = extractContent(optimizedPrompt, 'modification');
const newPrompt = extractContent(optimizedPrompt, 'prompt');
```

--------------------------------

### Run SSPO Optimization Programmatically

Source: https://github.com/phureewat29/sspo/blob/main/README.md

Demonstrates how to initiate and run the SSPO prompt optimization process using TypeScript code. It involves initializing LLM settings and creating a PromptOptimizer instance.

```typescript
import { SPO_LLM, PromptOptimizer } from './src';

// Initialize LLM settings
SPO_LLM.initialize(
  { model: 'gpt-4o-mini', temperature: 0.7 },
  { model: 'gpt-4o-mini', temperature: 0.3 },
  { model: 'gpt-4o-mini', temperature: 0 },
  'base_model'
);

// Create and run optimizer
const optimizer = new PromptOptimizer(
  'workspace',   // Output directory
  1,             // Starting round
  10,            // Maximum optimization rounds
  'poem',   // Project name
  'Poem.yaml'    // Template file
);

await optimizer.optimize();
```

--------------------------------

### Template Configuration - Task Definition (YAML)

Source: https://context7.com/phureewat29/sspo/llms.txt

YAML templates define the structure of optimization tasks, including the initial prompt, optimization requirements, and evaluation question-answer pairs. This format allows for clear specification of task parameters and test cases, supporting both open-ended and question-based evaluations.

```yaml
# File: src/settings/my-task.yaml

# Initial prompt to optimize
prompt: |
  Solve the following math problem step by step.
  Show your work and explain your reasoning.

# Requirements for optimization
requirements: |
  The solution should:
  - Break down complex problems into manageable steps
  - Use clear mathematical notation
  - Verify the answer at the end
  - Explain each step in simple terms

# Number of test samples (optional, can be None)
count: 50

# Question-answer pairs for evaluation
qa:
  - question: |
      A train travels 120 miles in 2 hours. What is its average speed?
    answer: |
      60 miles per hour

  - question: |
      If x + 5 = 12, what is the value of x?
    answer: |
      7

  - question: |
      Calculate the area of a rectangle with length 8 cm and width 5 cm.
    answer: |
      40 square centimeters

  - question: |
      What is 15% of 200?
    answer: |
      30

# For open-ended tasks, use None for answers
# - question: |
#     Write a creative story about robots
#   answer: |
#     None
```

--------------------------------

### SPO_LLM Class - Multi-Model LLM Manager

Source: https://context7.com/phureewat29/sspo/llms.txt

The SPO_LLM singleton manages three separate LLM instances for optimization, evaluation, and execution tasks with different temperature settings. It allows for initializing these instances and making requests for different task types.

```APIDOC
## SPO_LLM Class

### Description
Manages separate LLM instances for optimization, evaluation, and execution with configurable temperature settings.

### Initialization
```typescript
import { SPO_LLM, RequestType } from 'sspo';

SPO_LLM.initialize(
  { model: 'gpt-4o-mini', temperature: 0.7 },  // Optimizer settings
  { model: 'gpt-4o-mini', temperature: 0.3 },  // Evaluator settings
  { model: 'gpt-4o-mini', temperature: 0 },    // Executor settings
  'base_model'                                // Mode
);
```

### Method
`getInstance()`: Returns the singleton instance of SPO_LLM.
`responser(requestType: RequestType, messages: any[])`: Sends a request to the appropriate LLM instance based on the `requestType`.

### Parameters
- **requestType** (`RequestType`): Enum specifying the type of request (`OPTIMIZE`, `EVALUATE`, `EXECUTE`).
- **messages** (`Array<object>`): An array of message objects for the LLM.

### Request Example
```typescript
import { SPO_LLM, RequestType, extractContent } from 'sspo';

const llm = SPO_LLM.getInstance();

// Optimization request
const optimizeMessages = [{ role: 'user', content: 'Optimize this prompt: ...' }];
const optimizedPrompt = await llm.responser(RequestType.OPTIMIZE, optimizeMessages);

// Evaluation request
const evaluateMessages = [{ role: 'user', content: 'Compare answer A vs B: ...' }];
const evaluation = await llm.responser(RequestType.EVALUATE, evaluateMessages);

// Execution request
const executeMessages = [{ role: 'user', content: 'Answer this question: What is 2+2?' }];
const answer = await llm.responser(RequestType.EXECUTE, executeMessages);

// Extracting content from XML-tagged responses
const modification = extractContent(optimizedPrompt, 'modification');
const newPrompt = extractContent(optimizedPrompt, 'prompt');
```

### Response Example
- `responser` returns the LLM's response string.
- `extractContent` returns the extracted string content or null if not found.
```

--------------------------------

### CLI Tool - Command-Line Interface (Bash)

Source: https://context7.com/phureewat29/sspo/llms.txt

The SSPO CLI tool provides a command-line interface for running optimization tasks without writing code. It supports extensive configuration options via command-line arguments, allowing users to customize templates, models, temperature settings, and output directories. Basic usage involves `npm run optimize`, with advanced options specified using flags.

```bash
# Basic usage with defaults (template: Poem.yaml, 10 rounds)
npm run optimize

# Custom configuration
npm run optimize -- \
  --template my-task.yaml \
  --name my-optimization \
  --max-rounds 15 \
  --opt-model gpt-4o-mini \
  --opt-temp 0.8 \
  --eval-model gpt-4o-mini \
  --eval-temp 0.2 \
  --exec-model gpt-4o-mini \
  --exec-temp 0 \
  --workspace ./results \
  --initial-round 1 \
  --mode base_model

# All available options:
# --opt-model <model>       Model for prompt optimization (default: gpt-4o-mini)
# --opt-temp <temp>         Temperature for optimization (default: 0.7)
# --eval-model <model>      Model for evaluation (default: gpt-4o-mini)
# --eval-temp <temp>        Temperature for evaluation (default: 0.3)
# --exec-model <model>      Model for execution (default: gpt-4o-mini)
# --exec-temp <temp>        Temperature for execution (default: 0)
# --workspace <path>        Output directory (default: workspace)
# --initial-round <num>     Starting round (default: 1)
# --max-rounds <num>        Maximum rounds (default: 10)
# --template <file>         YAML template file (default: Poem.yaml)
# --name <name>             Project name (default: Poem)
# --mode <mode>             base_model or reasoning_model (default: base_model)
```

--------------------------------

### SSPO CLI Options

Source: https://github.com/phureewat29/sspo/blob/main/README.md

Lists the available command-line options for the SSPO optimization process. These options allow users to fine-tune the optimization parameters, specify models, set output directories, and more.

```bash
--opt-model            Model for optimization (default: gpt-4o-mini)
--opt-temp             Temperature for optimization (default: 0.7)
--eval-model           Model for evaluation (default: gpt-4o-mini)
--eval-temp            Temperature for evaluation (default: 0.3)
--exec-model           Model for execution (default: gpt-4o-mini)
--exec-temp            Temperature for execution (default: 0)
--workspace            Output directory path (default: workspace)
--initial-round        Initial round number (default: 1)
--max-rounds           Maximum number of rounds (default: 10)
--template             Template file name (default: Poem.yaml)
--name                 Project name (default: Poem)
--mode                 Execution model mode: base_model or reasoning_model (default: base_model)
```

--------------------------------

### PromptOptimizer Class - Main Optimization Engine

Source: https://context7.com/phureewat29/sspo/llms.txt

The PromptOptimizer class orchestrates the entire prompt optimization workflow, managing rounds of optimization, evaluation, and result tracking. It initializes LLM configurations, creates an optimizer instance, and runs the optimization process.

```APIDOC
## PromptOptimizer Class

### Description
Orchestrates the prompt optimization workflow, including rounds of optimization, evaluation, and result tracking.

### Initialization
```typescript
import { SPO_LLM, PromptOptimizer } from 'sspo';

// Initialize LLM configurations
SPO_LLM.initialize(
  { model: 'gpt-4o-mini', temperature: 0.7 },  // Optimization model
  { model: 'gpt-4o-mini', temperature: 0.3 },  // Evaluation model
  { model: 'gpt-4o-mini', temperature: 0 },    // Execution model
  'base_model'                                // Mode
);

// Create optimizer instance
const optimizer = new PromptOptimizer(
  'workspace',      // Output directory
  1,                // Starting round number
  10,               // Maximum optimization rounds
  'my-project',     // Project name
  'template.yaml'   // YAML template file
);
```

### Method
`optimize()`

### Functionality
Runs the prompt optimization process.

### Request Example
```typescript
await optimizer.optimize();
```

### Response Example
The optimization process generates output files in a structured directory:
```
workspace/
  my-project/
    prompts/
      results.json          // All rounds with success metrics
      round_1/
        prompt.txt          // Optimized prompt text
        answers.txt         // Generated answers
      round_2/
        prompt.txt
        answers.txt
```
```

--------------------------------

### AsyncLLM Class - Direct LLM Client (TypeScript)

Source: https://context7.com/phureewat29/sspo/llms.txt

The AsyncLLM class in TypeScript allows for direct interaction with OpenAI-compatible LLMs. It supports automatic token usage tracking and cost calculation, offering flexibility in initialization via configuration files, custom objects, or direct parameters. Input is typically an array of message objects, and output is the LLM's response.

```typescript
import { AsyncLLM, LLMConfig, LLMsConfig } from 'sspo';

// Method 1: Load from configuration file
const llm1 = new AsyncLLM('gpt-4o-mini');

// Method 2: Create with custom configuration
const config = new LLMConfig({
  model: 'gpt-4o-mini',
  temperature: 0.8,
  api_key: 'sk-your-api-key',
  base_url: 'https://api.openai.com/v1',
  top_p: 1
});
const llm2 = new AsyncLLM(config, 'You are a helpful assistant', 'base_model');

// Method 3: Direct instantiation with reasoning model
const llm3 = new AsyncLLM('gpt-4o-mini', undefined, 'reasoning_model');

// Make API calls
const messages = [
  { role: 'system', content: 'You are a creative writer.' },
  { role: 'user', content: 'Write a short story about AI.' }
];

try {
  const response = await llm2.call(messages);
  console.log('Response:', response);

  // Get usage statistics
  const summary = llm2.getUsageSummary();
  console.log('Total tokens:', summary.total_tokens);
  console.log('Total cost: $', summary.total_cost);
  console.log('API calls made:', summary.call_count);

  // Detailed history
  summary.history.forEach((record, index) => {
    console.log(`Call ${index + 1}:`, {
      model: record.model,
      input: record.input_tokens,
      output: record.output_tokens,
      cost: `$${record.total_cost.toFixed(6)}`
    });
  });
} catch (error) {
  console.error('API call failed:', error);
}
```

--------------------------------

### SSPO Development Scripts

Source: https://github.com/phureewat29/sspo/blob/main/README.md

Provides a list of npm scripts available for developing and managing the SSPO project. These scripts cover building, running, and cleaning the project, as well as executing the optimization process.

```bash
npm run build      # Compile TypeScript
npm run start      # Run compiled application
npm run dev        # Run with ts-node (development)
npm run optimize   # Run CLI optimizer
npm run clean      # Clean build directory
```

--------------------------------

### Run SSPO Optimization via CLI

Source: https://github.com/phureewat29/sspo/blob/main/README.md

Executes the SSPO prompt optimization process using the command line. It supports basic usage and allows customization of various parameters like template file, project name, and LLM models for optimization and evaluation.

```bash
# Basic usage
npm run optimize

# With custom parameters
npm run optimize -- \
  --template template.yaml \
  --name project-1 \
  --max-rounds 5 \
  --opt-model gpt-4o-mini \
  --eval-model gpt-4o-mini
```

--------------------------------

### Configure LLM API Key

Source: https://github.com/phureewat29/sspo/blob/main/README.md

Configures Large Language Model (LLM) parameters, including the API key, base URL, temperature, and top_p. This YAML file is crucial for the SSPO to interact with OpenAI's models.

```yaml
models:
  gpt-4o-mini:
    api_key: "your-api-key-here"
    base_url: "https://api.openai.com/v1"
    temperature: 1
    top_p: 1
```

--------------------------------

### Data Management with DataUtils Class in TypeScript

Source: https://context7.com/phureewat29/sspo/llms.txt

The DataUtils class manages loading, saving, and querying optimization results across multiple rounds. It handles result data, prompt text, and performance metrics. Dependencies include the 'sspo' library.

```typescript
import { DataUtils, ResultData, QAPair } from 'sspo';

const dataUtils = new DataUtils('./workspace/my-project');

// Load all results from previous rounds
const resultsPath = './workspace/my-project/prompts';
const allResults = await dataUtils.loadResults(resultsPath);
console.log(`Loaded ${allResults.length} rounds`);

// Get the best performing round
const bestRound = await dataUtils.getBestRound();
if (bestRound) {
  console.log('Best round:', bestRound.round);
  console.log('Prompt:', bestRound.prompt);
  console.log('Success:', bestRound.succeed);
  console.log('Answers:', bestRound.answers);
}

// Create new result data
const answers: QAPair[] = [
  { question: 'What is 2+2?', answer: '4' },
  { question: 'What is 3+3?', answer: '6' }
];

const newResult: ResultData = dataUtils.createResultData(
  5,                              // round number
  answers,                        // QA pairs
  'Solve the problem carefully',  // prompt text
  true,                           // success flag
  1250                            // token count
);

// Save results
const existingResults = await dataUtils.loadResults(resultsPath);
existingResults.push(newResult);
const resultsFile = dataUtils.getResultsFilePath(resultsPath);
await dataUtils.saveResults(resultsFile, existingResults);

// Convert QA pairs to markdown format
const markdown = dataUtils.listToMarkdown(answers);
console.log(markdown);
// Output:
// ```
// Question 1
//
// What is 2+2?
//
// Answer 1
//
// 4
//
// ---
//
// Question 2
//
// What is 3+3?
//
// Answer 2
//
// 6
//
// ```
```

--------------------------------

### Structured Content Extraction with extractContent in TypeScript

Source: https://context7.com/phureewat29/sspo/llms.txt

The extractContent utility function parses LLM responses, extracting content enclosed within specified XML-like tags. It takes the response string and the tag name as input. Returns the extracted string or null if the tag is not found. Requires the 'sspo' library.

```typescript
import { extractContent } from 'sspo';

// LLMs return XML-tagged responses for structured data
const llmResponse = `
<analyse>
The current prompt lacks specificity and doesn't guide the model
to provide step-by-step reasoning.
</analyse>
<modification>
Add explicit instructions for breaking down problems and showing work
</modification>
<prompt>
You are a math tutor. For each problem:
1. Read the problem carefully
2. Identify what is being asked
3. Show each calculation step
4. Verify your answer makes sense
5. State the final answer clearly

Now solve: {question}
</prompt>
`;

// Extract specific sections
const analysis = extractContent(llmResponse, 'analyse');
console.log('Analysis:', analysis);
// "The current prompt lacks specificity..."

const modification = extractContent(llmResponse, 'modification');
console.log('Modification:', modification);
// "Add explicit instructions for breaking down problems..."

const newPrompt = extractContent(llmResponse, 'prompt');
console.log('New prompt:', newPrompt);
// "You are a math tutor. For each problem:..."

// Returns null if tag not found
const missing = extractContent(llmResponse, 'nonexistent');
console.log('Missing:', missing);
// null
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.