portos-ai-toolkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Adam Eivy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# portos-ai-toolkit
+
+Shared AI provider, model, and prompt template patterns for PortOS-style applications.
+
+## Installation
+
+```bash
+npm install portos-ai-toolkit
+```
+
+## Features
+
+- **Provider Management**: Support for CLI-based (Claude Code, Codex, etc.) and API-based (OpenAI-compatible) AI providers
+- **Prompt Templates**: Reusable prompt template system with variable interpolation
+- **Run History**: Track and manage AI run history with streaming support
+- **React Components**: Ready-to-use React components and hooks for AI provider management
+- **Express Routes**: Pre-built Express route handlers for provider, prompt, and run management
+
+## Usage
+
+### Server-side
+
+```javascript
+import { createAIRoutes, ProvidersService, RunnerService } from 'portos-ai-toolkit/server';
+import express from 'express';
+
+const app = express();
+
+// Initialize services
+const providersService = new ProvidersService('./data');
+const runnerService = new RunnerService(providersService);
+
+// Mount AI routes
+app.use('/api', createAIRoutes({ providersService, runnerService }));
+```
+
+### Client-side
+
+```javascript
+import { AIProviders, useProviders, createApiClient } from 'portos-ai-toolkit/client';
+
+// Use the full-featured AIProviders page component
+function ProvidersPage() {
+  return <AIProviders onError={console.error} colorPrefix="app" />;
+}
+
+// Or use hooks for custom implementations
+function CustomComponent() {
+  const { providers, loading, refresh } = useProviders();
+  // ...
+}
+```
+
+### Shared utilities
+
+```javascript
+import { PROVIDER_TYPES, DEFAULT_TIMEOUT } from 'portos-ai-toolkit/shared';
+```
+
+## Provider Types
+
+### CLI Providers
+Execute AI commands via CLI tools like Claude Code or Codex:
+- Claude Code CLI (`claude`)
+- Codex CLI (`codex`)
+- Custom CLI tools
+
+### API Providers
+Connect to OpenAI-compatible APIs:
+- LM Studio
+- Ollama
+- OpenAI
+- Any OpenAI-compatible endpoint
+
+## API Reference
+
+### Server Exports (`portos-ai-toolkit/server`)
+
+- `createAIRoutes(options)` - Create Express router with all AI routes
+- `ProvidersService` - Manage AI provider configurations
+- `RunnerService` - Execute prompts and manage runs
+- `PromptsService` - Manage prompt templates
+- Route handlers: `createProvidersRoutes`, `createRunsRoutes`, `createPromptsRoutes`
+
+### Client Exports (`portos-ai-toolkit/client`)
+
+- `AIProviders` - Full-featured provider management page component
+- `ProviderDropdown` - Dropdown for selecting providers
+- `useProviders()` - Hook for provider state management
+- `useRuns()` - Hook for run history
+- `createApiClient(baseUrl)` - Create API client instance
+
+### Shared Exports (`portos-ai-toolkit/shared`)
+
+- `PROVIDER_TYPES` - Provider type constants
+- `DEFAULT_TIMEOUT` - Default timeout value
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "portos-ai-toolkit",
+  "version": "0.1.0",
+  "description": "Shared AI provider, model, and prompt template patterns for PortOS-style applications",
+  "author": "Adam Eivy <adam@eivy.com> (https://atomantic.com)",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./server": "./src/server/index.js",
+    "./client": "./src/client/index.js",
+    "./shared": "./src/shared/index.js"
+  },
+  "files": [
+    "src/**/*"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/atomantic/portos-ai-toolkit.git"
+  },
+  "homepage": "https://github.com/atomantic/portos-ai-toolkit#readme",
+  "bugs": {
+    "url": "https://github.com/atomantic/portos-ai-toolkit/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "zod": "^3.24.1",
+    "uuid": "^11.0.3"
+  },
+  "peerDependencies": {
+    "express": "^4.21.2 || ^5.2.1",
+    "socket.io": "^4.8.3",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
+    "socket.io": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.16",
+    "supertest": "^7.1.4",
+    "vitest": "^4.0.16"
+  },
+  "keywords": [
+    "ai",
+    "providers",
+    "llm",
+    "claude",
+    "openai",
+    "ollama",
+    "lm-studio",
+    "prompts",
+    "templates",
+    "portos"
+  ]
+}

package/src/client/api.js

@@ -0,0 +1,102 @@
+/**
+ * API Client for AI Toolkit
+ * Configurable API requests for providers and runs
+ */
+
+/**
+ * Create an API client with configurable base URL and error handler
+ */
+export function createApiClient(config = {}) {
+  const {
+    baseUrl = '/api',
+    onError = (error) => console.error(error)
+  } = config;
+
+  async function request(endpoint, options = {}) {
+    const url = `${baseUrl}${endpoint}`;
+    const requestConfig = {
+      headers: {
+        'Content-Type': 'application/json',
+        ...options.headers
+      },
+      ...options
+    };
+
+    const response = await fetch(url, requestConfig);
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: 'Request failed' }));
+      const errorMessage = error.error || `HTTP ${response.status}`;
+      onError(errorMessage);
+      throw new Error(errorMessage);
+    }
+
+    // Handle 204 No Content
+    if (response.status === 204) {
+      return null;
+    }
+
+    // Handle text/plain responses
+    const contentType = response.headers.get('content-type');
+    if (contentType?.includes('text/plain')) {
+      return response.text();
+    }
+
+    return response.json();
+  }
+
+  return {
+    // Providers
+    providers: {
+      getAll: () => request('/providers'),
+      getActive: () => request('/providers/active'),
+      setActive: (id) => request('/providers/active', {
+        method: 'PUT',
+        body: JSON.stringify({ id })
+      }),
+      getById: (id) => request(`/providers/${id}`),
+      create: (data) => request('/providers', {
+        method: 'POST',
+        body: JSON.stringify(data)
+      }),
+      update: (id, data) => request(`/providers/${id}`, {
+        method: 'PUT',
+        body: JSON.stringify(data)
+      }),
+      delete: (id) => request(`/providers/${id}`, {
+        method: 'DELETE'
+      }),
+      test: (id) => request(`/providers/${id}/test`, {
+        method: 'POST'
+      }),
+      refreshModels: (id) => request(`/providers/${id}/refresh-models`, {
+        method: 'POST'
+      })
+    },
+
+    // Runs
+    runs: {
+      list: (limit = 50, offset = 0, source = 'all') =>
+        request(`/runs?limit=${limit}&offset=${offset}&source=${source}`),
+      create: (data) => request('/runs', {
+        method: 'POST',
+        body: JSON.stringify(data)
+      }),
+      getById: (id) => request(`/runs/${id}`),
+      getOutput: (id) => request(`/runs/${id}/output`),
+      getPrompt: (id) => request(`/runs/${id}/prompt`),
+      stop: (id) => request(`/runs/${id}/stop`, {
+        method: 'POST'
+      }),
+      delete: (id) => request(`/runs/${id}`, {
+        method: 'DELETE'
+      }),
+      deleteFailedRuns: () => request('/runs?filter=failed', {
+        method: 'DELETE'
+      })
+    }
+  };
+}
+
+// Default export with default config
+export default createApiClient();

package/src/client/components/ProviderDropdown.jsx

@@ -0,0 +1,39 @@
+/**
+ * Provider Dropdown Component
+ * Dropdown for selecting an AI provider
+ */
+
+export function ProviderDropdown({
+  providers = [],
+  value,
+  onChange,
+  filter = null,
+  showType = false,
+  placeholder = 'Select provider...',
+  className = '',
+  theme = {}
+}) {
+  const {
+    bg = 'bg-port-bg',
+    border = 'border-port-border',
+    text = 'text-white'
+  } = theme;
+
+  const filteredProviders = filter ? providers.filter(filter) : providers;
+
+  return (
+    <select
+      value={value || ''}
+      onChange={(e) => onChange(e.target.value)}
+      className={`px-3 py-2 ${bg} border ${border} rounded-lg ${text} ${className}`}
+    >
+      <option value="">{placeholder}</option>
+      {filteredProviders.map(provider => (
+        <option key={provider.id} value={provider.id}>
+          {provider.name}
+          {showType && ` (${provider.type})`}
+        </option>
+      ))}
+    </select>
+  );
+}

package/src/client/components/index.js

@@ -0,0 +1,5 @@
+/**
+ * AI Toolkit React Components
+ */
+
+export { ProviderDropdown } from './ProviderDropdown.jsx';

package/src/client/hooks/index.js

@@ -0,0 +1,6 @@
+/**
+ * AI Toolkit React Hooks
+ */
+
+export { useProviders } from './useProviders.js';
+export { useRuns } from './useRuns.js';

package/src/client/hooks/useProviders.js

@@ -0,0 +1,96 @@
+import { useState, useEffect, useCallback } from 'react';
+
+/**
+ * Hook for managing AI providers
+ */
+export function useProviders(apiClient, options = {}) {
+  const { autoLoad = true } = options;
+
+  const [providers, setProviders] = useState([]);
+  const [activeProvider, setActiveProvider] = useState(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState(null);
+
+  const loadProviders = useCallback(async () => {
+    if (!apiClient) {
+      setError('API client not configured');
+      return;
+    }
+
+    setIsLoading(true);
+    setError(null);
+
+    const data = await apiClient.providers.getAll().catch(err => {
+      setError(err.message);
+      return { providers: [], activeProvider: null };
+    });
+
+    setProviders(data.providers || []);
+    setActiveProvider(data.activeProvider);
+    setIsLoading(false);
+  }, [apiClient]);
+
+  const setActive = useCallback(async (id) => {
+    if (!apiClient) return;
+
+    await apiClient.providers.setActive(id);
+    setActiveProvider(id);
+  }, [apiClient]);
+
+  const createProvider = useCallback(async (data) => {
+    if (!apiClient) return null;
+
+    const provider = await apiClient.providers.create(data);
+    await loadProviders();
+    return provider;
+  }, [apiClient, loadProviders]);
+
+  const updateProvider = useCallback(async (id, data) => {
+    if (!apiClient) return null;
+
+    const provider = await apiClient.providers.update(id, data);
+    await loadProviders();
+    return provider;
+  }, [apiClient, loadProviders]);
+
+  const deleteProvider = useCallback(async (id) => {
+    if (!apiClient) return;
+
+    await apiClient.providers.delete(id);
+    await loadProviders();
+  }, [apiClient, loadProviders]);
+
+  const testProvider = useCallback(async (id) => {
+    if (!apiClient) return null;
+
+    return apiClient.providers.test(id);
+  }, [apiClient]);
+
+  const refreshModels = useCallback(async (id) => {
+    if (!apiClient) return null;
+
+    const provider = await apiClient.providers.refreshModels(id);
+    await loadProviders();
+    return provider;
+  }, [apiClient, loadProviders]);
+
+  useEffect(() => {
+    if (autoLoad) {
+      loadProviders();
+    }
+  }, [autoLoad, loadProviders]);
+
+  return {
+    providers,
+    activeProvider,
+    isLoading,
+    error,
+    refetch: loadProviders,
+    setActive,
+    createProvider,
+    updateProvider,
+    deleteProvider,
+    testProvider,
+    refreshModels
+  };
+}

package/src/client/hooks/useRuns.js

@@ -0,0 +1,94 @@
+import { useState, useEffect, useCallback } from 'react';
+
+/**
+ * Hook for managing AI runs
+ */
+export function useRuns(apiClient, options = {}) {
+  const { autoLoad = true, limit = 50, offset = 0, source = 'all' } = options;
+
+  const [runs, setRuns] = useState([]);
+  const [total, setTotal] = useState(0);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState(null);
+
+  const loadRuns = useCallback(async () => {
+    if (!apiClient) {
+      setError('API client not configured');
+      return;
+    }
+
+    setIsLoading(true);
+    setError(null);
+
+    const data = await apiClient.runs.list(limit, offset, source).catch(err => {
+      setError(err.message);
+      return { runs: [], total: 0 };
+    });
+
+    setRuns(data.runs || []);
+    setTotal(data.total || 0);
+    setIsLoading(false);
+  }, [apiClient, limit, offset, source]);
+
+  const createRun = useCallback(async (data) => {
+    if (!apiClient) return null;
+
+    const result = await apiClient.runs.create(data);
+    await loadRuns();
+    return result;
+  }, [apiClient, loadRuns]);
+
+  const stopRun = useCallback(async (id) => {
+    if (!apiClient) return;
+
+    await apiClient.runs.stop(id);
+    await loadRuns();
+  }, [apiClient, loadRuns]);
+
+  const deleteRun = useCallback(async (id) => {
+    if (!apiClient) return;
+
+    await apiClient.runs.delete(id);
+    await loadRuns();
+  }, [apiClient, loadRuns]);
+
+  const deleteFailedRuns = useCallback(async () => {
+    if (!apiClient) return;
+
+    const result = await apiClient.runs.deleteFailedRuns();
+    await loadRuns();
+    return result;
+  }, [apiClient, loadRuns]);
+
+  const getRunOutput = useCallback(async (id) => {
+    if (!apiClient) return null;
+
+    return apiClient.runs.getOutput(id);
+  }, [apiClient]);
+
+  const getRunPrompt = useCallback(async (id) => {
+    if (!apiClient) return null;
+
+    return apiClient.runs.getPrompt(id);
+  }, [apiClient]);
+
+  useEffect(() => {
+    if (autoLoad) {
+      loadRuns();
+    }
+  }, [autoLoad, loadRuns]);
+
+  return {
+    runs,
+    total,
+    isLoading,
+    error,
+    refetch: loadRuns,
+    createRun,
+    stopRun,
+    deleteRun,
+    deleteFailedRuns,
+    getRunOutput,
+    getRunPrompt
+  };
+}

package/src/client/index.js

@@ -0,0 +1,11 @@
+/**
+ * AI Toolkit Client
+ * React components, hooks, and API client for AI providers and runs
+ */
+
+export { createApiClient } from './api.js';
+export * from './hooks/index.js';
+export * from './components/index.js';
+
+// Pages
+export { default as AIProviders } from './pages/AIProviders.jsx';