@fractalresearch/loop 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @fractalresearch/loop
+
+Fractal Loop SDK — Auto-instrument your AI application for recursive self-improvement.
+
+## Quick Start
+
+```bash
+npm install @fractalresearch/loop
+```
+
+```ts
+import { initialize } from "@fractalresearch/loop";
+
+// Call once at app startup, before any AI calls
+initialize({
+  apiKey: process.env.FRACTAL_API_KEY!,
+  appName: "my-ai-app",
+});
+```
+
+That's it. The SDK automatically instruments OpenAI, Anthropic, Cohere, and other LLM providers. Traces are sent to the Fractal platform where they're analyzed for improvement opportunities.
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | string | required | Your Fractal API key (`fr_live_...`) |
+| `baseUrl` | string | `https://fractalresearch.ai` | Fractal platform URL |
+| `appName` | string | `fractal-loop-app` | Your application name |
+| `disableBatch` | boolean | `false` | Disable span batching (for testing) |
+
+## How It Works
+
+1. **Instrument** — The SDK hooks into your LLM client libraries and captures every call as an OpenTelemetry span
+2. **Collect** — Spans are batched and sent to the Fractal `/api/v1/traces` endpoint
+3. **Analyze** — Fractal uses Claude to analyze trace patterns against your improvement target
+4. **Improve** — Fractal creates GitHub PRs with suggested code changes
+
+## Supported Providers
+
+- OpenAI
+- Anthropic
+- Cohere
+- Azure OpenAI
+- Amazon Bedrock
+- Google Vertex AI
+- Replicate
+- HuggingFace
+
+## Local Development
+
+If running Fractal locally:
+
+```ts
+initialize({
+  apiKey: "your-key",
+  baseUrl: "http://localhost:3000",
+  appName: "my-app",
+  disableBatch: true, // Send spans immediately
+});
+```

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+export interface LoopConfig {
+    /** Your Fractal API key (fr_live_...) */
+    apiKey: string;
+    /** Base URL of the Fractal platform (default: https://fractalresearch.ai) */
+    baseUrl?: string;
+    /** Name of your application */
+    appName?: string;
+    /** Disable batching for testing (default: false) */
+    disableBatch?: boolean;
+}
+/**
+ * Initialize the Fractal Loop SDK.
+ *
+ * Call this once at the entry point of your application, before any
+ * AI/LLM calls are made. The SDK auto-instruments OpenAI, Anthropic,
+ * Cohere, and other supported providers via Traceloop.
+ *
+ * @example
+ * ```ts
+ * import { initialize } from "@fractalresearch/loop";
+ *
+ * initialize({
+ *   apiKey: process.env.FRACTAL_API_KEY!,
+ *   appName: "my-ai-app",
+ * });
+ * ```
+ */
+export declare function initialize(config: LoopConfig): void;
+declare const _default: {
+    initialize: typeof initialize;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,71 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initialize = initialize;
+const traceloop = __importStar(require("@traceloop/node-server-sdk"));
+const exporter_trace_otlp_http_1 = require("@opentelemetry/exporter-trace-otlp-http");
+/**
+ * Initialize the Fractal Loop SDK.
+ *
+ * Call this once at the entry point of your application, before any
+ * AI/LLM calls are made. The SDK auto-instruments OpenAI, Anthropic,
+ * Cohere, and other supported providers via Traceloop.
+ *
+ * @example
+ * ```ts
+ * import { initialize } from "@fractalresearch/loop";
+ *
+ * initialize({
+ *   apiKey: process.env.FRACTAL_API_KEY!,
+ *   appName: "my-ai-app",
+ * });
+ * ```
+ */
+function initialize(config) {
+    const baseUrl = config.baseUrl || "https://fractalresearch.ai";
+    const endpoint = `${baseUrl}/api/v1/traces`;
+    const exporter = new exporter_trace_otlp_http_1.OTLPTraceExporter({
+        url: endpoint,
+        headers: {
+            Authorization: `Bearer ${config.apiKey}`,
+        },
+    });
+    traceloop.initialize({
+        appName: config.appName || "fractal-loop-app",
+        disableBatch: config.disableBatch ?? false,
+        exporter: exporter,
+    });
+}
+exports.default = { initialize };

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@fractalresearch/loop",
+  "version": "0.1.0",
+  "description": "Fractal Loop SDK - Auto-instrument your AI application for recursive improvement",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@traceloop/node-server-sdk": "^0.26.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.57.0",
+    "@opentelemetry/sdk-trace-base": "^1.30.0",
+    "@opentelemetry/sdk-trace-node": "^1.30.0",
+    "@opentelemetry/resources": "^1.30.0",
+    "@opentelemetry/semantic-conventions": "^1.28.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT"
+}