@eldrforge/ai-service 0.1.12 → 0.1.14

package/examples/05-custom-tools.ts

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+/**
+ * Example 5: Custom Tool Integration
+ *
+ * This example demonstrates how to create and register custom tools
+ * that extend the AI's capabilities for your specific use case.
+ *
+ * Usage:
+ *   npx tsx examples/05-custom-tools.ts
+ */
+
+/* eslint-disable no-console */
+
+import {
+    createToolRegistry,
+    runAgentic,
+    type Tool,
+    type ToolContext,
+} from '@eldrforge/ai-service';
+import { execSync } from 'child_process';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+/**
+ * Custom tool: Check test coverage
+ */
+const checkTestCoverage: Tool = {
+    name: 'check_test_coverage',
+    description: 'Check test coverage for the project or specific files',
+    parameters: {
+        type: 'object',
+        properties: {
+            filePath: {
+                type: 'string',
+                description: 'Optional specific file to check coverage for',
+            },
+        },
+    },
+    execute: async (params: { filePath?: string }, context?: ToolContext) => {
+        try {
+            const cmd = params.filePath
+                ? `npm test -- --coverage --testPathPattern="${params.filePath}"`
+                : 'npm test -- --coverage --silent 2>&1';
+
+            const output = execSync(cmd, {
+                encoding: 'utf8',
+                cwd: context?.workingDirectory || process.cwd(),
+            });
+
+            // Parse coverage from output
+            const coverageMatch = output.match(/All files.*?(\d+\.?\d*)/);
+            const coverage = coverageMatch ? parseFloat(coverageMatch[1]) : 0;
+
+            return {
+                success: true,
+                coverage: `${coverage}%`,
+                message: `Test coverage: ${coverage}%`,
+            };
+        } catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    },
+};
+
+/**
+ * Custom tool: Check for linter errors
+ */
+const checkLinterErrors: Tool = {
+    name: 'check_linter_errors',
+    description: 'Check for linter/ESLint errors in the codebase',
+    parameters: {
+        type: 'object',
+        properties: {
+            filePath: {
+                type: 'string',
+                description: 'Optional specific file to lint',
+            },
+        },
+    },
+    execute: async (params: { filePath?: string }, context?: ToolContext) => {
+        try {
+            const target = params.filePath || '.';
+            const cmd = `npx eslint ${target} --format json`;
+
+            const output = execSync(cmd, {
+                encoding: 'utf8',
+                cwd: context?.workingDirectory || process.cwd(),
+            });
+
+            const results = JSON.parse(output);
+            const errorCount = results.reduce((sum: number, file: any) => sum + file.errorCount, 0);
+            const warningCount = results.reduce((sum: number, file: any) => sum + file.warningCount, 0);
+
+            return {
+                success: errorCount === 0,
+                errors: errorCount,
+                warnings: warningCount,
+                message: `Found ${errorCount} errors and ${warningCount} warnings`,
+            };
+        } catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    },
+};
+
+/**
+ * Custom tool: Analyze package dependencies
+ */
+const analyzePackageDeps: Tool = {
+    name: 'analyze_package_dependencies',
+    description: 'Analyze package.json dependencies and check for outdated packages',
+    parameters: {
+        type: 'object',
+        properties: {},
+    },
+    execute: async (_params: any, context?: ToolContext) => {
+        try {
+            const packageJsonPath = path.join(
+                context?.workingDirectory || process.cwd(),
+                'package.json'
+            );
+
+            const packageJson = JSON.parse(
+                await fs.readFile(packageJsonPath, 'utf8')
+            );
+
+            const deps = packageJson.dependencies || {};
+            const devDeps = packageJson.devDependencies || {};
+            const totalDeps = Object.keys(deps).length + Object.keys(devDeps).length;
+
+            // Check for outdated packages
+            let outdatedOutput = '';
+            try {
+                outdatedOutput = execSync('npm outdated --json', {
+                    encoding: 'utf8',
+                    cwd: context?.workingDirectory || process.cwd(),
+                });
+            } catch {
+                // npm outdated exits with code 1 if there are outdated packages
+            }
+
+            const outdated = outdatedOutput ? JSON.parse(outdatedOutput) : {};
+            const outdatedCount = Object.keys(outdated).length;
+
+            return {
+                success: true,
+                totalDependencies: totalDeps,
+                outdatedPackages: outdatedCount,
+                dependencies: Object.keys(deps),
+                devDependencies: Object.keys(devDeps),
+                outdatedDetails: outdated,
+            };
+        } catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    },
+};
+
+async function main() {
+    try {
+        console.log('🔧 Creating tool registry with custom tools...\n');
+
+        // Create tool registry
+        const registry = createToolRegistry({
+            workingDirectory: process.cwd(),
+        });
+
+        // Register custom tools
+        registry.register(checkTestCoverage);
+        registry.register(checkLinterErrors);
+        registry.register(analyzePackageDeps);
+
+        console.log('✅ Registered custom tools:');
+        console.log('   - check_test_coverage');
+        console.log('   - check_linter_errors');
+        console.log('   - analyze_package_dependencies');
+        console.log('');
+
+        // Create a conversation that uses these tools
+        const messages = [
+            {
+                role: 'system' as const,
+                content: `You are a code quality analyst. Use the available tools to assess the project's health.
+
+Your task:
+1. Check test coverage
+2. Check for linter errors
+3. Analyze package dependencies
+
+Then provide a summary report of the project's code quality status.`,
+            },
+            {
+                role: 'user' as const,
+                content: 'Please analyze the current project and provide a code quality report.',
+            },
+        ];
+
+        console.log('🤖 Running AI analysis with custom tools...\n');
+
+        const result = await runAgentic({
+            messages,
+            tools: registry,
+            model: 'gpt-4o-mini',
+            maxIterations: 10,
+        });
+
+        console.log('✨ Analysis Complete!\n');
+        console.log('═'.repeat(70));
+        console.log(result.finalMessage);
+        console.log('═'.repeat(70));
+        console.log('');
+        console.log(`📊 Tool calls made: ${result.toolCallsExecuted}`);
+        console.log(`🔄 Iterations: ${result.iterations}`);
+        console.log('');
+
+        // Show which tools were used
+        const toolUsage: Record<string, number> = {};
+        result.toolMetrics.forEach(metric => {
+            toolUsage[metric.name] = (toolUsage[metric.name] || 0) + 1;
+        });
+
+        console.log('🔧 Tools used:');
+        Object.entries(toolUsage).forEach(([tool, count]) => {
+            console.log(`   - ${tool}: ${count}x`);
+        });
+
+    } catch (error) {
+        console.error('❌ Error:', error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}
+
+main();
+

package/examples/README.md

@@ -0,0 +1,320 @@
+# Examples
+
+This directory contains practical examples demonstrating how to use `@eldrforge/ai-service` as a standalone library.
+
+## Prerequisites
+
+Before running these examples, ensure you have:
+
+1. **Node.js** (v18 or later)
+2. **OpenAI API Key** set as environment variable:
+   ```bash
+   export OPENAI_API_KEY=sk-...
+   ```
+3. **tsx** for running TypeScript (or compile with `tsc` first):
+   ```bash
+   npm install -g tsx
+   ```
+
+## Examples Overview
+
+### 1. Simple Commit Message Generation
+**File:** `01-simple-commit.ts`
+
+The most basic example - generates a commit message from staged git changes.
+
+```bash
+# Stage some changes
+git add .
+
+# Run the example
+npx tsx examples/01-simple-commit.ts
+```
+
+**Features:**
+- Reads staged git changes
+- Generates commit message using agentic AI
+- Shows tool usage statistics
+- Suggests commit splits if appropriate
+
+**Use Case:** Quick commit message generation without interaction
+
+---
+
+### 2. Release Notes Generation
+**File:** `02-release-notes.ts`
+
+Generates comprehensive release notes by analyzing changes between two git references.
+
+```bash
+# Generate release notes from v1.0.0 to v1.1.0
+npx tsx examples/02-release-notes.ts v1.0.0 v1.1.0
+
+# Or from a tag to HEAD
+npx tsx examples/02-release-notes.ts v1.0.0 HEAD
+```
+
+**Features:**
+- Analyzes commit history and diffs
+- Uses 13 specialized tools for deep analysis
+- Generates detailed markdown release notes
+- Saves output to files
+- Shows tool usage metrics
+
+**Use Case:** Automated release note generation for GitHub releases, changelogs, etc.
+
+---
+
+### 3. Interactive Commit Workflow
+**File:** `03-interactive-commit.ts`
+
+An interactive workflow that lets users review, edit, and approve commit messages.
+
+```bash
+# Stage changes first
+git add .
+
+# Run interactive workflow
+npx tsx examples/03-interactive-commit.ts
+```
+
+**Features:**
+- Generates initial commit message
+- Interactive review loop:
+  - **[c]** Confirm and create commit
+  - **[e]** Edit in your editor
+  - **[s]** Skip and cancel
+- Automatically creates the git commit
+- Full TTY support
+
+**Use Case:** Daily development workflow with human oversight
+
+**Requirements:** Must run in a terminal (TTY), not in piped or non-interactive environments.
+
+---
+
+### 4. Custom Storage Adapter
+**File:** `04-custom-storage.ts`
+
+Demonstrates how to implement custom storage adapters for saving AI-generated content.
+
+```bash
+npx tsx examples/04-custom-storage.ts
+```
+
+**Features:**
+- Custom storage adapter implementation
+- Structured output directory
+- Saves multiple artifacts:
+  - Commit message
+  - Metadata (JSON)
+  - Tool metrics (JSON)
+- Example cloud storage adapter structure
+- Timestamped output organization
+
+**Use Case:**
+- Integrating with cloud storage (S3, Google Cloud Storage)
+- Saving AI artifacts for auditing
+- Custom file organization
+
+---
+
+### 5. Custom Tool Integration
+**File:** `05-custom-tools.ts`
+
+Shows how to create and register custom tools that extend the AI's capabilities.
+
+```bash
+npx tsx examples/05-custom-tools.ts
+```
+
+**Features:**
+- Three custom tools:
+  - `check_test_coverage` - Analyze test coverage
+  - `check_linter_errors` - Find ESLint errors
+  - `analyze_package_dependencies` - Check dependencies
+- Tool registry management
+- Custom AI workflows
+- Code quality analysis example
+
+**Use Case:**
+- Domain-specific code analysis
+- Custom CI/CD integrations
+- Project-specific quality checks
+
+---
+
+## Running the Examples
+
+### Option 1: Using tsx (Recommended)
+
+```bash
+# Run directly with tsx
+npx tsx examples/01-simple-commit.ts
+```
+
+### Option 2: Compile then run
+
+```bash
+# Compile TypeScript
+npx tsc examples/*.ts --outDir examples/dist
+
+# Run compiled JavaScript
+node examples/dist/01-simple-commit.js
+```
+
+### Option 3: Install tsx globally
+
+```bash
+# Install tsx globally
+npm install -g tsx
+
+# Run examples
+tsx examples/01-simple-commit.ts
+```
+
+## Configuration
+
+All examples can be configured by:
+
+1. **Environment Variables:**
+   ```bash
+   export OPENAI_API_KEY=sk-...
+   export EDITOR=code --wait
+   ```
+
+2. **Modifying the code:**
+   - Change `model` parameter (e.g., `gpt-4o-mini`, `gpt-4o`)
+   - Adjust `maxIterations` for more/less thorough analysis
+   - Add custom logic specific to your needs
+
+## Integration Patterns
+
+### As a CLI Tool
+
+Add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "commit": "tsx examples/01-simple-commit.ts",
+    "release": "tsx examples/02-release-notes.ts"
+  }
+}
+```
+
+Then use:
+```bash
+npm run commit
+npm run release v1.0.0 v1.1.0
+```
+
+### In Your Own Scripts
+
+```typescript
+import { runAgenticCommit } from '@eldrforge/ai-service';
+
+// Your custom logic here
+const result = await runAgenticCommit({
+  changedFiles,
+  diffContent,
+  model: 'gpt-4o-mini',
+});
+
+// Do something with result.commitMessage
+```
+
+### In a Web Service
+
+```typescript
+import express from 'express';
+import { runAgenticCommit } from '@eldrforge/ai-service';
+
+const app = express();
+
+app.post('/api/commit-message', async (req, res) => {
+  const { changedFiles, diffContent } = req.body;
+
+  const result = await runAgenticCommit({
+    changedFiles,
+    diffContent,
+    model: 'gpt-4o-mini',
+  });
+
+  res.json({ message: result.commitMessage });
+});
+```
+
+## Cost Considerations
+
+Approximate token usage and costs (as of 2024, with GPT-4o):
+
+| Example | Tokens | Est. Cost | Time |
+|---------|--------|-----------|------|
+| Simple Commit | 5,000-20,000 | $0.05-$0.20 | 10-30s |
+| Release Notes | 20,000-100,000 | $0.20-$1.00 | 30-180s |
+| Interactive Commit | 5,000-30,000 | $0.05-$0.30 | 10-60s |
+| Custom Storage | 5,000-20,000 | $0.05-$0.20 | 10-30s |
+| Custom Tools | 10,000-40,000 | $0.10-$0.40 | 20-60s |
+
+Use `gpt-4o-mini` for 60% cost reduction with slightly lower quality.
+
+## Troubleshooting
+
+### "OpenAI API key not found"
+
+Set your API key:
+```bash
+export OPENAI_API_KEY=sk-...
+```
+
+### "No staged changes found"
+
+Stage changes first:
+```bash
+git add .
+# or
+git add <specific-files>
+```
+
+### "Interactive mode requires a terminal"
+
+Examples 03 requires a real terminal. Don't pipe input or run in CI. Use example 01 instead for non-interactive use.
+
+### "Invalid git reference"
+
+Ensure the git references exist:
+```bash
+git tag  # List available tags
+git log --oneline  # See commits
+```
+
+### npm/npx issues
+
+Install dependencies:
+```bash
+npm install @eldrforge/ai-service openai @riotprompt/riotprompt
+```
+
+## Next Steps
+
+After exploring these examples:
+
+1. **Integrate into your workflow** - Add to package.json scripts
+2. **Customize for your needs** - Modify models, parameters, prompts
+3. **Create custom tools** - Extend with domain-specific capabilities
+4. **Build automation** - Use in CI/CD pipelines
+5. **Explore the API** - See [main README](../README.md) for full API documentation
+
+## Additional Resources
+
+- [Main README](../README.md) - Full API documentation
+- [OpenAI API Docs](https://platform.openai.com/docs) - OpenAI reference
+- [kodrdriv](https://github.com/calenvarek/kodrdriv) - Full automation toolkit
+
+## Questions or Issues?
+
+- 🐛 [Report bugs](https://github.com/calenvarek/ai-service/issues)
+- 💬 [Discussions](https://github.com/calenvarek/ai-service/discussions)
+- 📖 [Documentation](../README.md)
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eldrforge/ai-service",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "AI-powered content generation for automation - OpenAI integration with structured prompts",
   "main": "dist/index.js",
   "type": "module",
@@ -11,7 +11,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "examples"
   ],
   "repository": {
     "type": "git",
@@ -42,7 +43,7 @@
   "author": "Calen Varek <calenvarek@gmail.com>",
   "license": "Apache-2.0",
   "dependencies": {
-    "@eldrforge/git-tools": "^0.1.11",
+    "@eldrforge/git-tools": "^0.1.14",
     "@riotprompt/riotprompt": "^0.0.8",
     "openai": "^6.3.0"
   },