@riotprompt/riotprompt 0.0.13 → 0.0.15

package/guide/architecture.md

@@ -5,47 +5,58 @@
 ## Core Concepts
 
 ### Prompt Structure
-A `Prompt` in RiotPrompt is not a string; it is a structured object containing four main components:
+A `Prompt` in RiotPrompt is not a string; it is a structured object containing multiple components that map to different aspects of prompt engineering:
 
 1.  **Persona**: Defines *who* the AI is (System Prompt).
 2.  **Instructions**: Defines *what* the AI should do (User Prompt / Task).
 3.  **Context**: Background information, data, or documents needed to perform the task.
-4.  **Content**: Specific input data to be processed in this execution (optional, often merged with Context in simpler use cases).
+4.  **Content**: Specific input data to be processed in this execution.
+5.  **Constraints**: Operational boundaries (e.g., word count, format restrictions).
+6.  **Tone**: Style guidelines (e.g., professional, humorous).
+7.  **Examples**: Few-shot examples to demonstrate desired behavior.
+8.  **Reasoning**: Instructions on the thinking process (e.g., Chain of Thought).
+9.  **ResponseFormat**: Instructions on the output structure.
+10. **Recap**: Final reminders or summaries.
+11. **Safeguards**: Safety guidelines.
 
 ### Section System
 The fundamental building block is the `Section<T>`.
 *   A `Section` contains a list of items (of type `T`) and can also contain nested `Sections`.
-*   This allows for recursive, hierarchical structures (e.g., a Context section containing a "Market Data" section, which contains a "Q1 Results" section).
-*   **Weighted Items**: Most items extend `Weighted`, allowing them to have associated weights or parameters for advanced optimization (though simple usage ignores this).
+*   This allows for recursive, hierarchical structures.
+*   **Weighted Items**: Most items extend `Weighted`, allowing them to have associated weights or parameters for advanced optimization.
 
 ## Module Structure
 
 The project is organized into distinct logical modules:
 
 *   **`src/riotprompt.ts`**: The main entry point. Exports all sub-modules.
+*   **`src/recipes.ts`**: The **Recipes API** implementation (`cook` function). This is the high-level configuration layer that orchestrates the creation of prompts.
 *   **`src/prompt.ts`**: Defines the `Prompt` interface and factory.
-*   **`src/items/`**: Contains definitions for `Section`, `Instruction`, `Context`, `Content`.
-*   **`src/loader.ts`**: Logic for loading prompt parts from the filesystem. It handles traversing directories and parsing Markdown files (extracting headers as section titles).
-*   **`src/formatter.ts`**: Responsible for taking a `Prompt` object and converting it into a specific format (e.g., a Chat Request object or a flat string). It handles model-specific nuances via adapters.
+*   **`src/items/`**: Contains definitions for `Section` and various item types.
+*   **`src/loader.ts`**: Logic for loading prompt parts from the filesystem.
+*   **`src/formatter.ts`**: Responsible for taking a `Prompt` object and converting it into a specific format (e.g., a Chat Request object or a flat string). It handles model-specific rules via adapters.
+*   **`src/execution/`**: Contains provider implementations (OpenAI, Anthropic, Gemini) that handle API calls and structured output adaptation.
 *   **`src/serializer.ts`**: Handles converting the internal `Prompt` structure to portable formats like JSON and XML.
-*   **`src/cli.ts`**: The command-line interface implementation, using `commander` and `cardigantime` for config.
+*   **`src/cli.ts`**: The command-line interface implementation.
 
-## Data Flow (CLI)
+## Data Flow (Recipes API)
 
-1.  **Input**: User provides a directory path.
-2.  **Loader**: `loader.ts` scans the directory.
-    *   `persona.md` or `persona/` -> `Section<Instruction>` (Persona)
-    *   `instructions.md` or `instructions/` -> `Section<Instruction>` (Instructions)
-    *   `context/` -> `Section<Context>` (Context)
+1.  **Config**: User provides a `RecipeConfig` object (and optionally a template name).
+2.  **Cook**: The `cook` function processes the config:
+    *   Loads templates if specified.
+    *   Merges overrides.
+    *   Resolves file paths using `Loader`.
+    *   Creates `Section` objects for each component (`persona`, `instructions`, etc.).
+    *   Processes `zod` schemas for structured output.
 3.  **Assembly**: Parts are combined into a `Prompt` object.
-4.  **Processing**:
-    *   If **Serialization** is requested: `Serializer` converts `Prompt` to JSON/XML.
-    *   If **Formatting** is requested: `Formatter` applies model-specific rules (e.g., role assignment) to generate a Chat Request.
-5.  **Output**: Result is written to stdout or file.
+4.  **Execution**:
+    *   `executeChat` takes the `Prompt`.
+    *   `Formatter` converts it to the provider-specific format (handling roles, schema adaptation).
+    *   Provider client sends request and returns result.
 
 ## Design Decisions
 
-*   **Composition over Concatenation**: By keeping prompt parts separate until the final moment, we allow for dynamic injection, reordering, and model-specific formatting without string manipulation hell.
-*   **FileSystem as Source**: We treat the filesystem as a primary way to organize complex prompts. Folders represent Sections, files represent Items. This makes prompts version-controllable and easy to navigate.
-*   **Type Safety**: Extensive use of TypeScript generic types (`Section<T>`) ensures that we don't accidentally mix up Context (data) with Instructions (logic).
-
+*   **Configuration over Code**: The Recipes API favors declarative configuration over imperative builder patterns, making prompts easier to read and maintain.
+*   **Composition**: By keeping prompt parts separate until the final moment, we allow for dynamic injection, reordering, and model-specific formatting.
+*   **FileSystem as Source**: We treat the filesystem as a primary way to organize complex prompts. Folders represent Sections, files represent Items.
+*   **Portable Schemas**: We use `zod` as a universal schema definition language, adapting it to provider-specific formats (JSON Schema, Tools) at runtime to prevent vendor lock-in.

package/guide/index.md

@@ -8,40 +8,41 @@
 
 `riotprompt` is a library and CLI tool designed to treat LLM prompts as structured code objects rather than simple strings. It allows for the modular assembly, validation, and formatting of prompts.
 
-*   **Structured Prompts**: Prompts are composed of distinct sections: `Persona`, `Instructions`, `Context`, and `Content`.
-*   **Modular Assembly**: Sections can be loaded from separate files or directories and combined dynamically.
-*   **Model-Agnostic Formatting**: The library separates the *content* of a prompt from its *format*. It can output prompts optimized for different models (e.g., OpenAI, Claude) using adapters.
-*   **Serialization**: Prompts can be serialized to JSON or XML for storage or exchange.
-*   **CLI Tool**: A command-line interface allows for easy processing of prompt directories into formatted outputs.
+*   **Structured Prompts**: Prompts are composed of distinct sections beyond just "System" and "User". Use specialized sections like `Persona`, `Instructions`, `Constraints`, `Tone`, `Examples`, `Reasoning`, and more.
+*   **Recipes & Templates**: A declarative API (`cook`) allows you to assemble prompts from configuration objects and reusable templates.
+*   **Structured Outputs**: Portable support for structured outputs using `zod` schemas. Write one schema and use it across OpenAI, Anthropic, and Gemini.
+*   **Model-Agnostic Formatting**: The library separates the *content* of a prompt from its *format*. It can output prompts optimized for different models (e.g., handling role mapping for OpenAI's O-series vs GPT-4).
+*   **CLI Tool**: A command-line interface allows for easy scaffolding, processing, and execution of file-based prompts.
 
 ## Quick Start Context
 
 When analyzing or generating code using `riotprompt`, keep these patterns in mind:
 
-1.  **Define Sections**: Prompts are built from `Section<T>` objects.
-2.  **Create Prompt**: Use `createPrompt` to combine sections.
-3.  **Format**: Use `Formatter` to convert the structured prompt into a string or chat messages for a specific model.
+1.  **Use Recipes**: The `cook` function is the primary entry point for creating prompts programmatically.
+2.  **Use Schemas**: For structured data, pass a `zod` schema to `cook`.
+3.  **Execute via Provider**: Use `executeChat` to run prompts against LLMs, handling provider-specific details automatically.
 
 ```typescript
-import * as RiotPrompt from '@riotprompt/riotprompt';
+import { cook, executeChat } from '@riotprompt/riotprompt';
+import { z } from 'zod';
 
-// 1. Create Sections
-const persona = RiotPrompt.createSection({ title: 'Persona' })
-    .add(RiotPrompt.createInstruction('You are a helpful assistant.'));
-
-const instructions = RiotPrompt.createSection({ title: 'Instructions' })
-    .add(RiotPrompt.createInstruction('Summarize the following text.'));
+// Define output structure
+const ResultSchema = z.object({
+    summary: z.string(),
+    tags: z.array(z.string())
+});
 
-// 2. Create Prompt
-const prompt = RiotPrompt.createPrompt({
-    persona,
-    instructions
+// Create prompt
+const prompt = await cook({
+    basePath: __dirname,
+    persona: { content: 'You are a summarizer.' },
+    instructions: [{ content: 'Summarize the text.' }],
+    content: [{ content: 'Long text...' }],
+    schema: ResultSchema
 });
 
-// 3. Format
-const formatter = RiotPrompt.Formatter.create();
-// chatRequest will be a structured object suitable for API calls (e.g. OpenAI chat completion)
-const chatRequest = formatter.formatPrompt('gpt-4', prompt); 
+// Execute
+const result = await executeChat(prompt, { model: 'gpt-4o' });
 ```
 
 ## Documentation Structure
@@ -49,7 +50,6 @@ const chatRequest = formatter.formatPrompt('gpt-4', prompt);
 This guide directory contains specialized documentation for different aspects of the system:
 
 *   [Architecture](./architecture.md): Internal design, module structure, and data flow.
-*   [Usage Patterns](./usage.md): Common patterns for CLI and library usage.
+*   [Usage Patterns](./usage.md): Common patterns for CLI and library usage, including the Recipes API and Structured Outputs.
 *   [Configuration](./configuration.md): Deep dive into configuration options.
 *   [Development](./development.md): Guide for contributing to `riotprompt`.
-

package/guide/usage.md

@@ -8,15 +8,18 @@ The CLI is the primary way to interact with filesystem-based prompts.
 
 ### Directory Structure
 
-RiotPrompt expects a specific directory structure for a prompt "package":
+RiotPrompt expects a specific directory structure for a prompt "package". You can now use expanded sections for more control:
 
 ```
 my-prompt-project/
 ├── persona.md          # OR directory persona/ containing .md files
 ├── instructions.md     # OR directory instructions/ containing .md files
-└── context/            # Directory containing reference files (json, md, txt)
-    ├── data.json
-    └── background.md
+├── context/            # Directory containing reference files (json, md, txt)
+│   ├── data.json
+│   └── background.md
+├── constraints.md      # Optional: Operational constraints
+├── tone.md             # Optional: Tone and style guidelines
+└── examples.md         # Optional: Few-shot examples
 ```
 
 ### Commands
@@ -48,52 +51,106 @@ riotprompt process ./my-prompt-project --format json --output prompt.json
 riotprompt process ./my-prompt-project --format xml --output prompt.xml
 ```
 
-## Library Usage
+## Library Usage (Recipes API)
 
-You can import `riotprompt` into your own TypeScript applications to build dynamic prompt pipelines.
+The primary way to use RiotPrompt programmatically is via the **Recipes API** (`cook` function). This provides a declarative, configuration-driven approach.
 
-### Dynamic Context Injection
+### Basic Recipe
 
-A common pattern is to have static instructions but dynamic context (e.g., user data).
+```typescript
+import { cook } from '@riotprompt/riotprompt';
+
+const prompt = await cook({
+    basePath: __dirname,
+    persona: { content: 'You are a helpful AI assistant.' },
+    instructions: [
+        { content: 'Summarize the provided text.' }
+    ],
+    content: [
+        { content: 'Text to summarize goes here...' }
+    ]
+});
+```
+
+### Expanded Prompt Sections
+
+RiotPrompt now supports a wide range of specialized sections to give you fine-grained control over the prompt structure. These are inspired by advanced prompting techniques.
+
+*   **`persona`**: Who the AI is.
+*   **`instructions`**: What the AI should do.
+*   **`context`**: Background information.
+*   **`content`**: The specific input to process.
+*   **`constraints`**: Hard rules and limitations (e.g., "Do not use markdown").
+*   **`tone`**: Style and voice guidelines (e.g., "Be professional and concise").
+*   **`examples`**: Few-shot examples to guide the model.
+*   **`reasoning`**: Instructions on how to think (e.g., "Think step-by-step").
+*   **`responseFormat`**: Instructions on output structure.
+*   **`recap`**: Final reminders or summaries of instructions.
+*   **`safeguards`**: Safety guidelines and refusal criteria.
 
 ```typescript
-import * as RiotPrompt from '@riotprompt/riotprompt';
-
-async function buildPromptForUser(userData: any) {
-    // 1. Load static parts from disk
-    const loader = RiotPrompt.Loader.create();
-    const [baseContext] = await loader.load(['./prompts/base-context']);
-    
-    // 2. Create dynamic sections
-    const userContext = RiotPrompt.createSection({ title: 'User Data' });
-    userContext.add(JSON.stringify(userData));
-
-    // 3. Create Instructions
-    const instructions = RiotPrompt.createSection({ title: 'Task' })
-        .add(RiotPrompt.createInstruction('Analyze this user data.'));
-
-    // 4. Assemble
-    const prompt = RiotPrompt.createPrompt({
-        instructions,
-        contexts: RiotPrompt.createSection({ title: 'Context' })
-            .add(baseContext)
-            .add(userContext) // Inject dynamic part
-    });
-
-    return prompt;
-}
+const prompt = await cook({
+    basePath: __dirname,
+    persona: { content: 'You are a senior code reviewer.' },
+    instructions: [{ content: 'Review this pull request.' }],
+    constraints: [{ content: 'Focus on security vulnerabilities.' }],
+    tone: [{ content: 'Constructive and empathetic.' }],
+    examples: [{ path: './examples/good-review.md' }],
+    content: [{ content: prDiff }]
+});
 ```
 
-### Custom Formatters
+### Structured Outputs (Portable Schemas)
 
-If you need to output to a specific non-standard format, you can access the raw `Prompt` object structure.
+RiotPrompt supports portable structured outputs using `zod` schemas. This works across different providers (OpenAI, Anthropic, Gemini) by automatically adapting the schema to the provider's expected format (JSON Schema, Tool Use, etc.).
 
 ```typescript
-const prompt = ...;
+import { cook, executeChat } from '@riotprompt/riotprompt';
+import { z } from 'zod';
+
+// 1. Define your schema using Zod
+const AnalysisSchema = z.object({
+    sentiment: z.enum(['positive', 'negative', 'neutral']),
+    keyPoints: z.array(z.string()),
+    confidence: z.number().min(0).max(1)
+});
+
+// 2. Pass it to the cook function
+const prompt = await cook({
+    basePath: __dirname,
+    persona: { content: 'You are a sentiment analyzer.' },
+    content: [{ content: 'I loved this movie! It was fantastic.' }],
+    schema: AnalysisSchema // Pass the Zod schema directly
+});
 
-// Iterate over instructions
-prompt.instructions.items.forEach(item => {
-    console.log(item.text);
+// 3. Execute (RiotPrompt handles the provider specifics)
+const result = await executeChat(prompt, {
+    model: 'gpt-4o', // or 'claude-3-opus', 'gemini-1.5-pro'
+    apiKey: process.env.OPENAI_API_KEY
 });
+
+// result.content is validated and typed
+console.log(result.content.sentiment); // "positive"
 ```
 
+### Templates
+
+You can register reusable templates to standardize prompts across your application.
+
+```typescript
+import { registerTemplates, cook } from '@riotprompt/riotprompt';
+
+registerTemplates({
+    'security-audit': {
+        persona: { content: 'You are a security auditor.' },
+        constraints: [{ content: 'Report only high-severity issues.' }],
+        responseFormat: [{ content: 'Output as a CSV list.' }]
+    }
+});
+
+const prompt = await cook({
+    basePath: __dirname,
+    template: 'security-audit',
+    content: [{ content: sourceCode }]
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riotprompt/riotprompt",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "keywords": [
     "prompt",
     "llm",
@@ -84,6 +84,7 @@
     "marked": "^16.0.0",
     "openai": "^6.15.0",
     "tiktoken": "^1.0.22",
-    "zod": "^4.0.2"
+    "zod": "^4.0.2",
+    "zod-to-json-schema": "^3.25.1"
   }
 }