@stephen-lord/docs 1.0.0 → 1.0.1

package/dist-docs/Agent-Skills-for-Context-Engineering/examples/llm-as-judge-skills/tools/research/read-url.md

@@ -0,0 +1,162 @@
+# Read URL Tool
+
+## Purpose
+
+Extract and parse content from a given URL. Returns structured text content with metadata about the source.
+
+## Tool Definition
+
+```typescript
+import { tool } from "ai";
+import { z } from "zod";
+
+export const readUrl = tool({
+  description: `Read and extract content from a URL.
+Returns the main text content, stripped of navigation and ads.
+Use after webSearch to get full content from relevant results.`,
+
+  parameters: z.object({
+    url: z.string().url()
+      .describe("The URL to read"),
+    
+    contentType: z.enum(["auto", "article", "documentation", "paper", "code"]).default("auto")
+      .describe("Hint for content type to optimize extraction"),
+    
+    maxLength: z.number().min(1000).max(50000).default(10000)
+      .describe("Maximum characters to return"),
+    
+    extractSections: z.boolean().default(true)
+      .describe("Whether to identify and label sections"),
+    
+    includeMetadata: z.boolean().default(true)
+      .describe("Include author, date, and other metadata")
+  }),
+
+  execute: async (input) => {
+    return extractUrlContent(input);
+  }
+});
+```
+
+## Input Schema
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| url | string | Yes | URL to read |
+| contentType | enum | No | Content type hint |
+| maxLength | number | No | Max chars (default: 10000) |
+| extractSections | boolean | No | Label sections |
+| includeMetadata | boolean | No | Include metadata |
+
+## Output Schema
+
+```typescript
+interface ReadUrlResult {
+  success: boolean;
+  
+  url: string;
+  title: string;
+  
+  content: {
+    full: string;
+    sections?: {
+      heading: string;
+      level: number;  // h1=1, h2=2, etc.
+      content: string;
+    }[];
+  };
+  
+  metadata?: {
+    author?: string;
+    publishedDate?: string;
+    lastModified?: string;
+    description?: string;
+    keywords?: string[];
+    source: string;
+  };
+  
+  stats: {
+    totalCharacters: number;
+    truncated: boolean;
+    sectionsFound: number;
+  };
+  
+  error?: {
+    code: string;
+    message: string;
+  };
+}
+```
+
+## Usage Example
+
+```typescript
+const content = await readUrl.execute({
+  url: "https://eugeneyan.com/writing/llm-evaluators/",
+  contentType: "article",
+  maxLength: 15000,
+  extractSections: true,
+  includeMetadata: true
+});
+
+// Result:
+// {
+//   success: true,
+//   url: "https://eugeneyan.com/writing/llm-evaluators/",
+//   title: "Evaluating the Effectiveness of LLM-Evaluators",
+//   content: {
+//     full: "LLM-evaluators, also known as LLM-as-a-Judge...",
+//     sections: [
+//       {
+//         heading: "Key considerations before adopting an LLM-evaluator",
+//         level: 2,
+//         content: "Before reviewing the literature..."
+//       },
+//       ...
+//     ]
+//   },
+//   metadata: {
+//     author: "Eugene Yan",
+//     publishedDate: "2024-06-15",
+//     source: "eugeneyan.com"
+//   },
+//   stats: {
+//     totalCharacters: 15000,
+//     truncated: true,
+//     sectionsFound: 8
+//   }
+// }
+```
+
+## Content Type Handling
+
+| Type | Optimization |
+|------|-------------|
+| article | Prioritize main content, skip sidebars |
+| documentation | Preserve code blocks, keep structure |
+| paper | Extract abstract, sections, references |
+| code | Preserve formatting, syntax highlighting |
+| auto | Detect type from content |
+
+## Error Handling
+
+```typescript
+const errorCodes = {
+  "URL_NOT_FOUND": "Page does not exist (404)",
+  "ACCESS_DENIED": "Page requires authentication (401/403)",
+  "TIMEOUT": "Request timed out",
+  "BLOCKED": "Access blocked by robots.txt or rate limit",
+  "INVALID_CONTENT": "Content could not be parsed",
+  "UNSUPPORTED_TYPE": "Content type not supported (e.g., binary)"
+};
+```
+
+## Implementation Notes
+
+1. **Respect robots.txt**: Check and honor robots.txt directives
+2. **Rate Limiting**: Don't hammer the same domain
+3. **User Agent**: Use appropriate user agent string
+4. **Timeouts**: Set reasonable timeouts (10-30s)
+5. **JavaScript Rendering**: Consider headless browser for JS-heavy sites
+6. **Caching**: Cache content for repeated reads
+

package/dist-docs/Agent-Skills-for-Context-Engineering/examples/llm-as-judge-skills/tools/research/web-search.md

@@ -0,0 +1,128 @@
+# Web Search Tool
+
+## Purpose
+
+Search the web for relevant information on a given topic. Returns structured results with snippets, URLs, and metadata.
+
+## Tool Definition
+
+```typescript
+import { tool } from "ai";
+import { z } from "zod";
+
+export const webSearch = tool({
+  description: `Search the web for information on a topic.
+Returns relevant results with snippets and URLs.
+Use for gathering current information, verifying facts, or research.`,
+
+  parameters: z.object({
+    query: z.string()
+      .describe("Search query - be specific for better results"),
+    
+    maxResults: z.number().min(1).max(20).default(10)
+      .describe("Maximum number of results to return"),
+    
+    filters: z.object({
+      dateRange: z.enum(["day", "week", "month", "year", "any"]).default("any")
+        .describe("Limit results to a time period"),
+      
+      sourceType: z.enum(["all", "news", "academic", "documentation"]).default("all")
+        .describe("Type of sources to prioritize"),
+      
+      excludeDomains: z.array(z.string()).optional()
+        .describe("Domains to exclude from results")
+    }).optional()
+  }),
+
+  execute: async (input) => {
+    return performWebSearch(input);
+  }
+});
+```
+
+## Input Schema
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| query | string | Yes | Search query |
+| maxResults | number | No | Max results (default: 10) |
+| filters.dateRange | enum | No | Time period filter |
+| filters.sourceType | enum | No | Source type priority |
+| filters.excludeDomains | string[] | No | Domains to exclude |
+
+## Output Schema
+
+```typescript
+interface WebSearchResult {
+  success: boolean;
+  
+  results: {
+    title: string;
+    url: string;
+    snippet: string;
+    source: string;      // Domain name
+    publishedDate?: string;
+    relevanceScore: number;
+  }[];
+  
+  totalResults: number;
+  
+  metadata: {
+    query: string;
+    searchTimeMs: number;
+    filtersApplied: string[];
+  };
+}
+```
+
+## Usage Example
+
+```typescript
+const results = await webSearch.execute({
+  query: "LLM-as-a-Judge evaluation methods 2024",
+  maxResults: 10,
+  filters: {
+    dateRange: "year",
+    sourceType: "academic"
+  }
+});
+
+// Result:
+// {
+//   success: true,
+//   results: [
+//     {
+//       title: "Judging LLM-as-a-Judge with MT-Bench",
+//       url: "https://arxiv.org/abs/...",
+//       snippet: "We study the effectiveness of LLM-as-a-Judge...",
+//       source: "arxiv.org",
+//       publishedDate: "2024-01-15",
+//       relevanceScore: 0.95
+//     },
+//     ...
+//   ],
+//   totalResults: 10,
+//   metadata: {
+//     query: "LLM-as-a-Judge evaluation methods 2024",
+//     searchTimeMs: 342,
+//     filtersApplied: ["dateRange:year", "sourceType:academic"]
+//   }
+// }
+```
+
+## Query Optimization Tips
+
+1. **Specific Terms**: Use precise terminology
+2. **Quotes**: Use quotes for exact phrases
+3. **Operators**: Support site:, -term, OR
+4. **Context**: Include relevant context terms
+5. **Recency**: Add year for recent info
+
+## Implementation Notes
+
+1. **Rate Limiting**: Implement appropriate rate limits
+2. **Caching**: Cache results for repeated queries
+3. **Result Quality**: Filter out low-quality sources
+4. **Error Handling**: Handle API failures gracefully
+5. **Privacy**: Log queries appropriately
+

package/dist-docs/Agent-Skills-for-Context-Engineering/examples/llm-as-judge-skills/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}
+

package/dist-docs/Agent-Skills-for-Context-Engineering/examples/llm-as-judge-skills/vitest.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts', 'tests/**/*.test.ts'],
+    setupFiles: ['./tests/setup.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: ['node_modules/', 'dist/', '**/*.test.ts', 'tests/setup.ts']
+    },
+    testTimeout: 60000, // 60s for LLM calls
+    hookTimeout: 30000,
+    // Retry failed tests once (helpful for flaky LLM calls)
+    retry: 1
+  }
+});
+