@orcalang/orca-lang 0.1.0

package/src/llm/anthropic.ts

@@ -0,0 +1,102 @@
+import { LLMProvider, LLMRequest, LLMResponse, LLMProviderConfig } from './provider.js';
+
+export class AnthropicProvider implements LLMProvider {
+  private apiKey: string;
+  private baseUrl: string;
+  private model: string;
+  private maxTokens: number;
+  private temperature: number;
+  private authType: 'x-api-key' | 'bearer';
+
+  constructor(config: LLMProviderConfig) {
+    this.baseUrl = config.base_url || 'https://api.anthropic.com';
+    this.model = config.model || 'claude-sonnet-4-6';
+    this.maxTokens = config.max_tokens || 4096;
+    this.temperature = config.temperature ?? 0.7;
+
+    // MiniMax uses Bearer token auth, Anthropic uses x-api-key
+    if (this.baseUrl.includes('minimax.io')) {
+      this.apiKey = config.api_key || process.env.MINIMAX_API_KEY || '';
+      this.authType = 'bearer';
+    } else {
+      this.apiKey = config.api_key || process.env.ANTHROPIC_API_KEY || '';
+      this.authType = 'x-api-key';
+    }
+
+    if (!this.apiKey) {
+      throw new Error(`API key is required for ${this.baseUrl.includes('minimax.io') ? 'MINIMAX_API_KEY' : 'ANTHROPIC_API_KEY'}`);
+    }
+  }
+
+  name(): string {
+    return 'anthropic';
+  }
+
+  async complete(request: LLMRequest): Promise<LLMResponse> {
+    // Separate system message from user/assistant messages
+    const systemMessage = request.messages.find(m => m.role === 'system');
+    const otherMessages = request.messages.filter(m => m.role !== 'system');
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'anthropic-version': '2023-06-01',
+      'anthropic-dangerous-direct-browser-access': 'true',
+    };
+
+    if (this.authType === 'bearer') {
+      headers['Authorization'] = `Bearer ${this.apiKey}`;
+    } else {
+      headers['x-api-key'] = this.apiKey;
+    }
+
+    const response = await fetch(`${this.baseUrl}/v1/messages`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        model: request.model || this.model,
+        system: systemMessage?.content,
+        messages: otherMessages.map(m => ({
+          role: m.role === 'assistant' ? 'assistant' : 'user',
+          content: m.content,
+        })),
+        max_tokens: request.max_tokens || this.maxTokens,
+        temperature: request.temperature ?? this.temperature,
+        stop_sequences: request.stop_sequences,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Anthropic API error: ${response.status} ${error}`);
+    }
+
+    const data = await response.json() as {
+      content: Array<{ type: string; text: string }>;
+      model: string;
+      usage: { input_tokens: number; output_tokens: number };
+    };
+
+    const textContent = data.content.find(c => c.type === 'text');
+    return {
+      content: textContent?.text || '',
+      model: data.model,
+      usage: {
+        input_tokens: data.usage.input_tokens,
+        output_tokens: data.usage.output_tokens,
+      },
+    };
+  }
+
+  async completeWithPrefix(request: LLMRequest, prefix: string): Promise<LLMResponse> {
+    // Anthropic doesn't support continuation prefixes directly
+    // We need to include the prefix in the system prompt and ask for completion
+    const modifiedRequest: LLMRequest = {
+      ...request,
+      messages: [
+        ...request.messages,
+        { role: 'assistant' as const, content: prefix },
+      ],
+    };
+    return this.complete(modifiedRequest);
+  }
+}

package/src/llm/grok.ts

@@ -0,0 +1,73 @@
+import { LLMProvider, LLMRequest, LLMResponse, LLMProviderConfig } from './provider.js';
+
+export class GrokProvider implements LLMProvider {
+  private apiKey: string;
+  private baseUrl: string;
+  private model: string;
+  private maxTokens: number;
+  private temperature: number;
+
+  constructor(config: LLMProviderConfig) {
+    this.apiKey = config.api_key || process.env.XAI_API_KEY || process.env.GROK_API_KEY || '';
+    this.baseUrl = config.base_url || 'https://api.x.ai/v1';
+    this.model = config.model || 'grok-3';
+    this.maxTokens = config.max_tokens || 4096;
+    this.temperature = config.temperature ?? 0.7;
+
+    if (!this.apiKey) {
+      throw new Error('XAI_API_KEY or GROK_API_KEY is required for Grok provider');
+    }
+  }
+
+  name(): string {
+    return 'grok';
+  }
+
+  async complete(request: LLMRequest): Promise<LLMResponse> {
+    const response = await fetch(`${this.baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: request.model || this.model,
+        messages: request.messages,
+        max_tokens: request.max_tokens || this.maxTokens,
+        temperature: request.temperature ?? this.temperature,
+        stop: request.stop_sequences,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Grok API error: ${response.status} ${error}`);
+    }
+
+    const data = await response.json() as {
+      choices: Array<{ message: { content: string } }>;
+      model: string;
+      usage: { prompt_tokens: number; completion_tokens: number };
+    };
+
+    return {
+      content: data.choices[0]?.message?.content || '',
+      model: data.model,
+      usage: {
+        input_tokens: data.usage.prompt_tokens,
+        output_tokens: data.usage.completion_tokens,
+      },
+    };
+  }
+
+  async completeWithPrefix(request: LLMRequest, prefix: string): Promise<LLMResponse> {
+    const modifiedRequest: LLMRequest = {
+      ...request,
+      messages: [
+        ...request.messages,
+        { role: 'assistant' as const, content: prefix },
+      ],
+    };
+    return this.complete(modifiedRequest);
+  }
+}

package/src/llm/index.ts

@@ -0,0 +1,29 @@
+import { LLMProvider, LLMProviderConfig } from './provider.js';
+import type { LLMMessage, LLMRequest, LLMResponse } from './provider.js';
+import { AnthropicProvider } from './anthropic.js';
+import { OpenAIProvider } from './openai.js';
+import { OllamaProvider } from './ollama.js';
+import { GrokProvider } from './grok.js';
+import { LLMProviderType } from '../config/types.js';
+
+export type { LLMProvider };
+export type { LLMMessage, LLMRequest, LLMResponse };
+export { AnthropicProvider } from './anthropic.js';
+export { OpenAIProvider } from './openai.js';
+export { OllamaProvider } from './ollama.js';
+export { GrokProvider } from './grok.js';
+
+export function createProvider(type: LLMProviderType, config: LLMProviderConfig): LLMProvider {
+  switch (type) {
+    case 'anthropic':
+      return new AnthropicProvider(config);
+    case 'openai':
+      return new OpenAIProvider(config);
+    case 'ollama':
+      return new OllamaProvider(config);
+    case 'grok':
+      return new GrokProvider(config);
+    default:
+      throw new Error(`Unknown LLM provider type: ${type}`);
+  }
+}

package/src/llm/ollama.ts

@@ -0,0 +1,62 @@
+import { LLMProvider, LLMRequest, LLMResponse, LLMProviderConfig } from './provider.js';
+
+export class OllamaProvider implements LLMProvider {
+  private baseUrl: string;
+  private model: string;
+  private temperature: number;
+
+  constructor(config: LLMProviderConfig) {
+    this.baseUrl = config.base_url || 'http://localhost:11434';
+    this.model = config.model || 'llama3';
+    this.temperature = config.temperature ?? 0.7;
+  }
+
+  name(): string {
+    return 'ollama';
+  }
+
+  async complete(request: LLMRequest): Promise<LLMResponse> {
+    const response = await fetch(`${this.baseUrl}/api/chat`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        model: request.model || this.model,
+        messages: request.messages,
+        options: {
+          temperature: request.temperature ?? this.temperature,
+          num_predict: request.max_tokens || 4096,
+        },
+        stream: false,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Ollama API error: ${response.status} ${error}`);
+    }
+
+    const data = await response.json() as {
+      message: { content: string };
+      model: string;
+    };
+
+    return {
+      content: data.message.content,
+      model: data.model,
+    };
+  }
+
+  async completeWithPrefix(request: LLMRequest, prefix: string): Promise<LLMResponse> {
+    // Ollama doesn't support continuation prefixes directly
+    const modifiedRequest: LLMRequest = {
+      ...request,
+      messages: [
+        ...request.messages,
+        { role: 'assistant' as const, content: prefix },
+      ],
+    };
+    return this.complete(modifiedRequest);
+  }
+}

package/src/llm/openai.ts

@@ -0,0 +1,74 @@
+import { LLMProvider, LLMRequest, LLMResponse, LLMProviderConfig } from './provider.js';
+
+export class OpenAIProvider implements LLMProvider {
+  private apiKey: string;
+  private baseUrl: string;
+  private model: string;
+  private maxTokens: number;
+  private temperature: number;
+
+  constructor(config: LLMProviderConfig) {
+    this.apiKey = config.api_key || process.env.OPENAI_API_KEY || '';
+    this.baseUrl = config.base_url || 'https://api.openai.com/v1';
+    this.model = config.model || 'gpt-4o';
+    this.maxTokens = config.max_tokens || 4096;
+    this.temperature = config.temperature ?? 0.7;
+
+    if (!this.apiKey) {
+      throw new Error('OPENAI_API_KEY is required for OpenAI provider');
+    }
+  }
+
+  name(): string {
+    return 'openai';
+  }
+
+  async complete(request: LLMRequest): Promise<LLMResponse> {
+    const response = await fetch(`${this.baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: request.model || this.model,
+        messages: request.messages,
+        max_tokens: request.max_tokens || this.maxTokens,
+        temperature: request.temperature ?? this.temperature,
+        stop: request.stop_sequences,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`OpenAI API error: ${response.status} ${error}`);
+    }
+
+    const data = await response.json() as {
+      choices: Array<{ message: { content: string } }>;
+      model: string;
+      usage: { prompt_tokens: number; completion_tokens: number };
+    };
+
+    return {
+      content: data.choices[0]?.message?.content || '',
+      model: data.model,
+      usage: {
+        input_tokens: data.usage.prompt_tokens,
+        output_tokens: data.usage.completion_tokens,
+      },
+    };
+  }
+
+  async completeWithPrefix(request: LLMRequest, prefix: string): Promise<LLMResponse> {
+    // OpenAI doesn't support continuation prefixes directly
+    const modifiedRequest: LLMRequest = {
+      ...request,
+      messages: [
+        ...request.messages,
+        { role: 'assistant' as const, content: prefix },
+      ],
+    };
+    return this.complete(modifiedRequest);
+  }
+}

package/src/llm/provider.ts

@@ -0,0 +1,35 @@
+export interface LLMMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+export interface LLMRequest {
+  messages: LLMMessage[];
+  model: string;
+  max_tokens?: number;
+  temperature?: number;
+  stop_sequences?: string[];
+}
+
+export interface LLMResponse {
+  content: string;
+  model: string;
+  usage?: {
+    input_tokens: number;
+    output_tokens: number;
+  };
+}
+
+export interface LLMProvider {
+  name(): string;
+  complete(request: LLMRequest): Promise<LLMResponse>;
+  completeWithPrefix?(request: LLMRequest, prefix: string): Promise<LLMResponse>;
+}
+
+export interface LLMProviderConfig {
+  api_key?: string;
+  base_url?: string;
+  model: string;
+  max_tokens?: number;
+  temperature?: number;
+}

package/src/parser/ast-to-markdown.ts

@@ -0,0 +1,220 @@
+// AST to Markdown converter for Orca
+// Converts MachineDef AST to .orca.md format
+
+import {
+  MachineDef, ContextField, StateDef, Transition,
+  GuardDef, GuardExpression, ActionSignature, Property,
+  Type, ValueRef, ParallelDef, EffectDef,
+} from './ast.js';
+
+function typeToString(type: Type): string {
+  switch (type.kind) {
+    case 'string': return 'string';
+    case 'int': return 'int';
+    case 'decimal': return 'decimal';
+    case 'bool': return 'bool';
+    case 'array': return `${type.elementType}[]`;
+    case 'map': return `map<${type.keyType}, ${type.valueType}>`;
+    case 'optional': return `${type.innerType}?`;
+    case 'custom': return type.name;
+  }
+}
+
+function guardExpressionToString(expr: GuardExpression): string {
+  switch (expr.kind) {
+    case 'true': return 'true';
+    case 'false': return 'false';
+    case 'not': {
+      const inner = guardExpressionToString(expr.expr);
+      // Add parens for clarity if inner is a compound expression
+      if (expr.expr.kind === 'and' || expr.expr.kind === 'or') return `not (${inner})`;
+      return `not ${inner}`;
+    }
+    case 'and': {
+      const left = guardExpressionToString(expr.left);
+      const right = guardExpressionToString(expr.right);
+      const wrapLeft = expr.left.kind === 'or' ? `(${left})` : left;
+      const wrapRight = expr.right.kind === 'or' ? `(${right})` : right;
+      return `${wrapLeft} and ${wrapRight}`;
+    }
+    case 'or': return `${guardExpressionToString(expr.left)} or ${guardExpressionToString(expr.right)}`;
+    case 'compare': {
+      const opStr = { eq: '==', ne: '!=', lt: '<', gt: '>', le: '<=', ge: '>=' }[expr.op];
+      return `${expr.left.path.join('.')} ${opStr} ${valueToString(expr.right)}`;
+    }
+    case 'nullcheck': return expr.expr.path.join('.');
+  }
+}
+
+function valueToString(val: ValueRef): string {
+  if (val.type === 'null') return 'null';
+  if (val.type === 'string') return `"${val.value}"`;
+  if (val.type === 'boolean') return String(val.value);
+  return String(val.value);
+}
+
+function actionSignatureToString(action: ActionSignature): string {
+  const params = action.parameters.join(', ');
+  let sig = `(${params}) -> ${action.returnType}`;
+  if (action.hasEffect && action.effectType) sig += ` + Effect<${action.effectType}>`;
+  return sig;
+}
+
+function padColumn(rows: string[][], colIdx: number): void {
+  const maxLen = Math.max(...rows.map(r => (r[colIdx] || '').length));
+  for (const row of rows) {
+    row[colIdx] = (row[colIdx] || '').padEnd(maxLen);
+  }
+}
+
+function formatTable(headers: string[], rows: string[][]): string[] {
+  const allRows = [headers, ...rows];
+  for (let c = 0; c < headers.length; c++) padColumn(allRows, c);
+
+  const lines: string[] = [];
+  lines.push('| ' + allRows[0].join(' | ') + ' |');
+  lines.push('|' + allRows[0].map(h => '-'.repeat(h.length + 2)).join('|') + '|');
+  for (let r = 1; r < allRows.length; r++) {
+    lines.push('| ' + allRows[r].join(' | ') + ' |');
+  }
+  return lines;
+}
+
+function emitStates(states: StateDef[], level: number): string[] {
+  const lines: string[] = [];
+  for (const state of states) {
+    const prefix = '#'.repeat(level);
+    const annotations: string[] = [];
+    if (state.isInitial) annotations.push('initial');
+    if (state.isFinal) annotations.push('final');
+    if (state.parallel) {
+      annotations.push('parallel');
+      if (state.parallel.sync) annotations.push(`sync: ${state.parallel.sync}`);
+    }
+
+    let heading = `${prefix} state ${state.name}`;
+    if (annotations.length > 0) heading += ` [${annotations.join(', ')}]`;
+    lines.push(heading);
+
+    if (state.description) lines.push(`> ${state.description}`);
+
+    if (state.onEntry) lines.push(`- on_entry: ${state.onEntry}`);
+    if (state.onExit) lines.push(`- on_exit: ${state.onExit}`);
+    if (state.timeout) lines.push(`- timeout: ${state.timeout.duration} -> ${state.timeout.target}`);
+    if (state.ignoredEvents?.length) lines.push(`- ignore: ${state.ignoredEvents.join(', ')}`);
+    if (state.onDone) lines.push(`- on_done: -> ${state.onDone}`);
+
+    if (state.parallel) {
+      for (const region of state.parallel.regions) {
+        lines.push('');
+        lines.push(`${'#'.repeat(level + 1)} region ${region.name}`);
+        lines.push('');
+        lines.push(...emitStates(region.states, level + 2));
+      }
+    } else if (state.contains?.length) {
+      lines.push('');
+      lines.push(...emitStates(state.contains, level + 1));
+    }
+
+    lines.push('');
+  }
+  return lines;
+}
+
+function emitProperties(properties: Property[]): string[] {
+  return properties.map(prop => {
+    switch (prop.kind) {
+      case 'reachable':
+      case 'unreachable':
+        return `- ${prop.kind}: ${prop.to} from ${prop.from}`;
+      case 'passes_through':
+        return `- passes_through: ${prop.through} for ${prop.from} -> ${prop.to}`;
+      case 'live':
+        return '- live';
+      case 'responds':
+        return `- responds: ${prop.to} from ${prop.from} within ${prop.within}`;
+      case 'invariant': {
+        const expr = guardExpressionToString(prop.expression);
+        const inState = prop.inState ? ` in ${prop.inState}` : '';
+        return `- invariant: \`${expr}\`${inState}`;
+      }
+    }
+  });
+}
+
+export function machineToMarkdown(machine: MachineDef): string {
+  const lines: string[] = [];
+
+  lines.push(`# machine ${machine.name}`);
+  lines.push('');
+
+  // Context
+  if (machine.context.length > 0) {
+    lines.push('## context');
+    lines.push('');
+    const rows = machine.context.map(f => [f.name, typeToString(f.type), f.defaultValue || '']);
+    lines.push(...formatTable(['Field', 'Type', 'Default'], rows));
+    lines.push('');
+  }
+
+  // Events
+  if (machine.events.length > 0) {
+    lines.push('## events');
+    lines.push('');
+    for (const e of machine.events) lines.push(`- ${e.name}`);
+    lines.push('');
+  }
+
+  // States
+  lines.push(...emitStates(machine.states, 2));
+
+  // Transitions
+  if (machine.transitions.length > 0) {
+    lines.push('## transitions');
+    lines.push('');
+    const rows = machine.transitions.map(t => {
+      let guard = '';
+      if (t.guard) guard = t.guard.negated ? `!${t.guard.name}` : t.guard.name;
+      return [t.source, t.event, guard, t.target, t.action || ''];
+    });
+    lines.push(...formatTable(['Source', 'Event', 'Guard', 'Target', 'Action'], rows));
+    lines.push('');
+  }
+
+  // Guards
+  if (machine.guards.length > 0) {
+    lines.push('## guards');
+    lines.push('');
+    const rows = machine.guards.map(g => [g.name, `\`${guardExpressionToString(g.expression)}\``]);
+    lines.push(...formatTable(['Name', 'Expression'], rows));
+    lines.push('');
+  }
+
+  // Actions
+  if (machine.actions.length > 0) {
+    lines.push('## actions');
+    lines.push('');
+    const rows = machine.actions.map(a => [a.name, `\`${actionSignatureToString(a)}\``]);
+    lines.push(...formatTable(['Name', 'Signature'], rows));
+    lines.push('');
+  }
+
+  // Effects
+  if (machine.effects && machine.effects.length > 0) {
+    lines.push('## effects');
+    lines.push('');
+    const rows = machine.effects.map(e => [e.name, e.input, e.output]);
+    lines.push(...formatTable(['Name', 'Input', 'Output'], rows));
+    lines.push('');
+  }
+
+  // Properties
+  if (machine.properties?.length) {
+    lines.push('## properties');
+    lines.push('');
+    lines.push(...emitProperties(machine.properties));
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}