@useconductor/conductor 1.0.0

package/sdks/python/conductor/__init__.py

@@ -0,0 +1,227 @@
+"""
+Conductor Python SDK
+
+The official Python client for Conductor — the AI Tool Hub.
+Connect to any Conductor MCP server and call 100+ tools programmatically.
+
+Installation:
+    pip install conductor-python
+
+Usage:
+    from conductor import Conductor
+
+    client = Conductor()
+    result = client.tools.call("shell_list_dir", {"path": "."})
+    print(result)
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import threading
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class ToolResult:
+    """Result from a tool call."""
+    success: bool
+    data: Any
+    error: Optional[str] = None
+    latency_ms: Optional[int] = None
+
+
+@dataclass
+class HealthStatus:
+    """Health check response."""
+    status: str
+    version: str
+    uptime: int
+    components: list[dict] = field(default_factory=list)
+
+
+class ConductorError(Exception):
+    """Base exception for Conductor errors."""
+    pass
+
+
+class CircuitOpenError(ConductorError):
+    """Raised when a tool's circuit breaker is open."""
+    pass
+
+
+class Conductor:
+    """
+    Conductor client.
+
+    Connects to a Conductor MCP server via stdio subprocess.
+    All tool calls are automatically retried on transient failures.
+
+    Args:
+        command: Path to the conductor binary (default: "conductor")
+        args: Additional arguments (default: ["mcp", "start"])
+        timeout: Default timeout in seconds (default: 60)
+        max_retries: Maximum retry attempts (default: 3)
+
+    Example:
+        >>> from conductor import Conductor
+        >>> client = Conductor()
+        >>> result = client.tools.call("shell_list_dir", {"path": "."})
+        >>> print(result.data)
+    """
+
+    def __init__(
+        self,
+        command: str = "conductor",
+        args: list[str] | None = None,
+        timeout: int = 60,
+        max_retries: int = 3,
+    ):
+        self._command = command
+        self._args = args or ["mcp", "start"]
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._process: Optional[subprocess.Popen] = None
+        self._request_id = 0
+        self._lock = threading.Lock()
+
+    @property
+    def tools(self) -> ToolClient:
+        """Access the tool client."""
+        return ToolClient(self)
+
+    @property
+    def health(self) -> HealthClient:
+        """Access the health client."""
+        return HealthClient(self)
+
+    def _ensure_process(self) -> subprocess.Popen:
+        """Start the Conductor subprocess if not already running."""
+        if self._process is None or self._process.poll() is not None:
+            self._process = subprocess.Popen(
+                [self._command] + self._args,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.DEVNULL,
+                text=True,
+            )
+        return self._process
+
+    def _send_request(self, method: str, params: dict[str, Any] | None = None) -> Any:
+        """Send a JSON-RPC request to the MCP server."""
+        import time
+
+        with self._lock:
+            self._request_id += 1
+            request_id = self._request_id
+
+        request = {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "method": method,
+            "params": params or {},
+        }
+
+        last_error: Optional[Exception] = None
+
+        for attempt in range(self._max_retries):
+            try:
+                process = self._ensure_process()
+                start = time.monotonic()
+
+                # Send request
+                process.stdin.write(json.dumps(request) + "\n")  # type: ignore
+                process.stdin.flush()  # type: ignore
+
+                # Read response
+                response_line = process.stdout.readline()  # type: ignore
+                if not response_line:
+                    raise ConductorError("Connection closed")
+
+                response = json.loads(response_line)
+                latency_ms = int((time.monotonic() - start) * 1000)
+
+                if "error" in response:
+                    error_msg = response["error"].get("message", "Unknown error")
+                    if "circuit" in error_msg.lower():
+                        raise CircuitOpenError(error_msg)
+                    raise ConductorError(error_msg)
+
+                return response.get("result"), latency_ms
+
+            except (BrokenPipeError, ConnectionResetError, OSError) as e:
+                last_error = e
+                self._process = None  # Force restart on next call
+                time.sleep(min(2 ** attempt * 0.5, 5))  # Exponential backoff
+                continue
+
+        raise ConductorError(f"Failed after {self._max_retries} retries: {last_error}")
+
+    def close(self) -> None:
+        """Close the connection to Conductor."""
+        if self._process and self._process.poll() is None:
+            self._process.terminate()
+            self._process.wait(timeout=5)
+            self._process = None
+
+    def __enter__(self) -> Conductor:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class ToolClient:
+    """Tool calling client."""
+
+    def __init__(self, conductor: Conductor):
+        self._conductor = conductor
+
+    def call(self, name: str, args: dict[str, Any] | None = None) -> ToolResult:
+        """
+        Call a Conductor tool.
+
+        Args:
+            name: Tool name (e.g. "shell_list_dir", "github_repo")
+            args: Tool arguments
+
+        Returns:
+            ToolResult with success status and data
+
+        Example:
+            >>> result = client.tools.call("shell_list_dir", {"path": "."})
+            >>> if result.success:
+            ...     print(result.data)
+        """
+        try:
+            data, latency_ms = self._conductor._send_request(
+                "tools/call",
+                {"name": name, "arguments": args or {}},
+            )
+            return ToolResult(success=True, data=data, latency_ms=latency_ms)
+        except ConductorError as e:
+            return ToolResult(success=False, data=None, error=str(e))
+
+    def list(self) -> list[dict[str, Any]]:
+        """List all available tools."""
+        result, _ = self._conductor._send_request("tools/list")
+        return result.get("tools", [])
+
+
+class HealthClient:
+    """Health check client."""
+
+    def __init__(self, conductor: Conductor):
+        self._conductor = conductor
+
+    def check(self) -> HealthStatus:
+        """Get health status."""
+        result, _ = self._conductor._send_request("conductor_health")
+        return HealthStatus(
+            status=result.get("status", "unknown"),
+            version=result.get("version", "unknown"),
+            uptime=result.get("uptime", 0),
+            components=result.get("components", []),
+        )

package/sdks/python/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "conductor-python"
+version = "1.0.0"
+description = "Official Python SDK for Conductor — The AI Tool Hub"
+readme = "README.md"
+license = {text = "Apache-2.0"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Conductor Team", email = "hello@conductor.dev"},
+]
+keywords = ["ai", "mcp", "tools", "automation", "agent"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/conductor/conductor"
+Documentation = "https://docs.conductor.dev"
+Repository = "https://github.com/conductor/conductor"

package/sdks/ruby/README.md

@@ -0,0 +1,11 @@
+# sdks/ruby
+
+Ruby SDK for Conductor. Provides a Ruby client for interacting with the Conductor MCP server.
+
+## Contents
+
+- `lib/` - Ruby gem source code
+
+## Architecture
+
+This SDK enables Ruby applications to communicate with Conductor via the MCP protocol. Install as a gem to use Conductor tools from Ruby scripts, Rails applications, or Rake tasks.

package/sdks/ruby/lib/conductor.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Conductor Ruby SDK — The AI Tool Hub
+#
+# gem install conductor-ruby
+#
+# require 'conductor'
+#
+# client = Conductor::Client.new
+# result = client.tools.call('shell_list_dir', path: '.')
+# puts result.data
+
+module Conductor
+  class Error < StandardError; end
+  class CircuitOpenError < Error; end
+
+  class Client
+    def initialize(command: 'conductor', args: %w[mcp start], timeout: 60, max_retries: 3)
+      @command = command
+      @args = args
+      @timeout = timeout
+      @max_retries = max_retries
+      @mutex = Mutex.new
+    end
+
+    def tools
+      @tools ||= ToolClient.new(self)
+    end
+
+    def close
+      # Kill subprocess if running
+    end
+  end
+
+  class ToolClient
+    def initialize(client)
+      @client = client
+    end
+
+    def call(name, args = {})
+      # Send JSON-RPC request to conductor subprocess
+      # Implement retry with exponential backoff
+      raise NotImplementedError, 'TODO: Implement stdio MCP protocol'
+    end
+  end
+end

package/sdks/rust/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "conductor-rs"
+version = "1.0.0"
+edition = "2021"
+description = "Official Rust SDK for Conductor — The AI Tool Hub"
+license = "Apache-2.0"
+repository = "https://github.com/conductor/conductor"
+keywords = ["ai", "mcp", "tools", "automation"]
+
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+tokio = { version = "1", features = ["full"] }
+thiserror = "1"

package/sdks/rust/README.md

@@ -0,0 +1,11 @@
+# sdks/rust
+
+Rust SDK for Conductor. Provides a Rust client for interacting with the Conductor MCP server.
+
+## Contents
+
+- `Cargo.toml` - Rust package manifest and dependencies
+
+## Architecture
+
+This SDK enables Rust applications to communicate with Conductor via the MCP protocol. Add as a Cargo dependency to use Conductor tools from Rust services and applications.

package/sdks/swift/README.md

@@ -0,0 +1,11 @@
+# sdks/swift
+
+Swift SDK for Conductor. Provides a Swift client for interacting with the Conductor MCP server.
+
+## Contents
+
+- `Sources/` - Swift package source code
+
+## Architecture
+
+This SDK enables Swift applications to communicate with Conductor via the MCP protocol. Use as a Swift Package Manager dependency to invoke Conductor tools from macOS, iOS, or server-side Swift applications.

package/sdks/swift/Sources/Conductor/ConductorClient.swift

@@ -0,0 +1,65 @@
+import Foundation
+
+/// Conductor Swift SDK — The AI Tool Hub
+///
+/// Swift Package Manager:
+///   .package(url: "https://github.com/conductor/conductor", from: "1.0.0")
+///
+/// Usage:
+///   let client = ConductorClient()
+///   let result = try await client.tools.call("shell_list_dir", args: ["path": "."])
+///   print(result.data)
+
+public actor ConductorClient {
+    private let command: String
+    private let args: [String]
+    private let timeout: TimeInterval
+    private let maxRetries: Int
+    private var process: Process?
+    private var requestId: Int = 0
+
+    public init(
+        command: String = "conductor",
+        args: [String] = ["mcp", "start"],
+        timeout: TimeInterval = 60,
+        maxRetries: Int = 3
+    ) {
+        self.command = command
+        self.args = args
+        self.timeout = timeout
+        self.maxRetries = maxRetries
+    }
+
+    public var tools: ToolClient {
+        ToolClient(client: self)
+    }
+
+    public func close() {
+        process?.terminate()
+        process = nil
+    }
+
+    deinit {
+        process?.terminate()
+    }
+}
+
+public struct ToolClient {
+    private let client: ConductorClient
+
+    fileprivate init(client: ConductorClient) {
+        self.client = client
+    }
+
+    public func call(_ name: String, args: [String: Any]? = nil) async throws -> ToolResult {
+        // TODO: Implement stdio MCP protocol client
+        fatalError("Not implemented yet")
+    }
+}
+
+public struct ToolResult {
+    public let success: Bool
+    public let data: [String: Any]?
+    public let error: String?
+    public let latencyMs: Int?
+}

package/skills/conductor-mcp/SKILL.md

@@ -0,0 +1,38 @@
+# Conductor Integration Hub
+
+Conductor connects Claude Code to 25+ external services through MCP tools.
+
+## When to use Conductor tools
+
+- **GitHub** — list repos, create issues, check PRs, trigger Actions, manage releases
+- **Gmail** — read, send, search, organize emails
+- **Google Calendar** — check schedules, create events, find free time
+- **Google Drive** — search, read, upload files
+- **Slack** — send messages, read channels
+- **Notion** — create pages, query databases, update notes
+- **Spotify** — control playback, search tracks, manage playlists
+- **Vercel** — check deployments, view project status
+- **HomeKit** — control smart home devices, check sensors
+- **Weather** — get current conditions and forecasts
+- **System** — check CPU, memory, disk usage
+- **Network** — ping hosts, check connectivity
+- **n8n** — trigger automation workflows
+- **Calculator, Crypto, Hash, URL tools** — utility operations
+
+## Setup
+
+```bash
+npm install && npm run build
+conductor mcp setup
+
+# Configure services
+conductor google          # Gmail, Calendar, Drive (OAuth)
+conductor slack setup     # Slack tokens
+conductor plugins enable github
+conductor plugins enable notion
+conductor plugins enable spotify
+```
+
+## Tool naming
+
+All tools are prefixed with `conductor_`. Use `conductor_status` to check which plugins are active before attempting service-specific operations.

package/src/README.md

@@ -0,0 +1,20 @@
+# src
+
+Root source directory for the Conductor MCP server. Contains all application modules organized by concern.
+
+## Contents
+
+- `core/` - Central orchestration, config, database, and plugin management
+- `mcp/` - Model Context Protocol server implementation
+- `plugins/` - Plugin system with builtin and external plugin support
+- `cli/` - Command-line interface built with Commander
+- `dashboard/` - Web dashboard (Express + single-page app)
+- `ai/` - Multi-provider AI manager (Claude, OpenAI, Gemini, Ollama)
+- `bot/` - Telegram bot and Slack Bolt integrations
+- `security/` - Authentication, keychain, and encryption utilities
+- `config/` - OAuth and configuration helpers
+- `utils/` - Shared utility functions
+
+## Architecture
+
+This is the top-level source tree. All modules are imported from here and compiled to `dist/` via `tsx`. The codebase uses ESM (`"type": "module"`) with `Node16` module resolution — all imports must use `.js` extensions even for `.ts` source files.

package/src/ai/README.md

@@ -0,0 +1,18 @@
+# src/ai
+
+Multi-provider AI manager for Conductor. Supports Claude, OpenAI, Gemini, Ollama, and OpenRouter.
+
+## Contents
+
+- `manager.ts` - `AIManager` orchestrating multiple AI providers
+- `base.ts` - Base provider interface and shared logic
+- `claude.ts` - Anthropic Claude provider
+- `openai.ts` - OpenAI provider
+- `gemini.ts` - Google Gemini provider
+- `ollama.ts` - Ollama (local) provider
+- `openrouter.ts` - OpenRouter meta-provider
+- `maestro.ts` - AI orchestration and routing logic
+
+## Architecture
+
+`AIManager` abstracts over multiple AI providers, allowing users to configure and switch between them. Each provider implements a common interface. The `maestro.ts` module handles intelligent routing and fallback between providers. Used by the MCP server for tool responses and by the bot for proactive reasoning.

package/src/ai/base.ts

@@ -0,0 +1,93 @@
+import { PluginTool } from '../plugins/manager.js';
+
+export interface AIToolCall {
+  id: string;
+  name: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  arguments: Record<string, any>;
+}
+
+export interface AIMessage {
+  role: 'user' | 'assistant' | 'system' | 'tool';
+  content: string;
+  tool_calls?: AIToolCall[];
+  tool_call_id?: string;
+  name?: string; // Best practice for tool responses
+}
+
+export interface AIResponse {
+  content: string;
+  model: string;
+  tokens_used?: number;
+  finish_reason?: string;
+  tool_calls?: AIToolCall[];
+}
+
+export interface AIProviderConfig {
+  apiKey?: string;
+  endpoint?: string;
+  model?: string;
+  maxTokens?: number;
+}
+
+export abstract class AIProvider {
+  protected config: AIProviderConfig;
+
+  constructor(config: AIProviderConfig) {
+    this.config = config;
+  }
+
+  /** Send a message and get a response. */
+  abstract complete(messages: AIMessage[], tools?: PluginTool[]): Promise<AIResponse>;
+
+  /** Stream a response (for real-time output). */
+  abstract stream(messages: AIMessage[], tools?: PluginTool[]): AsyncGenerator<string>;
+
+  /** Test if the provider is configured correctly. */
+  abstract test(): Promise<boolean>;
+
+  /** Get provider display name. */
+  abstract getName(): string;
+
+  /**
+   * Parse user intent from a natural-language message.
+   * Used by the Telegram bot to route commands to plugins.
+   */
+  async parseIntent(userMessage: string): Promise<any> {
+    const systemPrompt = `You are a command parser for Conductor, an integration hub.
+Parse user messages into structured intents.
+
+Available intents:
+- install_plugin: { plugin: string }
+- list_plugins: {}
+- enable_plugin: { plugin: string }
+- disable_plugin: { plugin: string }
+- execute_action: { plugin: string, action: string, params: object }
+- get_status: {}
+- help: {}
+- chat: { message: string }
+
+Examples:
+"install github" → { "type": "install_plugin", "plugin": "github" }
+"list my repos" → { "type": "execute_action", "plugin": "github", "action": "list_repos" }
+"show status" → { "type": "get_status" }
+"hello" → { "type": "chat", "message": "hello" }
+
+Respond with JSON only. If unclear, use type "chat". Always use English for any string values.`;
+
+    const response = await this.complete([
+      { role: 'system', content: systemPrompt },
+      { role: 'user', content: userMessage },
+    ]);
+
+    try {
+      const jsonMatch = response.content.match(/\{[\s\S]*\}/);
+      if (jsonMatch) {
+        return JSON.parse(jsonMatch[0]);
+      }
+      return { type: 'chat', message: userMessage };
+    } catch {
+      return { type: 'chat', message: userMessage };
+    }
+  }
+}