macrocosmos 1.2.12 → 1.2.14

package/README.md

@@ -15,7 +15,7 @@ npm install macrocosmos
 The Apex client provides an interface for accessing the Apex API for chat completions and web search.
 
 ```typescript
-import { ApexClient } from 'macrocosmos';
+import { ApexClient, DeepResearch } from 'macrocosmos';
 
 // Initialize the client
 const client = new ApexClient({ apiKey: 'your-api-key' });
@@ -33,6 +33,24 @@ const response = await client.chat.completions.create({
 const webResults = await client.webRetrieval({
   query: 'latest news about AI'
 });
+
+// Deep Researcher
+
+// Create DeepResearch instance
+const deepResearch = new DeepResearch(client);
+
+// Submit a deep research job
+const submittedResponse = await deepResearch.createJob({
+      messages: [
+      { role: "user",
+        content: `Can you propose a mechanism by which a decentralized network 
+        of AI agents could achieve provable alignment on abstract ethical principles 
+        without relying on human-defined ontologies or centralized arbitration?`},
+    ],
+    });
+
+// Get the results of a deep research job
+const polledResponse = await deepResearch.getJobResults(submittedResponse.jobId);
 ```
 
 ### Gravity Client

package/dist/README.md

@@ -15,7 +15,7 @@ npm install macrocosmos
 The Apex client provides an interface for accessing the Apex API for chat completions and web search.
 
 ```typescript
-import { ApexClient } from 'macrocosmos';
+import { ApexClient, DeepResearch } from 'macrocosmos';
 
 // Initialize the client
 const client = new ApexClient({ apiKey: 'your-api-key' });
@@ -33,6 +33,24 @@ const response = await client.chat.completions.create({
 const webResults = await client.webRetrieval({
   query: 'latest news about AI'
 });
+
+// Deep Researcher
+
+// Create DeepResearch instance
+const deepResearch = new DeepResearch(client);
+
+// Submit a deep research job
+const submittedResponse = await deepResearch.createJob({
+      messages: [
+      { role: "user",
+        content: `Can you propose a mechanism by which a decentralized network 
+        of AI agents could achieve provable alignment on abstract ethical principles 
+        without relying on human-defined ontologies or centralized arbitration?`},
+    ],
+    });
+
+// Get the results of a deep research job
+const polledResponse = await deepResearch.getJobResults(submittedResponse.jobId);
 ```
 
 ### Gravity Client

package/dist/__tests__/apex/client-chat.test.js

@@ -6,34 +6,32 @@ describe("ApexClient", () => {
     if (!API_KEY) {
         throw new Error("MACROCOSMOS_API_KEY environment variable is required");
     }
-    it("should make a streaming chat completion call", async () => {
-        // Create ApexClient
-        const client = new macrocosmos_1.ApexClient({
+    const messages = [
+        {
+            role: "user",
+            content: "What is the capital of France?",
+        },
+    ];
+    const samplingParameters = {
+        temperature: 0.7,
+        topP: 0.9,
+        maxNewTokens: 100,
+        doSample: true,
+    };
+    let client;
+    beforeEach(() => {
+        client = new macrocosmos_1.ApexClient({
             apiKey: API_KEY,
             appName: "apex-client.test.ts",
         });
-        // Create request with the proper message type
-        const messages = [
-            {
-                role: "user",
-                content: "What is the capital of France?",
-            },
-        ];
+    });
+    it("should make a streaming chat completion call", async () => {
         // Create streaming completion
         const result = await client.chat.completions.create({
             messages,
             stream: true,
-            samplingParameters: {
-                temperature: 0.7,
-                topP: 0.9,
-                maxNewTokens: 100,
-                doSample: true,
-            },
+            samplingParameters,
         });
-        // Check if it's a Stream
-        if (!(result instanceof macrocosmos_1.ApexStream)) {
-            throw new Error("Expected a Stream but got a regular response");
-        }
         // Handle streaming response
         let fullResponse = "";
         const stream = result;
@@ -48,35 +46,12 @@ describe("ApexClient", () => {
         expect(fullResponse.toLowerCase()).toContain("paris");
     }, 30000); // Increase timeout to 30 seconds for streaming
     it("should make a non-streaming chat completion call", async () => {
-        // Create ApexClient
-        const client = new macrocosmos_1.ApexClient({
-            apiKey: API_KEY,
-            appName: "apex-client.test.ts",
-        });
-        // Create request with the proper message type
-        const messages = [
-            {
-                role: "user",
-                content: "What is the capital of France?",
-            },
-        ];
         // Create non-streaming completion
-        const result = await client.chat.completions.create({
+        const response = await client.chat.completions.create({
             messages,
             stream: false,
-            samplingParameters: {
-                temperature: 0.7,
-                topP: 0.9,
-                maxNewTokens: 100,
-                doSample: true,
-            },
+            samplingParameters,
         });
-        // Check if it's a regular response
-        if (result instanceof macrocosmos_1.ApexStream) {
-            throw new Error("Expected a regular response but got a Stream");
-        }
-        // Cast to the correct type
-        const response = result;
         console.log("Response:", response.choices?.[0]?.message?.content);
         expect(response.choices?.[0]?.message?.content).toBeTruthy();
         expect(response.choices?.[0]?.message?.content?.toLowerCase()).toContain("paris");

package/dist/__tests__/apex/client-deep-researcher.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/apex/client-deep-researcher.test.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const Client_1 = require("../../lib/apex/Client");
+const DeepResearch_1 = require("../../lib/apex/DeepResearch");
+describe("DeepResearch", () => {
+    const API_KEY = process.env.MACROCOSMOS_API_KEY;
+    if (!API_KEY) {
+        throw new Error("MACROCOSMOS_API_KEY environment variable is required");
+    }
+    it("should create a deep research job", async () => {
+        // Create ApexClient
+        const client = new Client_1.ApexClient({
+            apiKey: API_KEY,
+            appName: "apex-client.test.ts",
+        });
+        // Create DeepResearch instance
+        const deepResearch = new DeepResearch_1.DeepResearch(client);
+        // Create test parameters, enter all DeepResearchJobParams fields for coverage
+        const params = {
+            messages: [
+                {
+                    role: "user",
+                    content: `Can you propose a mechanism by which a decentralized network 
+        of AI agents could achieve provable alignment on abstract ethical principles 
+        without relying on human-defined ontologies or centralized arbitration?`,
+                },
+            ],
+            model: "Default",
+            samplingParameters: {
+                temperature: 0.7,
+                topP: 0.95,
+                maxNewTokens: 100,
+                doSample: false,
+            },
+            seed: 42,
+            uids: [1, 2, 3],
+        };
+        // Submit the job
+        const response = await deepResearch.createJob(params);
+        // Verify response structure
+        expect(response).toBeDefined();
+        expect(typeof response.jobId).toBe("string");
+        expect(typeof response.status).toBe("string");
+        expect(typeof response.createdAt).toBe("string");
+        expect(typeof response.updatedAt).toBe("string");
+        // Log response for debugging
+        console.log("Create Job Response:", response);
+    }, 30000);
+    it("should get deep researcher job results", async () => {
+        // Create ApexClient
+        const client = new Client_1.ApexClient({
+            apiKey: API_KEY,
+            appName: "apex-client.test.ts",
+        });
+        // Create DeepResearch instance
+        const deepResearch = new DeepResearch_1.DeepResearch(client);
+        // First create a job. Use simple inputs as job creation is tested in the previous test.
+        const createParams = {
+            messages: [
+                {
+                    role: "user",
+                    content: `Can you propose a mechanism by which a decentralized network 
+          of AI agents could achieve provable alignment on abstract ethical principles 
+          without relying on human-defined ontologies or centralized arbitration?`,
+                },
+            ],
+        };
+        const createResponse = await deepResearch.createJob(createParams);
+        const jobId = createResponse.jobId;
+        // Then get the results
+        const response = await deepResearch.getJobResults(jobId);
+        // Verify response structure
+        expect(response).toBeDefined();
+        expect(response.jobId).toBe(jobId); // Job ID should match the one from the create response
+        expect(typeof response.status).toBe("string");
+        expect(typeof response.jobId).toBe("string");
+        expect(typeof response.createdAt).toBe("string");
+        expect(typeof response.updatedAt).toBe("string");
+        expect(Array.isArray(response.result)).toBe(true);
+        // Log response for debugging
+        console.log("Get Job Results Response:", response);
+    }, 60000); // Longer timeout for this test as it involves multiple API calls
+});

package/dist/lib/apex/Client.d.ts

@@ -1,11 +1,11 @@
-import { ApexServiceClient, ChatCompletionRequest as GeneratedChatCompletionRequest, ChatCompletionResponse, ChatCompletionChunkResponse, WebRetrievalRequest as GeneratedWebRetrievalRequest, WebRetrievalResponse, ChatMessage } from "../../generated/apex/v1/apex";
+import { ApexServiceClient, ChatCompletionRequest as GeneratedChatCompletionRequest, ChatCompletionResponse, ChatCompletionChunkResponse, WebRetrievalRequest as GeneratedWebRetrievalRequest, WebRetrievalResponse, ChatMessage, SubmitDeepResearcherJobResponse, GetDeepResearcherJobRequest, GetDeepResearcherJobResponse } from "../../generated/apex/v1/apex";
 import * as grpc from "@grpc/grpc-js";
 import { BaseClient, BaseClientOptions } from "../BaseClient";
 import { ApexStream } from "./Stream";
 import { MarkFieldsOptional } from "../util.types";
 type ChatCompletionRequest = MarkFieldsOptional<GeneratedChatCompletionRequest, "uids">;
 type WebRetrievalRequest = MarkFieldsOptional<GeneratedWebRetrievalRequest, "uids">;
-export { ApexStream, WebRetrievalRequest, WebRetrievalResponse, ChatCompletionRequest, ChatMessage, };
+export { ApexStream, WebRetrievalRequest, WebRetrievalResponse, ChatCompletionRequest, ChatMessage, SubmitDeepResearcherJobResponse, GetDeepResearcherJobRequest, GetDeepResearcherJobResponse, };
 interface ApexClientOptions extends BaseClientOptions {
     timeout?: number;
 }
@@ -16,6 +16,18 @@ export interface ApexProtoClient {
         new (address: string, credentials: grpc.ChannelCredentials): ApexService;
     };
 }
+export interface ChatCompletionsCreate {
+    (params: ChatCompletionRequest & {
+        stream: true;
+    }, 
+    /** options are not used, but are accepted for compatibility with the OpenAI API */
+    _options?: unknown): Promise<ApexStream<ChatCompletionChunkResponse>>;
+    (params: ChatCompletionRequest & {
+        stream?: false | undefined;
+    }, 
+    /** options are not used, but are accepted for compatibility with the OpenAI API */
+    _options?: unknown): Promise<ChatCompletionResponse>;
+}
 /**
  * Client for interacting with the Apex API
  * Provides OpenAI-compatible interface over gRPC
@@ -24,21 +36,29 @@ export declare class ApexClient extends BaseClient {
     private _grpcClient?;
     private defaultTimeout;
     constructor(options: ApexClientOptions, grpcClient?: ApexServiceClient);
-    private createGrpcClient;
+    protected createGrpcClient(): ApexServiceClient;
     /**
      * Get the default timeout for chat completions
      */
-    private getDefaultTimeout;
+    protected getDefaultTimeout(): number;
     /**
      * OpenAI-compatible chat completions API
      */
     chat: {
         completions: {
-            create: (params: ChatCompletionRequest, _options?: unknown) => Promise<ChatCompletionResponse | ApexStream<ChatCompletionChunkResponse>>;
+            create: ChatCompletionsCreate;
         };
     };
     /**
      * Web retrieval API for searching the internet
      */
     webRetrieval: (params: WebRetrievalRequest) => Promise<WebRetrievalResponse>;
+    /**
+     * Submit a deep researcher job
+     */
+    submitDeepResearcherJob: (params: ChatCompletionRequest) => Promise<SubmitDeepResearcherJobResponse>;
+    /**
+     * Get a deep researcher job
+     */
+    getDeepResearcherJob: (params: GetDeepResearcherJobRequest) => Promise<GetDeepResearcherJobResponse>;
 }

package/dist/lib/apex/Client.js

@@ -33,14 +33,41 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ApexClient = exports.ChatMessage = exports.WebRetrievalResponse = exports.ApexStream = void 0;
+exports.ApexClient = exports.GetDeepResearcherJobResponse = exports.GetDeepResearcherJobRequest = exports.SubmitDeepResearcherJobResponse = exports.ChatMessage = exports.WebRetrievalResponse = exports.ApexStream = void 0;
 const apex_1 = require("../../generated/apex/v1/apex");
 Object.defineProperty(exports, "WebRetrievalResponse", { enumerable: true, get: function () { return apex_1.WebRetrievalResponse; } });
 Object.defineProperty(exports, "ChatMessage", { enumerable: true, get: function () { return apex_1.ChatMessage; } });
+Object.defineProperty(exports, "SubmitDeepResearcherJobResponse", { enumerable: true, get: function () { return apex_1.SubmitDeepResearcherJobResponse; } });
+Object.defineProperty(exports, "GetDeepResearcherJobRequest", { enumerable: true, get: function () { return apex_1.GetDeepResearcherJobRequest; } });
+Object.defineProperty(exports, "GetDeepResearcherJobResponse", { enumerable: true, get: function () { return apex_1.GetDeepResearcherJobResponse; } });
 const grpc = __importStar(require("@grpc/grpc-js"));
 const BaseClient_1 = require("../BaseClient");
 const Stream_1 = require("./Stream");
 Object.defineProperty(exports, "ApexStream", { enumerable: true, get: function () { return Stream_1.ApexStream; } });
+function chatCompletionsCreate(params, _options) {
+    const client = this.createGrpcClient();
+    const requestParams = {
+        ...params,
+        uids: params.uids ?? [],
+        timeout: params.timeout || this.getDefaultTimeout(),
+    };
+    if (requestParams.stream) {
+        const stream = client.chatCompletionStream(requestParams);
+        const controller = new AbortController();
+        return Promise.resolve(Stream_1.ApexStream.fromGrpcStream(stream, controller));
+    }
+    else {
+        return new Promise((resolve, reject) => {
+            client.chatCompletion(requestParams, (error, response) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve(response);
+            });
+        });
+    }
+}
 /**
  * Client for interacting with the Apex API
  * Provides OpenAI-compatible interface over gRPC
@@ -53,36 +80,7 @@ class ApexClient extends BaseClient_1.BaseClient {
          */
         this.chat = {
             completions: {
-                create: async (params, _options) => {
-                    const client = this.createGrpcClient();
-                    // Apply default timeout if not specified in params
-                    const requestParams = {
-                        ...params,
-                        uids: params.uids ?? [],
-                        timeout: params.timeout || this.getDefaultTimeout(),
-                    };
-                    // Handle streaming vs non-streaming
-                    if (requestParams.stream) {
-                        // Create a streaming call
-                        const stream = client.chatCompletionStream(requestParams);
-                        // Create controller for abort capability
-                        const controller = new AbortController();
-                        // Return a Stream object that wraps the gRPC stream
-                        return Stream_1.ApexStream.fromGrpcStream(stream, controller);
-                    }
-                    else {
-                        // For non-streaming, return a promise that resolves with the completion
-                        return new Promise((resolve, reject) => {
-                            client.chatCompletion(requestParams, (error, response) => {
-                                if (error) {
-                                    reject(error);
-                                    return;
-                                }
-                                resolve(response);
-                            });
-                        });
-                    }
-                },
+                create: chatCompletionsCreate.bind(this),
             },
         };
         /**
@@ -100,6 +98,36 @@ class ApexClient extends BaseClient_1.BaseClient {
                 });
             });
         };
+        /**
+         * Submit a deep researcher job
+         */
+        this.submitDeepResearcherJob = async (params) => {
+            const client = this.createGrpcClient();
+            return new Promise((resolve, reject) => {
+                client.submitDeepResearcherJob({ ...params, uids: params.uids ?? [] }, (error, response) => {
+                    if (error) {
+                        reject(error);
+                        return;
+                    }
+                    resolve(response);
+                });
+            });
+        };
+        /**
+         * Get a deep researcher job
+         */
+        this.getDeepResearcherJob = async (params) => {
+            const client = this.createGrpcClient();
+            return new Promise((resolve, reject) => {
+                client.getDeepResearcherJob(params, (error, response) => {
+                    if (error) {
+                        reject(error);
+                        return;
+                    }
+                    resolve(response);
+                });
+            });
+        };
         this.defaultTimeout = options.timeout || 60;
         this._grpcClient = grpcClient;
     }

package/dist/lib/apex/DeepResearch.d.ts

@@ -0,0 +1,28 @@
+import { ApexClient } from "./Client";
+import { ChatMessage, SamplingParameters, SubmitDeepResearcherJobResponse, GetDeepResearcherJobResponse } from "../../generated/apex/v1/apex";
+/** interface for input parameters that can be defined by the user */
+export interface DeepResearchJobParams {
+    /** The messages to generate completions for */
+    messages: ChatMessage[];
+    /** The miner UIDs that will be used to generate the completion */
+    uids?: number[];
+    /** The LLM name to use for the completion */
+    model?: string;
+    /** The seed to use for the completion */
+    seed?: number;
+    /** The sampling parameters to use for the completion */
+    samplingParameters?: SamplingParameters;
+}
+export declare class DeepResearch {
+    private client;
+    private readonly defaultSamplingParameters;
+    constructor(client: ApexClient);
+    /**
+     * Create a deep research job with proper defaults
+     */
+    createJob(params: DeepResearchJobParams): Promise<SubmitDeepResearcherJobResponse>;
+    /**
+     * Get the status and results of a deep research job
+     */
+    getJobResults(jobId: string): Promise<GetDeepResearcherJobResponse>;
+}

package/dist/lib/apex/DeepResearch.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeepResearch = void 0;
+class DeepResearch {
+    constructor(client) {
+        // Default sampling parameters for deep research
+        this.defaultSamplingParameters = {
+            temperature: 0.7,
+            topP: 0.95,
+            maxNewTokens: 8192,
+            doSample: false,
+        };
+        this.client = client;
+    }
+    /**
+     * Create a deep research job with proper defaults
+     */
+    async createJob(params) {
+        const request = {
+            // User configurable fields
+            messages: params.messages,
+            uids: params.uids ?? [], // Default to empty array if not provided
+            model: params.model,
+            seed: params.seed,
+            samplingParameters: params.samplingParameters ?? this.defaultSamplingParameters,
+            // Required internal fields for Deep Researcher
+            task: "InferenceTask",
+            mixture: false,
+            inferenceMode: "Chain-of-Thought",
+            stream: true,
+        };
+        return this.client.submitDeepResearcherJob(request);
+    }
+    /**
+     * Get the status and results of a deep research job
+     */
+    async getJobResults(jobId) {
+        return this.client.getDeepResearcherJob({ jobId });
+    }
+}
+exports.DeepResearch = DeepResearch;

package/dist/lib/apex/Stream.d.ts

@@ -5,6 +5,9 @@ export type ReadableStreamInterface = ReadableStream<Uint8Array>;
  */
 export declare class ApexStream<Item> implements AsyncIterable<Item> {
     private iterator;
+    /**
+     * The AbortController for this stream. Call `abort()` to cancel the stream.
+     */
     controller: AbortController;
     constructor(iterator: () => AsyncIterator<Item>, controller: AbortController);
     /**

package/dist/lib/apex/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./Stream";
 export * from "./Client";
+export * from "./DeepResearch";

package/dist/lib/apex/index.js

@@ -16,4 +16,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./Stream"), exports);
 __exportStar(require("./Client"), exports);
+__exportStar(require("./DeepResearch"), exports);
 // Future exports from the apex package would go here

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.2.12";
+export declare const VERSION = "1.2.14";

package/dist/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = "1.2.12";
+exports.VERSION = "1.2.14";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macrocosmos",
-  "version": "1.2.12",
+  "version": "1.2.14",
   "description": "TypeScript SDK package for Macrocosmos",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",