groundswell 0.0.2 → 1.0.0

package/PRPs/templates/prp_base.md

@@ -1,222 +0,0 @@
-# PRP Template: {Feature Name}
-
-> **PRP**: Product Requirements Package - A comprehensive implementation guide enabling one-pass success
-
-## Pre-Implementation Checklist
-
-Before implementing, verify you have:
-- [ ] Read and understood this entire PRP
-- [ ] Access to all referenced files and documentation
-- [ ] Development environment properly configured
-- [ ] Understanding of existing codebase patterns
-
----
-
-## 1. Goal
-
-### Feature Goal
-{One clear sentence describing what this feature accomplishes}
-
-### Deliverable
-{Concrete, measurable output - what files/functionality will exist when done}
-
-### Success Definition
-{How to verify the feature works correctly - specific criteria}
-
----
-
-## 2. Context
-
-### External Documentation
-```yaml
-primary_docs:
-  - url: "{documentation_url}#specific-section"
-    purpose: "{what to learn from this}"
-    key_sections:
-      - "{section name}"
-
-reference_implementations:
-  - url: "{github_url}"
-    purpose: "{what patterns to follow}"
-    files_to_study:
-      - "{specific file path}"
-```
-
-### Codebase Context
-```yaml
-existing_patterns:
-  - file: "{path/to/file.ts}"
-    pattern: "{pattern name}"
-    follow_for: "{what aspect to replicate}"
-
-related_files:
-  - path: "{path/to/related.ts}"
-    relationship: "{how it relates to this feature}"
-
-naming_conventions:
-  files: "{convention description}"
-  classes: "{convention description}"
-  functions: "{convention description}"
-```
-
-### Technical Constraints
-```yaml
-typescript:
-  version: "{minimum version}"
-  config_requirements:
-    - "{specific tsconfig setting}"
-
-dependencies:
-  required:
-    - name: "{package name}"
-      version: "{version range}"
-      purpose: "{why needed}"
-  avoid:
-    - name: "{package to avoid}"
-      reason: "{why to avoid}"
-
-runtime:
-  node_version: "{minimum version}"
-  target: "{ES target}"
-```
-
-### Known Gotchas
-```yaml
-pitfalls:
-  - issue: "{description of common mistake}"
-    solution: "{how to avoid/fix}"
-
-  - issue: "{another common mistake}"
-    solution: "{how to avoid/fix}"
-```
-
----
-
-## 3. Implementation Tasks
-
-> Tasks are ordered by dependency. Complete each task fully before moving to the next.
-
-### Task 1: {Task Name}
-**Depends on**: None (or list dependencies)
-
-**Input**: {What you need before starting}
-
-**Steps**:
-1. {Specific action with exact file names}
-2. {Next action}
-3. {Continue...}
-
-**Output**: {What should exist when done}
-
-**Validation**: {How to verify this task is complete}
-
----
-
-### Task 2: {Task Name}
-**Depends on**: Task 1
-
-**Input**: {What you need}
-
-**Steps**:
-1. {Actions}
-
-**Output**: {Results}
-
-**Validation**: {Verification steps}
-
----
-
-{Continue with additional tasks...}
-
----
-
-## 4. Implementation Details
-
-### Code Patterns to Follow
-
-```typescript
-// Example pattern with annotations
-{code example showing the pattern to follow}
-```
-
-### File Structure
-```
-{directory structure showing where files should be created}
-```
-
-### Interface Definitions
-```typescript
-// Key interfaces that must be implemented
-{interface definitions}
-```
-
----
-
-## 5. Testing Strategy
-
-### Unit Tests
-```yaml
-test_files:
-  - path: "{test file path}"
-    covers:
-      - "{what it tests}"
-
-test_patterns:
-  - "{describe the testing pattern to follow}"
-```
-
-### Integration Tests
-```yaml
-scenarios:
-  - name: "{test scenario}"
-    validates: "{what it validates}"
-```
-
-### Manual Validation
-```yaml
-steps:
-  - action: "{what to do}"
-    expected: "{expected result}"
-```
-
----
-
-## 6. Final Validation Checklist
-
-### Code Quality
-- [ ] All TypeScript compiles without errors
-- [ ] No linting warnings
-- [ ] Follows existing code patterns
-- [ ] Proper error handling
-
-### Functionality
-- [ ] {Specific functional requirement}
-- [ ] {Another requirement}
-
-### Testing
-- [ ] Unit tests pass
-- [ ] Integration tests pass
-- [ ] Manual validation complete
-
-### Documentation
-- [ ] Code is self-documenting with clear names
-- [ ] Complex logic has comments
-- [ ] Public APIs have JSDoc
-
----
-
-## 7. "No Prior Knowledge" Test
-
-**Validation**: If someone knew nothing about this codebase, would they have everything needed to implement this successfully using only this PRP?
-
-- [ ] All file paths are absolute and specific
-- [ ] All patterns have concrete examples
-- [ ] All dependencies are explicitly listed
-- [ ] All validation steps are executable
-- [ ] No assumed knowledge of codebase internals
-
----
-
-## Confidence Score: {X}/10
-
-**Rationale**: {Brief explanation of confidence level and any remaining uncertainties}

package/docs/agent.md

@@ -1,422 +0,0 @@
-# Agents
-
-Agents are lightweight wrappers around the Anthropic SDK that execute prompts, manage tool invocation cycles, and integrate with caching and reflection systems.
-
-## Table of Contents
-
-- [Basic Usage](#basic-usage)
-- [Configuration](#configuration)
-- [Executing Prompts](#executing-prompts)
-- [Reflection](#reflection)
-- [Tools and MCP](#tools-and-mcp)
-- [Hooks](#hooks)
-- [Caching](#caching)
-- [API Reference](#api-reference)
-
-## Basic Usage
-
-```typescript
-import { createAgent, createPrompt } from 'groundswell';
-import { z } from 'zod';
-
-const agent = createAgent({
-  name: 'AnalysisAgent',
-  model: 'claude-sonnet-4-20250514',
-  enableCache: true,
-});
-
-const prompt = createPrompt({
-  user: 'Analyze this code for bugs',
-  data: { code: 'function foo() { return 42; }' },
-  responseFormat: z.object({
-    bugs: z.array(z.string()),
-    severity: z.enum(['low', 'medium', 'high']),
-  }),
-});
-
-const result = await agent.prompt(prompt);
-// result is typed: { bugs: string[], severity: 'low' | 'medium' | 'high' }
-```
-
-## Configuration
-
-### AgentConfig
-
-```typescript
-interface AgentConfig {
-  name?: string;                    // Human-readable name
-  system?: string;                  // System prompt
-  tools?: Tool[];                   // Available tools
-  mcps?: MCPServer[];               // MCP servers to connect
-  skills?: Skill[];                 // Skills to load
-  hooks?: AgentHooks;               // Lifecycle hooks
-  env?: Record<string, string>;     // Environment variables
-  enableReflection?: boolean;       // Enable reflection capability
-  enableCache?: boolean;            // Enable response caching
-  model?: string;                   // Model to use
-  maxTokens?: number;               // Max tokens for responses
-  temperature?: number;             // Response temperature
-}
-```
-
-### Configuration Priority
-
-Configuration follows a three-level override hierarchy:
-
-1. **Prompt-level** (highest priority)
-2. **Execution-level** (via `PromptOverrides`)
-3. **Agent-level** (lowest priority)
-
-```typescript
-const agent = createAgent({
-  system: 'Default system prompt',  // Agent-level
-  model: 'claude-sonnet-4-20250514',
-});
-
-const prompt = createPrompt({
-  user: 'Hello',
-  system: 'Override system prompt',  // Prompt-level (wins)
-  responseFormat: z.object({ response: z.string() }),
-});
-
-// Or override at execution time
-const result = await agent.prompt(prompt, {
-  model: 'claude-opus-4-5-20251101',  // Execution-level override
-});
-```
-
-## Executing Prompts
-
-### prompt()
-
-Returns validated response data:
-
-```typescript
-const result = await agent.prompt(prompt);
-// result is T (the response type)
-```
-
-### promptWithMetadata()
-
-Returns full execution metadata:
-
-```typescript
-const result = await agent.promptWithMetadata(prompt);
-
-console.log(result.data);       // Validated response
-console.log(result.usage);      // { input_tokens, output_tokens }
-console.log(result.duration);   // Total time in ms
-console.log(result.toolCalls);  // Number of tool invocations
-```
-
-### PromptResult
-
-```typescript
-interface PromptResult<T> {
-  data: T;                  // Validated response
-  usage: TokenUsage;        // Token usage stats
-  duration: number;         // Duration in milliseconds
-  toolCalls: number;        // Number of tool calls
-}
-
-interface TokenUsage {
-  input_tokens: number;
-  output_tokens: number;
-}
-```
-
-## Reflection
-
-Enable self-correction with the `reflect()` method:
-
-```typescript
-const agent = createAgent({
-  name: 'ReflectiveAgent',
-  enableReflection: true,
-});
-
-const result = await agent.reflect(prompt);
-```
-
-The reflection system prepends a reflection prefix to the system prompt:
-
-```
-Before answering, reflect on your reasoning step by step.
-Consider alternative approaches and potential errors.
-Then provide your final answer.
-```
-
-### Reflection Configuration
-
-```typescript
-// Agent-level
-const agent = createAgent({
-  enableReflection: true,
-});
-
-// Prompt-level
-const prompt = createPrompt({
-  user: 'Complex question',
-  enableReflection: true,
-  responseFormat: schema,
-});
-
-// Execution-level
-const result = await agent.prompt(prompt, {
-  enableReflection: true,
-});
-```
-
-## Tools and MCP
-
-### Tool Definition
-
-```typescript
-import type { Tool } from 'groundswell';
-
-const calculatorTool: Tool = {
-  name: 'calculate',
-  description: 'Performs arithmetic operations',
-  input_schema: {
-    type: 'object',
-    properties: {
-      operation: { type: 'string', enum: ['add', 'subtract', 'multiply', 'divide'] },
-      a: { type: 'number' },
-      b: { type: 'number' },
-    },
-    required: ['operation', 'a', 'b'],
-  },
-};
-```
-
-### MCP Handler
-
-Register tools with an MCP handler:
-
-```typescript
-import { MCPHandler } from 'groundswell';
-
-const mcpHandler = new MCPHandler();
-
-mcpHandler.registerServer({
-  name: 'demo',
-  transport: 'inprocess',
-  tools: [calculatorTool],
-});
-
-mcpHandler.registerToolExecutor('demo', 'calculate', async (input) => {
-  const { operation, a, b } = input;
-  switch (operation) {
-    case 'add': return { result: a + b };
-    case 'subtract': return { result: a - b };
-    case 'multiply': return { result: a * b };
-    case 'divide': return { result: a / b };
-  }
-});
-
-const agent = createAgent({
-  tools: mcpHandler.getTools(),
-});
-```
-
-### Tool Execution Flow
-
-1. Agent sends prompt to API
-2. API requests tool use
-3. Agent executes tool via MCP handler
-4. Result sent back to API
-5. Loop continues until no more tool calls
-6. Final response validated and returned
-
-## Hooks
-
-Lifecycle hooks enable logging, monitoring, and custom processing:
-
-```typescript
-import type { AgentHooks, PreToolUseContext, PostToolUseContext } from 'groundswell';
-
-const hooks: AgentHooks = {
-  preToolUse: [
-    async (ctx: PreToolUseContext) => {
-      console.log(`[PRE] Tool: ${ctx.toolName}`);
-      console.log(`Input:`, ctx.input);
-    }
-  ],
-  postToolUse: [
-    async (ctx: PostToolUseContext) => {
-      console.log(`[POST] Tool: ${ctx.toolName}`);
-      console.log(`Output:`, ctx.output);
-      console.log(`Duration: ${ctx.duration}ms`);
-    }
-  ],
-  sessionStart: [
-    async (ctx) => {
-      console.log(`Session started: ${ctx.agentName}`);
-    }
-  ],
-  sessionEnd: [
-    async (ctx) => {
-      console.log(`Session ended: ${ctx.totalDuration}ms`);
-    }
-  ],
-};
-
-const agent = createAgent({
-  hooks,
-});
-```
-
-### Hook Types
-
-| Hook | Trigger | Context |
-|------|---------|---------|
-| `preToolUse` | Before tool execution | `toolName`, `input` |
-| `postToolUse` | After tool execution | `toolName`, `input`, `output`, `duration` |
-| `sessionStart` | Before prompt execution | `agentName`, `promptId` |
-| `sessionEnd` | After prompt execution | `agentName`, `totalDuration` |
-
-## Caching
-
-### Enable Caching
-
-```typescript
-const agent = createAgent({
-  enableCache: true,
-});
-
-// First call: API request made, result cached
-const result1 = await agent.prompt(prompt);
-
-// Second call: cached result returned
-const result2 = await agent.prompt(prompt);
-```
-
-### Cache Metrics
-
-```typescript
-import { defaultCache } from 'groundswell';
-
-const metrics = defaultCache.metrics();
-console.log(`Hits: ${metrics.hits}`);
-console.log(`Misses: ${metrics.misses}`);
-console.log(`Hit rate: ${metrics.hitRate}%`);
-console.log(`Size: ${metrics.size} items`);
-console.log(`Size bytes: ${metrics.sizeBytes}`);
-```
-
-### Cache Key Generation
-
-Cache keys are deterministic SHA-256 hashes of:
-- User message
-- Data
-- System prompt
-- Model
-- Temperature
-- Max tokens
-- Tools
-- MCP servers
-- Skills
-- Response format schema
-
-Identical inputs always produce identical keys.
-
-### Disable Cache for Specific Call
-
-```typescript
-const result = await agent.prompt(prompt, {
-  disableCache: true,
-});
-```
-
-### Clear Cache
-
-```typescript
-import { defaultCache } from 'groundswell';
-
-await defaultCache.clear();
-
-// Or bust by prefix (agent ID)
-await defaultCache.bustPrefix(agent.id);
-```
-
-### Cache Configuration
-
-```typescript
-import { LLMCache } from 'groundswell';
-
-const customCache = new LLMCache({
-  maxItems: 500,           // Default: 1000
-  maxSizeBytes: 25_000_000, // Default: 50MB
-  defaultTTLMs: 7_200_000,  // Default: 1 hour
-});
-```
-
-## API Reference
-
-### Agent Class
-
-```typescript
-class Agent {
-  readonly id: string;
-  readonly name: string;
-
-  constructor(config?: AgentConfig);
-
-  prompt<T>(prompt: Prompt<T>, overrides?: PromptOverrides): Promise<T>;
-  promptWithMetadata<T>(prompt: Prompt<T>, overrides?: PromptOverrides): Promise<PromptResult<T>>;
-  reflect<T>(prompt: Prompt<T>, overrides?: PromptOverrides): Promise<T>;
-}
-```
-
-### Factory Function
-
-```typescript
-function createAgent(config?: AgentConfig): Agent;
-```
-
-### PromptOverrides
-
-```typescript
-interface PromptOverrides {
-  system?: string;
-  model?: string;
-  temperature?: number;
-  maxTokens?: number;
-  enableReflection?: boolean;
-  disableCache?: boolean;
-}
-```
-
-### Types
-
-```typescript
-interface Tool {
-  name: string;
-  description: string;
-  input_schema: {
-    type: 'object';
-    properties: Record<string, unknown>;
-    required?: string[];
-  };
-}
-
-interface MCPServer {
-  name: string;
-  transport: 'inprocess' | 'stdio' | 'http';
-  tools?: Tool[];
-}
-
-interface Skill {
-  name: string;
-  path: string;
-}
-
-interface AgentHooks {
-  preToolUse?: Array<(ctx: PreToolUseContext) => Promise<void>>;
-  postToolUse?: Array<(ctx: PostToolUseContext) => Promise<void>>;
-  sessionStart?: Array<(ctx: SessionStartContext) => Promise<void>>;
-  sessionEnd?: Array<(ctx: SessionEndContext) => Promise<void>>;
-}
-```
-
-See [examples/08-sdk-features.ts](../examples/examples/08-sdk-features.ts) for tools and hooks usage.