npm - groundswell - Versions diffs - 0.0.2 → 0.0.3 - Mend

groundswell 0.0.2 → 0.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (633) hide show

package/PRPs/templates/prp_base.md DELETED Viewed

@@ -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 DELETED Viewed

@@ -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.