Partitura SDK

SDK for building Partitura plugins and accessing hosted models.

Install

npm install @partitura/sdk

Four Entry Points

1. Gateway API (NEW in v3)

Access Partitura's unified API for hosted models with automatic credit management, conversation memory, and real-time voice support.

import { Partitura } from '@partitura/sdk/gateway'

const partitura = new Partitura({
  token: process.env.PARTITURA_TOKEN
})

// Simple chat
const response = await partitura.chat("What is the meaning of life?")

// Create an agent with memory
const agent = partitura.agent({
  model: 'claude-3-5-sonnet',
  system: 'You are a helpful assistant.',
  memory: true
})

await agent.chat("My name is John")
const response = await agent.chat("What's my name?")  // Remembers!

2. MCP Tool Servers (server-side)

Build custom tools that AI agents can use:

import { createMCPServer, defineTools, PluginContext } from '@partitura/sdk';

const ctx = new PluginContext();
const server = createMCPServer({ name: 'my-tools' });

defineTools(server, {
  my_tool: {
    description: 'Does something useful',
    bubbleText: '{agent} using my tool',
    inputSchema: {
      type: 'object',
      properties: {
        input: { type: 'string', description: 'The input' },
      },
      required: ['input'],
    },
    execute: async ({ input }) => {
      const apiKey = await ctx.getConfig('api_key');
      // ... your logic
      return { content: [{ type: 'text', text: `Result: ${input}` }] };
    },
  },
});

server.start();

3. WebView Stages (client-side)

Communicate with Partitura from stage HTML:

<script type="module">
  import { createStage } from '@partitura/sdk/stage';

  const stage = createStage();

  // Receive messages from agents
  stage.onMessage((msg) => {
    console.log('Agent says:', msg.text);
  });

  // Send messages to the active agent
  document.getElementById('btn').onclick = () => {
    stage.sendToAgent('Hello from the stage!');
  };
</script>

4. Extended API (client-side, v2)

For view replacements and rich plugin WebViews:

// Agent management
const agents = await Partitura.api.agents.list();
await Partitura.api.agents.deliverPrompt('maestro', 'Start the task');

// UI control
Partitura.api.ui.toast('Done!', 'success');

// Config
const value = await Partitura.api.config.get('api_key');

// Generic backend proxy
const res = await Partitura.api.fetch('/management/agents');

Gateway API Examples

Real-time Voice

const voice = partitura.voice({
  model: 'gemini-3.1-flash-live',
  voice: 'Charon'
})

voice.on('speech', (text) => console.log('Agent:', text))
voice.on('user-speech', (text) => console.log('User:', text))

await voice.connect()
await voice.say('Tell me about Partitura')

Tool Use

const agent = partitura.agent({
  model: 'claude-3-5-sonnet',
  tools: [{
    name: 'calculate',
    description: 'Calculate math',
    inputSchema: {
      type: 'object',
      properties: { expr: { type: 'string' } }
    }
  }]
})

const response = await agent.chat("What is 2 + 2?")

Streaming

const stream = await agent.chatStream('Write a story')

for await (const chunk of stream) {
  process.stdout.write(chunk.text)
}

Type-Safe Plugin Manifests

import type { PluginManifest } from '@partitura/sdk/types';

const manifest: PluginManifest = {
  apiVersion: 'partitura.dev/v1',
  kind: 'Plugin',
  metadata: {
    name: 'my-plugin',
    version: '1.0.0',
    displayName: 'My Plugin',
    description: 'Does cool things',
  },
  contributions: {
    mcpPackages: [{
      id: 'my-tools',
      name: 'My Tools',
      transport: 'stdio',
      command: 'node',
      args: ['mcp-servers/index.js'],
    }],
  },
};

All 38 Contribution Types

See the Plugin Documentation for the full manifest reference.

License

MIT