('proxy.url') : undefined;
-});
+const replTool = createJavaScriptReplTool();
+
+// Configure runtime providers for artifact/attachment access
+replTool.runtimeProvidersFactory = () => [
+ new AttachmentsRuntimeProvider(attachments),
+ new ArtifactsRuntimeProvider(artifactsPanel, agent, true), // read-write
+];
+
+agent.setTools([replTool]);
```
-Providers requiring proxy:
-- `zai`: Always requires proxy
-- `anthropic`: Only OAuth tokens (`sk-ant-oat-*`) require proxy
+### Extract Document
-## Tool Renderers
+Extract text from documents at URLs:
-Customize how tool calls are displayed:
+```typescript
+import { createExtractDocumentTool } from '@mariozechner/pi-web-ui';
+
+const extractTool = createExtractDocumentTool();
+extractTool.corsProxyUrl = 'https://corsproxy.io/?';
+
+agent.setTools([extractTool]);
+```
+
+### Artifacts Tool
+
+Built into ArtifactsPanel, supports: HTML, SVG, Markdown, text, JSON, images, PDF, DOCX, XLSX.
+
+```typescript
+const artifactsPanel = new ArtifactsPanel();
+artifactsPanel.agent = agent;
+
+// The tool is available as artifactsPanel.tool
+agent.setTools([artifactsPanel.tool]);
+```
+
+### Custom Tool Renderers
```typescript
import { registerToolRenderer, type ToolRenderer } from '@mariozechner/pi-web-ui';
-import { html } from 'lit';
const myRenderer: ToolRenderer = {
- renderParams(params, isStreaming) {
- return html`Calling with: ${JSON.stringify(params)}
`;
- },
- renderResult(params, result) {
- return html`Result: ${result.output}
`;
+ render(params, result, isStreaming) {
+ return {
+ content: html`...
`,
+ isCustom: false, // true = no card wrapper
+ };
},
};
@@ -327,17 +359,15 @@ registerToolRenderer('my_tool', myRenderer);
## Storage
-### AppStorage
-
-Central storage configuration:
+### Setup
```typescript
import {
AppStorage,
IndexedDBStorageBackend,
+ SettingsStore,
ProviderKeysStore,
SessionsStore,
- SettingsStore,
CustomProvidersStore,
setAppStorage,
getAppStorage,
@@ -349,7 +379,7 @@ const providerKeys = new ProviderKeysStore();
const sessions = new SessionsStore();
const customProviders = new CustomProvidersStore();
-// Create backend
+// Create backend with all store configs
const backend = new IndexedDBStorageBackend({
dbName: 'my-app',
version: 1,
@@ -357,6 +387,7 @@ const backend = new IndexedDBStorageBackend({
settings.getConfig(),
providerKeys.getConfig(),
sessions.getConfig(),
+ SessionsStore.getMetadataConfig(),
customProviders.getConfig(),
],
});
@@ -367,14 +398,118 @@ providerKeys.setBackend(backend);
sessions.setBackend(backend);
customProviders.setBackend(backend);
-// Create and set app storage
+// Create and set global storage
const storage = new AppStorage(settings, providerKeys, sessions, customProviders, backend);
setAppStorage(storage);
+```
-// Access anywhere
-const storage = getAppStorage();
-await storage.providerKeys.set('anthropic', 'sk-...');
+### SettingsStore
+
+Key-value settings:
+
+```typescript
+await storage.settings.set('proxy.enabled', true);
+await storage.settings.set('proxy.url', 'https://proxy.example.com');
+const enabled = await storage.settings.get('proxy.enabled');
+```
+
+### ProviderKeysStore
+
+API keys by provider:
+
+```typescript
+await storage.providerKeys.set('anthropic', 'sk-ant-...');
+const key = await storage.providerKeys.get('anthropic');
+const providers = await storage.providerKeys.list();
+```
+
+### SessionsStore
+
+Chat sessions with metadata:
+
+```typescript
+// Save session
await storage.sessions.save(sessionData, metadata);
+
+// Load session
+const data = await storage.sessions.get(sessionId);
+const metadata = await storage.sessions.getMetadata(sessionId);
+
+// List sessions (sorted by lastModified)
+const allMetadata = await storage.sessions.getAllMetadata();
+
+// Update title
+await storage.sessions.updateTitle(sessionId, 'New Title');
+
+// Delete
+await storage.sessions.delete(sessionId);
+```
+
+### CustomProvidersStore
+
+Custom LLM providers:
+
+```typescript
+const provider: CustomProvider = {
+ id: crypto.randomUUID(),
+ name: 'My Ollama',
+ type: 'ollama',
+ baseUrl: 'http://localhost:11434',
+};
+
+await storage.customProviders.set(provider);
+const all = await storage.customProviders.getAll();
+```
+
+## Attachments
+
+Load and process files:
+
+```typescript
+import { loadAttachment, type Attachment } from '@mariozechner/pi-web-ui';
+
+// From File input
+const file = inputElement.files[0];
+const attachment = await loadAttachment(file);
+
+// From URL
+const attachment = await loadAttachment('https://example.com/doc.pdf');
+
+// From ArrayBuffer
+const attachment = await loadAttachment(arrayBuffer, 'document.pdf');
+
+// Attachment structure
+interface Attachment {
+ id: string;
+ type: 'image' | 'document';
+ fileName: string;
+ mimeType: string;
+ size: number;
+ content: string; // base64 encoded
+ extractedText?: string; // For documents
+ preview?: string; // base64 preview image
+}
+```
+
+Supported formats: PDF, DOCX, XLSX, PPTX, images, text files.
+
+## CORS Proxy
+
+For browser environments with CORS restrictions:
+
+```typescript
+import { createStreamFn, shouldUseProxyForProvider, isCorsError } from '@mariozechner/pi-web-ui';
+
+// AgentInterface auto-configures proxy from settings
+// For manual setup:
+agent.streamFn = createStreamFn(async () => {
+ const enabled = await storage.settings.get('proxy.enabled');
+ return enabled ? await storage.settings.get('proxy.url') : undefined;
+});
+
+// Providers requiring proxy:
+// - zai: always
+// - anthropic: only OAuth tokens (sk-ant-oat-*)
```
## Dialogs
@@ -382,9 +517,13 @@ await storage.sessions.save(sessionData, metadata);
### SettingsDialog
```typescript
-import { SettingsDialog, ProvidersModelsTab, ProxyTab } from '@mariozechner/pi-web-ui';
+import { SettingsDialog, ProvidersModelsTab, ProxyTab, ApiKeysTab } from '@mariozechner/pi-web-ui';
-SettingsDialog.open([new ProvidersModelsTab(), new ProxyTab()]);
+SettingsDialog.open([
+ new ProvidersModelsTab(), // Custom providers + model list
+ new ProxyTab(), // CORS proxy settings
+ new ApiKeysTab(), // API keys per provider
+]);
```
### SessionListDialog
@@ -406,6 +545,16 @@ import { ApiKeyPromptDialog } from '@mariozechner/pi-web-ui';
const success = await ApiKeyPromptDialog.prompt('anthropic');
```
+### ModelSelector
+
+```typescript
+import { ModelSelector } from '@mariozechner/pi-web-ui';
+
+ModelSelector.open(currentModel, (selectedModel) => {
+ agent.setModel(selectedModel);
+});
+```
+
## Styling
Import the pre-built CSS:
@@ -414,7 +563,7 @@ Import the pre-built CSS:
import '@mariozechner/pi-web-ui/app.css';
```
-Or customize with your own Tailwind config:
+Or use Tailwind with custom config:
```css
@import '@mariozechner/mini-lit/themes/claude.css';
@@ -423,14 +572,29 @@ Or customize with your own Tailwind config:
@tailwind utilities;
```
+## Internationalization
+
+```typescript
+import { i18n, setLanguage, translations } from '@mariozechner/pi-web-ui';
+
+// Add translations
+translations.de = {
+ 'Loading...': 'Laden...',
+ 'No sessions yet': 'Noch keine Sitzungen',
+};
+
+setLanguage('de');
+console.log(i18n('Loading...')); // "Laden..."
+```
+
## Examples
-- [example/](./example) - Complete web application with sessions, artifacts, and custom messages
+- [example/](./example) - Complete web app with sessions, artifacts, custom messages
- [sitegeist](https://github.com/badlogic/sitegeist) - Browser extension using pi-web-ui
-## Known Bugs
+## Known Issues
-- **PersistentStorageDialog**: Currently broken and commented out in examples
+- **PersistentStorageDialog**: Currently broken
## License