@hasna/connectors 1.3.45 → 1.4.0

package/connectors/weights-biases/CLAUDE.md

@@ -0,0 +1,65 @@
+# CLAUDE.md
+
+Guidance for Claude Code when working with the Weights & Biases connector.
+
+## Project Overview
+
+`@hasna/connect-weights-biases` is a TypeScript connector for the [Weights & Biases REST API](https://docs.wandb.ai/). It provides multi-profile configuration, API key authentication, and CLI commands for runs, events, search, and raw requests.
+
+## Build & Run Commands
+
+```bash
+bun install
+bun run dev
+bun run build
+bun run typecheck
+bun test
+```
+
+## Authentication
+
+API key authentication. Set credentials via:
+
+- Environment variable `WANDB_API_KEY`
+- Profile config: `weights-biases config set-key <key>`
+
+The HTTP client sends the key as `Authorization: Bearer <api_key>`.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `WANDB_API_KEY` | API key (overrides profile) |
+| `WANDB_BASE_URL` | Override base URL (default `https://api.wandb.ai/v1`) |
+
+## CLI Commands
+
+```bash
+weights-biases config show
+weights-biases config set-key <key>
+weights-biases runs list --entity <entity> --project <project>
+weights-biases runs get <runId>
+weights-biases runs create --body '<json>'
+weights-biases events list --run-id <runId>
+weights-biases search query --body '<json>'
+weights-biases request /runs -X GET
+```
+
+## Data Storage
+
+```
+~/.hasna/connectors/weights-biases/
+├── current_profile
+└── profiles/
+    └── default.json
+```
+
+## Project Structure
+
+```
+src/
+├── api/       # client, runs, events, search
+├── cli/       # Commander CLI
+├── types/
+└── utils/     # config, output
+```

package/connectors/weights-biases/README.md

@@ -0,0 +1,62 @@
+# @hasna/connect-weights-biases
+
+TypeScript connector for the [Weights & Biases](https://wandb.ai/) REST API — ML experiment tracking with runs, events, and search.
+
+## Install
+
+```bash
+bun add @hasna/connect-weights-biases
+```
+
+Or use via the main `@hasna/connectors` CLI/MCP.
+
+## Authentication
+
+Get an API key from [wandb.ai/authorize](https://wandb.ai/authorize).
+
+```bash
+export WANDB_API_KEY=your-api-key-here
+# or
+weights-biases config set-key your-api-key-here
+```
+
+## CLI
+
+```bash
+# Configuration
+weights-biases config show
+weights-biases profile list
+
+# Runs
+weights-biases runs list --entity my-team --project my-project
+weights-biases runs get <run-id>
+weights-biases runs create --body '{"entity":"team","project":"demo","displayName":"test"}'
+
+# Events
+weights-biases events list --run-id <run-id>
+
+# Search
+weights-biases search query --body '{"entity":"team","project":"demo","filters":{}}'
+
+# Raw request
+weights-biases request /runs -X GET --query '{"perPage":10}'
+```
+
+## Library
+
+```typescript
+import { WeightsBiases } from '@hasna/connect-weights-biases';
+
+const wb = WeightsBiases.fromEnv();
+const runs = await wb.runs.list({ entity: 'team', project: 'demo' });
+```
+
+## API base URL
+
+Default: `https://api.wandb.ai/v1`
+
+Override with `WANDB_BASE_URL` or `weights-biases config set-base-url`.
+
+## License
+
+Apache-2.0

package/connectors/weights-biases/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@hasna/connect-weights-biases",
+  "version": "0.1.0",
+  "description": "Weights & Biases API connector - ML experiment tracking (runs, events, search)",
+  "type": "module",
+  "bin": {
+    "weights-biases": "./bin/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun && bun build ./src/cli/index.ts --outdir ./bin --target bun",
+    "dev": "bun run ./src/cli/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "weights-biases",
+    "wandb",
+    "ml",
+    "experiment-tracking",
+    "api",
+    "connector",
+    "cli",
+    "typescript",
+    "bun",
+    "hasna"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/connectors.git"
+  }
+}

package/connectors/weights-biases/src/api/client.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test, mock, afterEach } from 'bun:test';
+import { WeightsBiasesClient } from './client';
+
+describe('WeightsBiasesClient', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    mock.restore();
+  });
+
+  test('sends Bearer auth header and builds /runs URL', async () => {
+    let capturedUrl = '';
+    let capturedHeaders: HeadersInit | undefined;
+
+    globalThis.fetch = mock(async (input: RequestInfo | URL, init?: RequestInit) => {
+      capturedUrl = String(input);
+      capturedHeaders = init?.headers;
+      return new Response(JSON.stringify({ runs: [] }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    }) as unknown as typeof fetch;
+
+    const client = new WeightsBiasesClient({ apiKey: 'test-key-12345' });
+    await client.get('/runs', { entity: 'team', project: 'demo' });
+
+    expect(capturedUrl).toBe('https://api.wandb.ai/v1/runs?entity=team&project=demo');
+    expect(capturedHeaders).toMatchObject({
+      Authorization: 'Bearer test-key-12345',
+      Accept: 'application/json',
+    });
+  });
+
+  test('uses custom base URL when configured', () => {
+    const client = new WeightsBiasesClient({
+      apiKey: 'key',
+      baseUrl: 'https://custom.example/v1',
+    });
+    expect(client.getBaseUrl()).toBe('https://custom.example/v1');
+  });
+
+  test('throws when API key is missing', () => {
+    expect(() => new WeightsBiasesClient({ apiKey: '' })).toThrow('API key is required');
+  });
+});

package/connectors/weights-biases/src/api/client.ts

@@ -0,0 +1,119 @@
+import type { WeightsBiasesConfig } from '../types';
+import { WeightsBiasesApiError } from '../types';
+
+const DEFAULT_BASE_URL = 'https://api.wandb.ai/v1';
+
+export interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  params?: Record<string, string | number | boolean | undefined>;
+  body?: Record<string, unknown> | unknown[] | string;
+  headers?: Record<string, string>;
+}
+
+export class WeightsBiasesClient {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+
+  constructor(config: WeightsBiasesConfig) {
+    if (!config.apiKey) {
+      throw new Error('API key is required');
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+  }
+
+  getBaseUrl(): string {
+    return this.baseUrl;
+  }
+
+  private buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {
+    const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+    const url = new URL(`${this.baseUrl}${normalizedPath}`);
+
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+
+    return url.toString();
+  }
+
+  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    const { method = 'GET', params, body, headers = {} } = options;
+    const url = this.buildUrl(path, params);
+
+    const requestHeaders: Record<string, string> = {
+      Authorization: `Bearer ${this.apiKey}`,
+      Accept: 'application/json',
+      ...headers,
+    };
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      requestHeaders['Content-Type'] = 'application/json';
+    }
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers: requestHeaders,
+    };
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
+    }
+
+    const response = await fetch(url, fetchOptions);
+
+    if (response.status === 204) {
+      return {} as T;
+    }
+
+    let data: unknown;
+    const contentType = response.headers.get('content-type') || '';
+
+    if (contentType.includes('application/json')) {
+      const text = await response.text();
+      if (text) {
+        try {
+          data = JSON.parse(text);
+        } catch {
+          data = text;
+        }
+      }
+    } else {
+      data = await response.text();
+    }
+
+    if (!response.ok) {
+      let errorMessage = String(data || response.statusText);
+      if (typeof data === 'object' && data !== null) {
+        const errorObj = data as { detail?: string; error?: string; message?: string };
+        errorMessage = errorObj.detail || errorObj.error || errorObj.message || JSON.stringify(data);
+      }
+      throw new WeightsBiasesApiError(errorMessage, response.status);
+    }
+
+    return data as T;
+  }
+
+  async get<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'GET', params });
+  }
+
+  async post<T>(
+    path: string,
+    body?: Record<string, unknown> | unknown[] | string | object,
+    params?: Record<string, string | number | boolean | undefined>,
+  ): Promise<T> {
+    return this.request<T>(path, { method: 'POST', body: body as Record<string, unknown>, params });
+  }
+
+  getApiKeyPreview(): string {
+    if (this.apiKey.length > 10) {
+      return `${this.apiKey.substring(0, 6)}...${this.apiKey.substring(this.apiKey.length - 4)}`;
+    }
+    return '***';
+  }
+}

package/connectors/weights-biases/src/api/events.ts

@@ -0,0 +1,18 @@
+import type { EventsListResponse } from '../types';
+import type { WeightsBiasesClient } from './client';
+
+export interface ListEventsParams {
+  entity?: string;
+  project?: string;
+  runId?: string;
+  perPage?: number;
+  [key: string]: string | number | boolean | undefined;
+}
+
+export class EventsApi {
+  constructor(private readonly client: WeightsBiasesClient) {}
+
+  list(params?: ListEventsParams): Promise<EventsListResponse> {
+    return this.client.get<EventsListResponse>('/events', params);
+  }
+}

package/connectors/weights-biases/src/api/index.ts

@@ -0,0 +1,56 @@
+import type { WeightsBiasesConfig } from '../types';
+import { WeightsBiasesClient } from './client';
+import { RunsApi } from './runs';
+import { EventsApi } from './events';
+import { SearchApi } from './search';
+
+export class WeightsBiases {
+  private readonly client: WeightsBiasesClient;
+
+  public readonly runs: RunsApi;
+  public readonly events: EventsApi;
+  public readonly search: SearchApi;
+
+  constructor(config: WeightsBiasesConfig) {
+    this.client = new WeightsBiasesClient(config);
+    this.runs = new RunsApi(this.client);
+    this.events = new EventsApi(this.client);
+    this.search = new SearchApi(this.client);
+  }
+
+  static fromEnv(): WeightsBiases {
+    const apiKey = process.env.WANDB_API_KEY;
+    if (!apiKey) {
+      throw new Error('WANDB_API_KEY environment variable is required');
+    }
+    return new WeightsBiases({
+      apiKey,
+      baseUrl: process.env.WANDB_BASE_URL,
+    });
+  }
+
+  getApiKeyPreview(): string {
+    return this.client.getApiKeyPreview();
+  }
+
+  getClient(): WeightsBiasesClient {
+    return this.client;
+  }
+
+  async rawRequest<T = unknown>(
+    path: string,
+    options: {
+      method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+      params?: Record<string, string | number | boolean | undefined>;
+      body?: Record<string, unknown> | unknown[] | string;
+      headers?: Record<string, string>;
+    } = {},
+  ): Promise<T> {
+    return this.client.request<T>(path, options);
+  }
+}
+
+export { WeightsBiasesClient } from './client';
+export { RunsApi } from './runs';
+export { EventsApi } from './events';
+export { SearchApi } from './search';

package/connectors/weights-biases/src/api/runs.ts

@@ -0,0 +1,28 @@
+import type { CreateRunParams, RunSummary, RunsListResponse } from '../types';
+import type { WeightsBiasesClient } from './client';
+
+export interface ListRunsParams {
+  entity?: string;
+  project?: string;
+  filters?: string;
+  order?: string;
+  perPage?: number;
+  [key: string]: string | number | boolean | undefined;
+}
+
+export class RunsApi {
+  constructor(private readonly client: WeightsBiasesClient) {}
+
+  list(params?: ListRunsParams): Promise<RunsListResponse> {
+    return this.client.get<RunsListResponse>('/runs', params);
+  }
+
+  get(runId: string): Promise<RunSummary> {
+    const encoded = encodeURIComponent(runId);
+    return this.client.get<RunSummary>(`/runs/${encoded}`);
+  }
+
+  create(body: CreateRunParams): Promise<RunSummary> {
+    return this.client.post<RunSummary>('/runs', body);
+  }
+}

package/connectors/weights-biases/src/api/search.ts

@@ -0,0 +1,10 @@
+import type { SearchRequest, SearchResponse } from '../types';
+import type { WeightsBiasesClient } from './client';
+
+export class SearchApi {
+  constructor(private readonly client: WeightsBiasesClient) {}
+
+  search(body: SearchRequest): Promise<SearchResponse> {
+    return this.client.post<SearchResponse>('/search', body);
+  }
+}