Skip to main content

Model Providers

Gravity abstracts all model providers behind a clean ModelProvider interface. You can switch providers without changing any agent logic.

Built-in Providers​

import { DeepSeekProvider } from 'gravity-sdk';

const model = new DeepSeekProvider({
  apiKey: process.env.DEEPSEEK_API_KEY, // or set env var
  model: 'deepseek-v4-pro',             // or 'deepseek-v4-flash'
  baseURL: 'https://api.deepseek.com',  // default
});

OpenAIProvider​

import { OpenAIProvider } from 'gravity-sdk';

const model = new OpenAIProvider({
  apiKey: process.env.OPENAI_API_KEY,
  model: 'gpt-4o', // default
});

Custom Provider​

Implement the ModelProvider interface to integrate any LLM:

import { ModelProvider, ModelRequest, ModelResponse } from 'gravity-sdk';

class MyCustomProvider implements ModelProvider {
  name = 'my-provider';

  async generate(request: ModelRequest): Promise<ModelResponse> {
    // Call your LLM API here
    const response = await callMyLLM(request.messages, request.systemPrompt);

    return {
      message: {
        role: 'assistant',
        content: response.text,
        toolCalls: response.toolCalls,
      },
      usage: {
        promptTokens: response.usage.input,
        completionTokens: response.usage.output,
        totalTokens: response.usage.total,
      },
    };
  }
}

const agent = new Agent({
  model: new MyCustomProvider(),
  // ...
});

Model Fallback Pattern​

async function runWithFallback(input: string, sessionId: string) {
  const primary = new DeepSeekProvider({ model: 'deepseek-v4-pro' });
  const fallback = new DeepSeekProvider({ model: 'deepseek-v4-flash' });

  try {
    const agent = new Agent({ model: primary, /* ... */ });
    return await agent.run(input, sessionId);
  } catch {
    const agent = new Agent({ model: fallback, /* ... */ });
    return await agent.run(input, sessionId);
  }
}