Initial commit: MUDlet AI Client with Telnet + Ollama integration
This commit is contained in:
truetype committed
commit
a1b7191098
22 files changed
+2197
No files matched your search
+373
@@ -0,0 +1,373 @@
|
||||
# API IPC Reference
|
||||
|
||||
## Context Bridge
|
||||
|
||||
Tutte le API sono esposte tramite `window.electronAPI`:
|
||||
|
||||
```typescript
|
||||
// TypeScript declaration
|
||||
interface ElectronAPI {
|
||||
// Telnet
|
||||
telnetConnect: (host: string, port: number) => Promise<boolean>;
|
||||
telnetDisconnect: () => Promise<void>;
|
||||
telnetSend: (data: string) => Promise<boolean>;
|
||||
telnetGetOutput: () => Promise<string>;
|
||||
onTelnetOutput: (callback: (data: string) => void) => void;
|
||||
|
||||
// Ollama
|
||||
ollamaChat: (messages: OllamaMessage[], options?: OllamaOptions) => Promise<OllamaResponse>;
|
||||
ollamaGetModels: () => Promise<string[]>;
|
||||
ollamaIsAvailable: () => Promise<boolean>;
|
||||
|
||||
// Autoplayer
|
||||
autoplayerConfigure: (config: AutoplayerConfig) => Promise<void>;
|
||||
autoplayerStart: () => Promise<void>;
|
||||
autoplayerStop: () => Promise<void>;
|
||||
autoplayerIsActive: () => Promise<boolean>;
|
||||
autoplayerExecuteAction: (action: string) => Promise<void>;
|
||||
onAutoplayerDecision: (callback: (decision: string) => void) => void;
|
||||
onAutoplayerAction: (callback: (action: string) => void) => void;
|
||||
onAutoplayerState: (callback: (state: GameState) => void) => void;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Telnet API
|
||||
|
||||
### telnetConnect
|
||||
|
||||
Stabilisce connessione Telnet al server MUD.
|
||||
|
||||
```typescript
|
||||
const connected = await window.electronAPI.telnetConnect('172.24.19.225', 6666);
|
||||
```
|
||||
|
||||
**Params:**
|
||||
| Param | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| host | string | Indirizzo server MUD |
|
||||
| port | number | Porta Telnet |
|
||||
|
||||
**Returns:** `Promise<boolean>` - true se connessione riuscita
|
||||
|
||||
**Errors:** Connection timeout, host unreachable
|
||||
|
||||
### telnetDisconnect
|
||||
|
||||
Chiude connessione Telnet.
|
||||
|
||||
```typescript
|
||||
await window.electronAPI.telnetDisconnect();
|
||||
```
|
||||
|
||||
### telnetSend
|
||||
|
||||
Invia comando al server MUD.
|
||||
|
||||
```typescript
|
||||
const sent = await window.electronAPI.telnetSend('look\n');
|
||||
```
|
||||
|
||||
**Params:**
|
||||
| Param | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| data | string | Comando da inviare (newline esclusa) |
|
||||
|
||||
**Returns:** `Promise<boolean>` - true se invio riuscito
|
||||
|
||||
### telnetGetOutput
|
||||
|
||||
Restituisce buffer output Telnet accumulato.
|
||||
|
||||
```typescript
|
||||
const output = await window.electronAPI.telnetGetOutput();
|
||||
```
|
||||
|
||||
**Returns:** `Promise<string>` - Output completo con HTML colors
|
||||
|
||||
### onTelnetOutput
|
||||
|
||||
Subscribe a nuovi output dal server.
|
||||
|
||||
```typescript
|
||||
window.electronAPI.onTelnetOutput((data) => {
|
||||
console.log('Nuovo output:', data);
|
||||
});
|
||||
```
|
||||
|
||||
**Callback Params:**
|
||||
| Param | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| data | string | Chunk output HTML |
|
||||
|
||||
---
|
||||
|
||||
## Ollama API
|
||||
|
||||
### ollamaChat
|
||||
|
||||
Invia messaggi a Ollama e riceve risposta.
|
||||
|
||||
```typescript
|
||||
const response = await window.electronAPI.ollamaChat([
|
||||
{ role: 'system', content: 'You are a MUD player' },
|
||||
{ role: 'user', content: 'What should I do?' }
|
||||
], {
|
||||
model: 'llama3.2',
|
||||
temperature: 0.7
|
||||
});
|
||||
```
|
||||
|
||||
**Params:**
|
||||
| Param | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| messages | OllamaMessage[] | Storico conversazione |
|
||||
| options | OllamaOptions | Opzioni (opzionali) |
|
||||
|
||||
**OllamaMessage:**
|
||||
```typescript
|
||||
{
|
||||
role: 'user' | 'assistant' | 'system';
|
||||
content: string;
|
||||
}
|
||||
```
|
||||
|
||||
**OllamaOptions:**
|
||||
```typescript
|
||||
{
|
||||
model?: string; // Default: 'llama3.2'
|
||||
temperature?: number; // Default: 0.7
|
||||
}
|
||||
```
|
||||
|
||||
**Returns:** `Promise<OllamaResponse>`
|
||||
```typescript
|
||||
{
|
||||
model: string;
|
||||
response: string;
|
||||
done: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
### ollamaGetModels
|
||||
|
||||
Lista modelli disponibili sul server.
|
||||
|
||||
```typescript
|
||||
const models = await window.electronAPI.ollamaGetModels();
|
||||
// ['llama3.2', 'llama3.1', 'mistral', ...]
|
||||
```
|
||||
|
||||
**Returns:** `Promise<string[]>` - Nomi modelli
|
||||
|
||||
### ollamaIsAvailable
|
||||
|
||||
Verifica se server Ollama raggiungibile.
|
||||
|
||||
```typescript
|
||||
const available = await window.electronAPI.ollamaIsAvailable();
|
||||
// true se server risponde
|
||||
```
|
||||
|
||||
**Returns:** `Promise<boolean>`
|
||||
|
||||
---
|
||||
|
||||
## Autoplayer API
|
||||
|
||||
### autoplayerConfigure
|
||||
|
||||
Configura comportamento autoplayer.
|
||||
|
||||
```typescript
|
||||
await window.electronAPI.autoplayerConfigure({
|
||||
model: 'llama3.2',
|
||||
systemPrompt: 'You are an explorer...',
|
||||
temperature: 0.7,
|
||||
autoSend: true
|
||||
});
|
||||
```
|
||||
|
||||
**AutoplayerConfig:**
|
||||
```typescript
|
||||
{
|
||||
model: string; // Model LLM
|
||||
systemPrompt: string; // Personalità bot
|
||||
temperature?: number; // Creatività (0.0-1.0)
|
||||
autoSend?: boolean; // Auto-esegui azioni
|
||||
}
|
||||
```
|
||||
|
||||
### autoplayerStart
|
||||
|
||||
Avvia loop autoplayer.
|
||||
|
||||
```typescript
|
||||
await window.electronAPI.autoplayerStart();
|
||||
```
|
||||
|
||||
### autoplayerStop
|
||||
|
||||
Ferma loop autoplayer.
|
||||
|
||||
```typescript
|
||||
await window.electronAPI.autoplayerStop();
|
||||
```
|
||||
|
||||
### autoplayerIsActive
|
||||
|
||||
Verifica se autoplayer in esecuzione.
|
||||
|
||||
```typescript
|
||||
const active = await window.electronAPI.autoplayerIsActive();
|
||||
```
|
||||
|
||||
**Returns:** `Promise<boolean>`
|
||||
|
||||
### autoplayerExecuteAction
|
||||
|
||||
Esegui azione manualmente (senza passare per decision engine).
|
||||
|
||||
```typescript
|
||||
await window.electronAPI.autoplayerExecuteAction('go north');
|
||||
```
|
||||
|
||||
### onAutoplayerDecision
|
||||
|
||||
Subscribe a decisioni LLM.
|
||||
|
||||
```typescript
|
||||
window.electronAPI.onAutoplayerDecision((decision) => {
|
||||
console.log('LLM decision:', decision);
|
||||
});
|
||||
```
|
||||
|
||||
**Callback Params:**
|
||||
| Param | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| decision | string | Risposta completa LLM |
|
||||
|
||||
### onAutoplayerAction
|
||||
|
||||
Subscribe ad azioni generate.
|
||||
|
||||
```typescript
|
||||
window.electronAPI.onAutoplayerAction((action) => {
|
||||
console.log('Action to execute:', action);
|
||||
});
|
||||
```
|
||||
|
||||
**Callback Params:**
|
||||
| Param | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| action | string | Comando da eseguire |
|
||||
|
||||
### onAutoplayerState
|
||||
|
||||
Subscribe a updates stato gioco parsato.
|
||||
|
||||
```typescript
|
||||
window.electronAPI.onAutoplayerState((state) => {
|
||||
console.log('Current location:', state.location);
|
||||
console.log('Exits:', state.exits);
|
||||
});
|
||||
```
|
||||
|
||||
**GameState:**
|
||||
```typescript
|
||||
{
|
||||
location: string; // Nome location corrente
|
||||
description: string; // Descrizione stanza
|
||||
exits: string[]; // Uscite disponibili
|
||||
players: string[]; // Giocatori presenti
|
||||
objects: string[]; // Oggetti nella stanza
|
||||
health?: string; // HP corrente
|
||||
mana?: string; // Mana corrente
|
||||
prompt?: string; // Prompt del gioco
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Esempi Completi
|
||||
|
||||
### Connessione e Game Loop
|
||||
|
||||
```typescript
|
||||
// 1. Connetti
|
||||
const connected = await window.electronAPI.telnetConnect('172.24.19.225', 6666);
|
||||
if (!connected) {
|
||||
console.error('Connessione fallita');
|
||||
return;
|
||||
}
|
||||
|
||||
// 2. Subscribe output
|
||||
window.electronAPI.onTelnetOutput((data) => {
|
||||
// Aggiorna UI
|
||||
setOutput(prev => prev + data);
|
||||
});
|
||||
|
||||
// 3. Invia comando
|
||||
await window.electronAPI.telnetSend('look\n');
|
||||
```
|
||||
|
||||
### Autoplayer Workflow
|
||||
|
||||
```typescript
|
||||
// 1. Configura
|
||||
await window.electronAPI.autoplayerConfigure({
|
||||
model: 'llama3.2',
|
||||
systemPrompt: 'You are a helpful MUD player. Explore and interact naturally.',
|
||||
temperature: 0.7,
|
||||
autoSend: false // Review manuale azioni
|
||||
});
|
||||
|
||||
// 2. Subscribe decisioni
|
||||
window.electronAPI.onAutoplayerAction((action) => {
|
||||
console.log('Pending action:', action);
|
||||
// Possibile review manuale qui
|
||||
});
|
||||
|
||||
// 3. Avvia
|
||||
await window.electronAPI.autoplayerStart();
|
||||
|
||||
// 4. Per fermare
|
||||
await window.electronAPI.autoplayerStop();
|
||||
```
|
||||
|
||||
### Ollama Chat Diretta
|
||||
|
||||
```typescript
|
||||
// Test chat con Ollama
|
||||
const response = await window.electronAPI.ollamaChat([
|
||||
{ role: 'system', content: 'You are a fantasy game master.' },
|
||||
{ role: 'user', content: 'Describe a dark forest.' }
|
||||
], { temperature: 0.8 });
|
||||
|
||||
console.log(response.response);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
```typescript
|
||||
try {
|
||||
await window.electronAPI.telnetConnect(host, port);
|
||||
} catch (error) {
|
||||
console.error('Connection error:', error);
|
||||
}
|
||||
|
||||
// Event-based errors
|
||||
window.electronAPI.onTelnetOutput((data) => {
|
||||
// Gestisci errori in output
|
||||
});
|
||||
```
|
||||
|
||||
## Note
|
||||
|
||||
- Tutte le chiamate IPC sono asincrone (Promise-based)
|
||||
- Gli eventi devono essere sottoscritti una volta (non in useEffect ripetuti)
|
||||
- Cleanup event listeners quando il componente unmount
|
||||
- Utilizzare `window.electronAPI` solo dopo il mount del componente
|
||||
Reference in new issue
Block a user