@bcelep/capint 0.4.2 → 0.7.0

package/skills/cloudflare/references/ai-search/api.md

@@ -0,0 +1,87 @@
+# AI Search API Reference
+
+## Workers Binding
+
+```typescript
+const answer = await env.AI.autorag("instance-name").aiSearch(options);
+const results = await env.AI.autorag("instance-name").search(options);
+const instances = await env.AI.autorag("_").listInstances();
+```
+
+## aiSearch() Options
+
+```typescript
+interface AiSearchOptions {
+  query: string;                          // User query
+  model: string;                          // Workers AI model ID
+  system_prompt?: string;                 // LLM instructions
+  rewrite_query?: boolean;                // Fix typos (default: false)
+  max_num_results?: number;               // Max chunks (default: 10)
+  ranking_options?: { score_threshold?: number }; // 0.0-1.0 (default: 0.3)
+  reranking?: { enabled: boolean; model: string };
+  stream?: boolean;                       // Stream response (default: false)
+  filters?: Filter;                       // Metadata filters
+  page?: string;                          // Pagination token
+}
+```
+
+## Response
+
+```typescript
+interface AiSearchResponse {
+  search_query: string;      // Query used (rewritten if enabled)
+  response: string;          // AI-generated answer
+  data: SearchResult[];      // Retrieved chunks
+  has_more: boolean;
+  next_page?: string;
+}
+
+interface SearchResult {
+  id: string;
+  score: number;
+  content: string;
+  metadata: { filename: string; folder: string; timestamp: number };
+}
+```
+
+## Filters
+
+```typescript
+// Comparison
+{ column: "folder", operator: "gte", value: "docs/" }
+
+// Compound
+{ operator: "and", filters: [
+  { column: "folder", operator: "gte", value: "docs/" },
+  { column: "timestamp", operator: "gte", value: 1704067200 }
+]}
+```
+
+**Operators:** `eq`, `ne`, `gt`, `gte`, `lt`, `lte`
+
+**Built-in metadata:** `filename`, `folder`, `timestamp` (Unix seconds)
+
+## Streaming
+
+```typescript
+const stream = await env.AI.autorag("docs").aiSearch({ query, model, stream: true });
+return new Response(stream, { headers: { "Content-Type": "text/event-stream" } });
+```
+
+## Error Types
+
+| Error | Cause |
+|-------|-------|
+| `AutoRAGNotFoundError` | Instance doesn't exist |
+| `AutoRAGUnauthorizedError` | Invalid/missing token |
+| `AutoRAGValidationError` | Invalid parameters |
+
+## REST API
+
+```bash
+curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/autorag/rags/{NAME}/ai-search \
+  -H "Authorization: Bearer {TOKEN}" \
+  -d '{"query": "...", "model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast"}'
+```
+
+Requires Service API token with "AI Search - Read" permission.

package/skills/cloudflare/references/ai-search/configuration.md

@@ -0,0 +1,88 @@
+# AI Search Configuration
+
+## Worker Setup
+
+```jsonc
+// wrangler.jsonc
+{
+  "ai": { "binding": "AI" }
+}
+```
+
+```typescript
+interface Env {
+  AI: Ai;
+}
+
+const answer = await env.AI.autorag("my-instance").aiSearch({
+  query: "How do I configure caching?",
+  model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast"
+});
+```
+
+## Data Sources
+
+### R2 Bucket
+
+Dashboard: AI Search → Create Instance → Select R2 bucket
+
+**Supported formats:** `.md`, `.txt`, `.html`, `.pdf`, `.doc`, `.docx`, `.csv`, `.json`
+
+**Auto-indexed metadata:** `filename`, `folder`, `timestamp`
+
+### Website Crawler
+
+Requirements:
+- Domain on Cloudflare
+- `sitemap.xml` at root
+- Bot protection must allow `CloudflareAISearch` user agent
+
+## Path Filtering (R2)
+
+```
+docs/**/*.md          # All .md in docs/ recursively
+**/*.draft.md         # Exclude (use in exclude patterns)
+```
+
+## Indexing
+
+- **Automatic:** Every 6 hours
+- **Force Sync:** Dashboard button (30s rate limit between syncs)
+- **Pause:** Settings → Pause Indexing (existing index remains searchable)
+
+## Service API Token
+
+Dashboard: AI Search → Instance → Use AI Search → API → Create Token
+
+Permissions:
+- **Read** - search operations
+- **Edit** - instance management
+
+Store securely:
+```bash
+wrangler secret put AI_SEARCH_TOKEN
+```
+
+## Multi-Environment
+
+```toml
+# wrangler.toml
+[env.production.vars]
+AI_SEARCH_INSTANCE = "prod-docs"
+
+[env.staging.vars]
+AI_SEARCH_INSTANCE = "staging-docs"
+```
+
+```typescript
+const answer = await env.AI.autorag(env.AI_SEARCH_INSTANCE).aiSearch({ query });
+```
+
+## Monitoring
+
+```typescript
+const instances = await env.AI.autorag("_").listInstances();
+console.log(instances.find(i => i.name === "docs"));
+```
+
+Dashboard shows: files indexed, status, last index time, storage usage.

package/skills/cloudflare/references/ai-search/gotchas.md

@@ -0,0 +1,81 @@
+# AI Search Gotchas
+
+## Type Safety
+
+**Timestamp precision:** Use seconds (10-digit), not milliseconds.
+```typescript
+const nowInSeconds = Math.floor(Date.now() / 1000); // Correct
+```
+
+**Folder prefix matching:** Use `gte` for "starts with" on paths.
+```typescript
+filters: { column: "folder", operator: "gte", value: "docs/api/" } // Matches nested
+```
+
+## Filter Limitations
+
+| Limit | Value |
+|-------|-------|
+| Max nesting depth | 2 levels |
+| Filters per compound | 10 |
+| `or` operator | Same column, `eq` only |
+
+**OR restriction example:**
+```typescript
+// ✅ Valid: same column, eq only
+{ operator: "or", filters: [
+  { column: "folder", operator: "eq", value: "docs/" },
+  { column: "folder", operator: "eq", value: "guides/" }
+]}
+```
+
+## Indexing Issues
+
+| Problem | Cause | Solution |
+|---------|-------|----------|
+| File not indexed | Unsupported format or >4MB | Check format (.md/.txt/.html/.pdf/.doc/.csv/.json) |
+| Index out of sync | 6-hour index cycle | Wait or use "Force Sync" (30s rate limit) |
+| Empty results | Index incomplete | Check dashboard for indexing status |
+
+## Auth Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `AutoRAGUnauthorizedError` | Invalid/missing token | Create Service API token with AI Search permissions |
+| `AutoRAGNotFoundError` | Wrong instance name | Verify exact name from dashboard |
+
+## Performance
+
+**Slow responses (>3s):**
+```typescript
+// Add score threshold + limit results
+ranking_options: { score_threshold: 0.5 },
+max_num_results: 10
+```
+
+**Empty results debug:**
+1. Remove filters, test basic query
+2. Lower `score_threshold` to 0.1
+3. Check index is populated
+
+## Limits
+
+| Resource | Limit |
+|----------|-------|
+| Instances per account | 10 |
+| Files per instance | 100,000 |
+| Max file size | 4 MB |
+| Index frequency | 6 hours |
+
+## Anti-Patterns
+
+**Use env vars for instance names:**
+```typescript
+const answer = await env.AI.autorag(env.AI_SEARCH_INSTANCE).aiSearch({...});
+```
+
+**Handle specific error types:**
+```typescript
+if (error instanceof AutoRAGNotFoundError) { /* 404 */ }
+if (error instanceof AutoRAGUnauthorizedError) { /* 401 */ }
+```

package/skills/cloudflare/references/ai-search/patterns.md

@@ -0,0 +1,85 @@
+# AI Search Patterns
+
+## search() vs aiSearch()
+
+| Use | Method | Returns |
+|-----|--------|---------|
+| Custom UI, analytics | `search()` | Raw chunks only (~100-300ms) |
+| Chatbots, Q&A | `aiSearch()` | AI response + chunks (~500-2000ms) |
+
+## rewrite_query
+
+| Setting | Use When |
+|---------|----------|
+| `true` | User input (typos, vague queries) |
+| `false` | LLM-generated queries (already optimized) |
+
+## Multitenancy (Folder-Based)
+
+```typescript
+const answer = await env.AI.autorag("saas-docs").aiSearch({
+  query: "refund policy",
+  model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+  filters: {
+    column: "folder",
+    operator: "gte",  // "starts with" pattern
+    value: `tenants/${tenantId}/`
+  }
+});
+```
+
+## Streaming
+
+```typescript
+const stream = await env.AI.autorag("docs").aiSearch({
+  query, model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast", stream: true
+});
+return new Response(stream, { headers: { "Content-Type": "text/event-stream" } });
+```
+
+## Score Threshold
+
+| Threshold | Use |
+|-----------|-----|
+| 0.3 (default) | Broad recall, exploratory |
+| 0.5 | Balanced, production default |
+| 0.7 | High precision, critical accuracy |
+
+## System Prompt Template
+
+```typescript
+const systemPrompt = `You are a documentation assistant.
+- Answer ONLY based on provided context
+- If context doesn't contain answer, say "I don't have information"
+- Include code examples from context`;
+```
+
+## Compound Filters
+
+```typescript
+// OR: Multiple folders
+filters: {
+  operator: "or",
+  filters: [
+    { column: "folder", operator: "gte", value: "docs/api/" },
+    { column: "folder", operator: "gte", value: "docs/auth/" }
+  ]
+}
+
+// AND: Folder + date
+filters: {
+  operator: "and",
+  filters: [
+    { column: "folder", operator: "gte", value: "docs/" },
+    { column: "timestamp", operator: "gte", value: oneWeekAgoSeconds }
+  ]
+}
+```
+
+## Reranking
+
+Enable for high-stakes use cases (adds ~300ms latency):
+
+```typescript
+reranking: { enabled: true, model: "@cf/baai/bge-reranker-base" }
+```

package/skills/cloudflare/references/analytics-engine/README.md

@@ -0,0 +1,94 @@
+# Cloudflare Workers Analytics Engine Reference
+
+Expert guidance for implementing unlimited-cardinality analytics at scale using Cloudflare Workers Analytics Engine.
+
+## What is Analytics Engine?
+
+Time-series analytics database designed for high-cardinality data (millions of unique dimensions). Write data points from Workers, query via SQL API. Use for:
+- Custom user-facing analytics dashboards
+- Usage-based billing & metering
+- Per-customer/per-feature monitoring
+- High-frequency instrumentation without performance impact
+
+**Key Capability:** Track metrics with unlimited unique values (e.g., millions of user IDs, API keys) without performance degradation.
+
+## Core Concepts
+
+| Concept | Description | Example |
+|---------|-------------|---------|
+| **Dataset** | Logical table for related metrics | `api_requests`, `user_events` |
+| **Data Point** | Single measurement with timestamp | One API request's metrics |
+| **Blobs** | String dimensions (max 20) | endpoint, method, status, user_id |
+| **Doubles** | Numeric values (max 20) | latency_ms, request_count, bytes |
+| **Indexes** | Filtered blobs for efficient queries | customer_id, api_key |
+
+## Reading Order
+
+| Task | Start Here | Then Read |
+|------|------------|-----------|
+| **First-time setup** | [configuration.md](configuration.md) → [api.md](api.md) → [patterns.md](patterns.md) | |
+| **Writing data** | [api.md](api.md) → [gotchas.md](gotchas.md) (sampling) | |
+| **Querying data** | [api.md](api.md) (SQL API) → [patterns.md](patterns.md) (examples) | |
+| **Debugging** | [gotchas.md](gotchas.md) → [api.md](api.md) (limits) | |
+| **Optimization** | [patterns.md](patterns.md) (anti-patterns) → [gotchas.md](gotchas.md) | |
+
+## When to Use Analytics Engine
+
+```
+Need to track metrics? → Yes
+  ↓
+Millions of unique dimension values? → Yes
+    ↓
+  Need real-time queries? → Yes
+      ↓
+    Use Analytics Engine ✓
+
+Alternative scenarios:
+- Low cardinality (<10k unique values) → Workers Analytics (free tier)
+- Complex joins/relations → D1 Database
+- Logs/debugging → Tail Workers (logpush)
+- External tools → Send to external analytics (Datadog, etc.)
+```
+
+## Quick Start
+
+1. Add binding to `wrangler.jsonc`:
+```jsonc
+{
+  "analytics_engine_datasets": [
+    { "binding": "ANALYTICS", "dataset": "my_events" }
+  ]
+}
+```
+
+2. Write data points (fire-and-forget, no await):
+```typescript
+env.ANALYTICS.writeDataPoint({
+  blobs: ["/api/users", "GET", "200"],
+  doubles: [145.2, 1],  // latency_ms, count
+  indexes: [customerId]
+});
+```
+
+3. Query via SQL API (HTTP):
+```sql
+SELECT blob1, SUM(double2) AS total_requests
+FROM my_events
+WHERE index1 = 'customer_123'
+  AND timestamp >= NOW() - INTERVAL '7' DAY
+GROUP BY blob1
+ORDER BY total_requests DESC
+```
+
+## In This Reference
+
+- **[configuration.md](configuration.md)** - Setup, bindings, TypeScript types, limits
+- **[api.md](api.md)** - `writeDataPoint()`, SQL API, query syntax
+- **[patterns.md](patterns.md)** - Use cases, examples, anti-patterns
+- **[gotchas.md](gotchas.md)** - Sampling, index selection, troubleshooting
+
+## See Also
+
+- [Cloudflare Analytics Engine Docs](https://developers.cloudflare.com/analytics/analytics-engine/)
+- [GraphQL Analytics API Reference](../graphql-api/) - Query built-in Cloudflare analytics (HTTP, Workers, DNS, Firewall, etc.)
+- [Observability Reference](../observability/) - Workers Logs, Traces, and real-time debugging

package/skills/cloudflare/references/analytics-engine/api.md

@@ -0,0 +1,112 @@
+# Analytics Engine API Reference
+
+## Writing Data
+
+### `writeDataPoint()`
+
+Fire-and-forget (returns `void`, not Promise). Writes happen asynchronously.
+
+```typescript
+interface AnalyticsEngineDataPoint {
+  blobs?: string[];      // Up to 20 strings (dimensions), 16KB each
+  doubles?: number[];    // Up to 20 numbers (metrics)
+  indexes?: string[];    // 1 indexed string for high-cardinality filtering
+}
+
+env.ANALYTICS.writeDataPoint({
+  blobs: ["/api/users", "GET", "200"],
+  doubles: [145.2, 1],  // latency_ms, count
+  indexes: ["customer_abc123"]
+});
+```
+
+**Behaviors:** No await needed, no error thrown (check tail logs), auto-sampled at high volumes, auto-timestamped.
+
+**Blob vs Index:** Blob for GROUP BY (<100k unique), Index for filter-only (millions unique).
+
+### Full Example
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const start = Date.now();
+    const url = new URL(request.url);
+    try {
+      const response = await handleRequest(request);
+      env.ANALYTICS.writeDataPoint({
+        blobs: [url.pathname, request.method, response.status.toString()],
+        doubles: [Date.now() - start, 1],
+        indexes: [request.headers.get("x-api-key") || "anonymous"]
+      });
+      return response;
+    } catch (error) {
+      env.ANALYTICS.writeDataPoint({
+        blobs: [url.pathname, request.method, "500"],
+        doubles: [Date.now() - start, 1, 0],
+      });
+      throw error;
+    }
+  }
+};
+```
+
+## SQL API (External Only)
+
+```bash
+curl -X POST https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql \
+  -H "Authorization: Bearer $TOKEN" \
+  -d "SELECT blob1 AS endpoint, COUNT(*) AS requests FROM dataset WHERE timestamp >= NOW() - INTERVAL '1' HOUR GROUP BY blob1"
+```
+
+### Column References
+
+```sql
+-- blob1..blob20, double1..double20, index1, timestamp
+SELECT blob1 AS endpoint, SUM(double1) AS latency, COUNT(*) AS requests
+FROM my_dataset
+WHERE index1 = 'customer_123' AND timestamp >= NOW() - INTERVAL '7' DAY
+GROUP BY blob1
+HAVING COUNT(*) > 100
+ORDER BY requests DESC LIMIT 100
+```
+
+**Aggregations:** `SUM()`, `AVG()`, `COUNT()`, `MIN()`, `MAX()`, `quantile(0.95)()`
+
+**Time ranges:** `NOW() - INTERVAL '1' HOUR`, `BETWEEN '2026-01-01' AND '2026-01-31'`
+
+### Query Examples
+
+```sql
+-- Top endpoints
+SELECT blob1, COUNT(*) AS requests, AVG(double1) AS avg_latency
+FROM api_requests WHERE timestamp >= NOW() - INTERVAL '24' HOUR
+GROUP BY blob1 ORDER BY requests DESC LIMIT 20
+
+-- Error rate
+SELECT blob1, COUNT(*) AS total,
+  SUM(CASE WHEN blob3 LIKE '5%' THEN 1 ELSE 0 END) AS errors
+FROM api_requests WHERE timestamp >= NOW() - INTERVAL '1' HOUR
+GROUP BY blob1 HAVING total > 50
+
+-- P95 latency
+SELECT blob1, quantile(0.95)(double1) AS p95
+FROM api_requests GROUP BY blob1
+```
+
+## Response Format
+
+```json
+{"data": [{"endpoint": "/api/users", "requests": 1523}], "rows": 2}
+```
+
+## Limits
+
+| Resource | Limit |
+|----------|-------|
+| Blobs/Doubles per point | 20 each |
+| Indexes per point | 1 |
+| Blob/Index size | 16KB |
+| Data retention | 90 days |
+| Query timeout | 30s |
+
+**Critical:** High write volumes (>1M/min) trigger automatic sampling.

package/skills/cloudflare/references/analytics-engine/configuration.md

@@ -0,0 +1,112 @@
+# Analytics Engine Configuration
+
+## Setup
+
+1. Add binding to `wrangler.jsonc`
+2. Deploy Worker
+3. Dataset created automatically on first write
+4. Query via SQL API
+
+## wrangler.jsonc
+
+```jsonc
+{
+  "name": "my-worker",
+  "analytics_engine_datasets": [
+    { "binding": "ANALYTICS", "dataset": "my_events" }
+  ]
+}
+```
+
+Multiple datasets for separate concerns:
+```jsonc
+{
+  "analytics_engine_datasets": [
+    { "binding": "API_ANALYTICS", "dataset": "api_requests" },
+    { "binding": "USER_EVENTS", "dataset": "user_activity" }
+  ]
+}
+```
+
+## TypeScript
+
+```typescript
+interface Env {
+  ANALYTICS: AnalyticsEngineDataset;
+}
+
+export default {
+  async fetch(request: Request, env: Env) {
+    // No await - returns void, fire-and-forget
+    env.ANALYTICS.writeDataPoint({
+      blobs: [pathname, method, status],      // String dimensions (max 20)
+      doubles: [latency, 1],                   // Numeric metrics (max 20)
+      indexes: [apiKey]                        // High-cardinality filter (max 1)
+    });
+    return response;
+  }
+};
+```
+
+## Data Point Limits
+
+| Field | Limit | SQL Access |
+|-------|-------|------------|
+| blobs | 20 strings, 16KB each | `blob1`...`blob20` |
+| doubles | 20 numbers | `double1`...`double20` |
+| indexes | 1 string, 16KB | `index1` |
+
+## Write Behavior
+
+| Scenario | Behavior |
+|----------|----------|
+| <1M writes/min | All accepted |
+| >1M writes/min | Automatic sampling |
+| Invalid data | Silent failure (check tail logs) |
+
+**Mitigate sampling:** Pre-aggregate, use multiple datasets, write only critical metrics.
+
+## Query Limits
+
+| Resource | Limit |
+|----------|-------|
+| Query timeout | 30 seconds |
+| Data retention | 90 days (default) |
+| Result size | ~10MB |
+
+## Cost
+
+**Free tier:** 10M writes/month, 1M reads/month
+
+**Paid:** $0.05 per 1M writes, $1.00 per 1M reads
+
+## Environment-Specific
+
+```jsonc
+{
+  "analytics_engine_datasets": [
+    { "binding": "ANALYTICS", "dataset": "prod_events" }
+  ],
+  "env": {
+    "staging": {
+      "analytics_engine_datasets": [
+        { "binding": "ANALYTICS", "dataset": "staging_events" }
+      ]
+    }
+  }
+}
+```
+
+## Monitoring
+
+```bash
+npx wrangler tail  # Check for sampling/write errors
+```
+
+```sql
+-- Check write activity
+SELECT DATE_TRUNC('hour', timestamp) AS hour, COUNT(*) AS writes
+FROM my_dataset
+WHERE timestamp >= NOW() - INTERVAL '24' HOUR
+GROUP BY hour
+```