🧱 CubicKit

The SDK core for interacting with the Cubicler ecosystem.

CubicKit is a developer desk toolkit for building AI agents that interface with Cubicler's orchestration system. Think of it as the interface between your AI agent and Cubicler, handling prompt retrieval, function spec loading, and agent call routing.

🚀 Features

• TypeScript-first SDK with full type safety
• Intelligent caching with configurable timeouts for prompts and specs
• Fallback mechanisms - uses cached data when network requests fail
• Force refresh capabilities to bypass cache when needed
• Lightweight and stateless - no heavyweight frameworks
• Model-agnostic - works with any AI model or framework

📦 Installation

npm install cubic-kit

🧰 Basic Usage

import { CubicKitClient } from 'cubic-kit';

// Create client with default configuration
const client = new CubicKitClient({
    baseUrl: "https://cubicler.example.com"
});

// Load system prompt (cached for 10 minutes by default)
const prompt = await client.loadPrompt();

// Load function specifications (cached for 10 minutes by default)
const specs = await client.loadSpec();

// Call a function
const response = await client.callFunction("getMock", {
    mock_id: 123,
    mock_name: "test"
});

⚙️ Configuration

import { CubicKitClient } from 'cubic-kit';

const client = new CubicKitClient({
    baseUrl: "https://cubicler.example.com",
    promptCacheTimeout: 300,  // Cache prompt for 5 minutes (in seconds)
    specCacheTimeout: 600     // Cache spec for 10 minutes (in seconds)
});

🔄 Cache Management

Force Refresh

// Force fetch fresh prompt (bypass cache)
const freshPrompt = await client.loadPrompt(true);

// Force fetch fresh spec (bypass cache)
const freshSpec = await client.loadSpec(true);

Automatic Fallback

If network requests fail, CubicKit automatically falls back to cached data when available:

try {
    // Will use cached data if network fails
    const prompt = await client.loadPrompt();
} catch (error) {
    // Only throws if no cached data is available
    console.error('No cached data available:', error);
}

🔧 API Reference

CubicKitClient

Constructor

new CubicKitClient(config: CubicKitClientConfig)

• config.baseUrl: The base URL of your Cubicler instance
• config.promptCacheTimeout: Cache timeout for prompts in seconds (default: 600)
• config.specCacheTimeout: Cache timeout for specs in seconds (default: 600)

Methods

loadPrompt(force?: boolean): Promise<string>

Fetches the system prompt from GET /prompt.

• Returns cached version if valid and force is false
• Falls back to cache if network request fails

loadSpec(force?: boolean): Promise<FunctionSpec[]>

Fetches function specifications from GET /spec.

• Returns cached version if valid and force is false
• Falls back to cache if network request fails

callFunction(functionName: string, parameters: FunctionCallParameters): Promise<any>

Calls a function via POST /call.

• No caching for function calls
• Returns the JSON response from the server

📋 Types

FunctionSpec

interface FunctionSpec {
  name: string;
  description: string;
  parameters: {
    type: 'object';
    properties: Record<string, ParameterDefinition>;
    required?: string[];
  };
}

FunctionCallParameters

type FunctionCallParameters = JSONObject & {
  payload?: JSONValue;
};

ParameterDefinition

interface ParameterDefinition {
  type: 'string' | 'number' | 'boolean' | 'array' | 'object';
  required?: boolean;
  items?: ParameterDefinition;
  properties?: Record<string, ParameterDefinition>;
}

🧪 Development

Running Tests

npm test

Building

npm run build

Linting

npm run lint

📝 License

MIT

🤝 Contributing

Contributions are welcome! Please ensure:

• Clean modularity and composability
• Readability and DX over cleverness
• Compatibility with Cubicler's spec and prompt structure
• Lightweight, stateless, and testable code

Build it like it's going to be used by other engineers every day.