Orpheon SDK

TypeScript SDK for the Orpheon Protocol - an intent-native interaction standard for autonomous systems.

Installation

npm install orpheon-sdk
# or
bun add orpheon-sdk
# or
yarn add orpheon-sdk

Quick Start

import { OrpheonClient, IntentBuilder } from 'orpheon-sdk';

// Connect to an Orpheon node
const client = await OrpheonClient.connect('http://localhost:3000');

// Create an intent using the fluent builder
const intent = IntentBuilder.create()
  .kind('provision_gpu_cluster')
  .resourceLimit('count', 8)
  .sla('type', 100, 'H100')
  .maxCost(500, 'USD')
  .minimize('cost', 0.6)
  .maximize('speed', 0.4)
  .build();

// Submit and stream events
const stream = await client.submit(intent);

for await (const event of stream) {
  switch (event.type) {
    case 'negotiating':
      console.log(`💬 Negotiating: $${event.estimatedCost}`);
      break;
    case 'executing':
      console.log(`⚙️ Executing: ${event.stepName} (${event.progress * 100}%)`);
      break;
    case 'complete':
      console.log(`✅ Complete! Artifact: ${event.artifactId}`);
      break;
    case 'error':
      console.error(`❌ Error: ${event.message}`);
      break;
  }
}

API Reference

OrpheonClient

Main client for interacting with Orpheon nodes.

// Connect
const client = await OrpheonClient.connect(url, options?);

// Submit intent
const stream = await client.submit(intent);

// Get intent status
const status = await client.getIntent(id);

// Get plan
const plan = await client.getPlan(intentId);

// Get artifact
const artifact = await client.getArtifact(intentId);

// Cancel
await client.cancel(id);

// Simulate (dry-run)
const result = await client.simulate(intent);

// List intents
const intents = await client.listIntents();

IntentBuilder

Fluent builder for creating intents.

const intent = IntentBuilder.create()
  .kind('my_intent')              // Required: intent type
  .stateMatch('expr')             // State match constraint
  .resourceLimit('cpu', 4)        // Resource constraint
  .sla('latency', 100, 'ms')      // SLA constraint
  .budget({ maxCost: 100 })       // Budget configuration
  .maxCost(100, 'USD')            // Shorthand for max cost
  .maxDuration(30000)             // Max duration in ms
  .minimize('cost', 0.5)          // Optimization preference
  .maximize('speed', 0.5)         // Optimization preference
  .metadata({ key: 'value' })     // Custom metadata
  .build();                       // Build the intent

EventStream

Async-iterable stream of execution events.

const stream = await client.submit(intent);

// Using for-await
for await (const event of stream) {
  console.log(event);
}

// Or manually
const event = await stream.next();

// Close when done
stream.close();

Event Types

| Type | Description | Fields | |------|-------------|--------| | negotiating | Plan being negotiated | proposalId, estimatedCost, estimatedLatencyMs | | executing | Step being executed | stepId, stepName, progress | | complete | Execution complete | artifactId | | status_update | Status changed | status, planId?, artifactId? | | error | Error occurred | message |

Types

All types are exported for TypeScript users:

import type {
  Intent,
  IntentStatus,
  Constraint,
  Preference,
  Budget,
  Plan,
  Step,
  ExecutionArtifact,
  Outcome,
} from 'orpheon-sdk';

License

MIT