@future-explorer/lib 1.0.4

package/README.md

@@ -0,0 +1,120 @@
+# Future Explorer Lib
+
+Shared utilities and clients for Future Explorer projects.
+
+## Installation
+
+```bash
+npm install @future-explorer/lib
+```
+
+## GrokAiClient
+
+AI client for interacting with Grok (xAI) models with structured output support.
+
+### Basic Usage
+
+```typescript
+import { GrokAiClient } from '@future-explorer/lib';
+
+const client = new GrokAiClient({
+  apiKey: 'your-api-key', // or set XAI_API_KEY env var
+  temperature: 0.1,
+  maxTokens: 4096,
+  logger: console, // optional
+});
+
+interface PersonInfo {
+  name: string;
+  age: number;
+}
+
+const response = await client.getGenericStructuredResponse<PersonInfo>({
+  model: 'grok-2-latest',
+  messages: [
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'Extract data from this text...' }
+  ],
+  tools: [
+    {
+      type: 'function',
+      name: 'extract_info',
+      description: 'Extract structured information',
+      parameters: {
+        type: 'object',
+        properties: {
+          name: { type: 'string' },
+          age: { type: 'number' }
+        },
+        required: ['name', 'age']
+      }
+    }
+  ],
+});
+
+if (response) {
+  console.log(response.args); // { name: '...', age: ... }
+  console.log(response.functionName); // 'extract_info'
+}
+```
+
+### Constructor Options
+
+- `apiKey` (optional): xAI API key. Falls back to `XAI_API_KEY` env var
+- `temperature` (optional): Default temperature for requests (default: 0.1)
+- `maxTokens` (optional): Default max tokens (default: 4096)
+- `logger` (optional): Logger instance with `warn` and `error` methods
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+### Watch Mode
+
+```bash
+npm run watch
+```
+
+### Lint
+
+```bash
+npm run lint
+npm run lint:fix
+```
+
+### Local Development
+
+Link the package locally for testing in other projects:
+
+```bash
+./scripts/link-local.sh
+```
+
+Then in your project:
+
+```bash
+npm link @future-explorer/lib
+```
+
+## Publishing
+
+### Manual Publish
+
+```bash
+npm run build
+npm publish
+```
+
+### Using Script
+
+```bash
+./scripts/publish.sh [patch|minor|major]
+```
+
+## License
+
+ISC

package/dist/GrokAiClient.d.ts

@@ -0,0 +1,19 @@
+import { GetGenericStructuredResponse, GetGenericStructuredResponseArgs } from './types';
+export interface GrokAiClientOptions {
+    apiKey?: string;
+    temperature?: number;
+    maxTokens?: number;
+    logger?: {
+        warn: (message: string, ...args: any[]) => void;
+        error: (message: string, ...args: any[]) => void;
+    };
+}
+export declare class GrokAiClient {
+    private readonly xaiClient;
+    private temperature;
+    private maxTokens;
+    private logger?;
+    constructor(options?: GrokAiClientOptions);
+    getGenericStructuredResponse<T>(payload: GetGenericStructuredResponseArgs): Promise<GetGenericStructuredResponse<T> | null>;
+}
+//# sourceMappingURL=GrokAiClient.d.ts.map

package/dist/GrokAiClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GrokAiClient.d.ts","sourceRoot":"","sources":["../src/GrokAiClient.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,4BAA4B,EAAE,gCAAgC,EAAE,MAAM,SAAS,CAAC;AAEzF,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE;QACP,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;QAChD,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;KAClD,CAAC;CACH;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA+B;IACzD,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAC,CAAgC;gBAEnC,OAAO,GAAE,mBAAwB;IAahC,4BAA4B,CAAC,CAAC,EACzC,OAAO,EAAE,gCAAgC,GACxC,OAAO,CAAC,4BAA4B,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;CA2CnD"}

package/dist/GrokAiClient.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GrokAiClient = void 0;
+const xai_1 = require("@ai-sdk/xai");
+class GrokAiClient {
+    xaiClient;
+    temperature;
+    maxTokens;
+    logger;
+    constructor(options = {}) {
+        const key = options.apiKey || process.env.XAI_API_KEY;
+        if (!key) {
+            throw new Error('XAI_API_KEY is required (env var or constructor arg)');
+        }
+        this.xaiClient = (0, xai_1.createXai)({ apiKey: key });
+        this.temperature = options.temperature ?? 0.1;
+        this.maxTokens = options.maxTokens ?? 4096;
+        this.logger = options.logger;
+    }
+    async getGenericStructuredResponse(payload) {
+        const { model, messages, tools, toolChoice = { type: 'tool', toolName: 'auto' }, temperature = this.temperature, maxOutputTokens = this.maxTokens, } = payload;
+        try {
+            const result = await this.xaiClient.chat(model).doGenerate({
+                prompt: messages,
+                tools,
+                toolChoice,
+                temperature,
+                maxOutputTokens,
+            });
+            const toolsCallResult = result.content.find((item) => item.type === 'tool-call');
+            if (!toolsCallResult?.input) {
+                this.logger?.warn('The model did not call the function.');
+                return null;
+            }
+            const { input, toolName } = toolsCallResult;
+            try {
+                return {
+                    args: JSON.parse(input),
+                    functionName: toolName,
+                };
+            }
+            catch (e) {
+                throw new Error(`Failed to parse response as JSON: ${e}`);
+            }
+        }
+        catch (err) {
+            this.logger?.error('GrokAiClient error:', err);
+            throw err;
+        }
+    }
+}
+exports.GrokAiClient = GrokAiClient;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { GrokAiClient, GrokAiClientOptions } from './GrokAiClient';
+export { GetGenericStructuredResponse, GetGenericStructuredResponseArgs } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,4BAA4B,EAAE,gCAAgC,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GrokAiClient = void 0;
+var GrokAiClient_1 = require("./GrokAiClient");
+Object.defineProperty(exports, "GrokAiClient", { enumerable: true, get: function () { return GrokAiClient_1.GrokAiClient; } });

package/dist/types.d.ts

@@ -0,0 +1,17 @@
+import { LanguageModelV2Message } from '@ai-sdk/provider';
+export interface GetGenericStructuredResponseArgs {
+    model?: string;
+    messages: LanguageModelV2Message[];
+    tools?: any[];
+    toolChoice?: {
+        type: 'tool';
+        toolName: 'auto' | 'required' | string;
+    };
+    temperature?: number;
+    maxOutputTokens?: number;
+}
+export interface GetGenericStructuredResponse<T> {
+    args: T | null;
+    functionName: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,MAAM,WAAW,gCAAgC;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,sBAAsB,EAAE,CAAC;IACnC,KAAK,CAAC,EAAE,GAAG,EAAE,CAAC;IACd,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAAA;KAAE,CAAC;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,4BAA4B,CAAC,CAAC;IAC7C,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@future-explorer/lib",
+  "version": "1.0.4",
+  "description": "Shared utilities and clients for Future Explorer projects",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rimraf ./dist && tsc",
+    "prepublishOnly": "npm run build",
+    "watch": "tsc --watch",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix"
+  },
+  "keywords": [
+    "future-explorer",
+    "grok",
+    "ai-client"
+  ],
+  "author": "",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/future-explorer/future-explorer.git",
+    "directory": "future-explorer-lib"
+  },
+  "peerDependencies": {
+    "@ai-sdk/provider": "^2.0.0",
+    "@ai-sdk/xai": "^2.0.0"
+  },
+  "devDependencies": {
+    "@ai-sdk/provider": "^2.0.0",
+    "@ai-sdk/xai": "^2.0.31",
+    "@types/node": "^24.5.2",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.20.1",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-prettier": "^5.2.3",
+    "prettier": "^3.5.1",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.6.3"
+  }
+}