Interfaces ========== Interfaces provide the communication layer between synth and external platforms. Like plugins and Cortex engines, interfaces are completely modular and automatically discovered at runtime. This ensures that platform integrations are decoupled from the core system and can be developed independently. Interface Architecture ---------------------- All interfaces follow a consistent architecture: - **Auto-Discovery**: Interfaces are automatically found in the ``interface/`` directory - **Standard Interface**: Interfaces extend ``AIPluginBase`` or implement compatible methods - **Action Providers**: Interfaces can provide actions (sending messages, media, etc.) - **Security Integration**: Built-in trainer ID validation and rate limiting - **Platform Abstraction**: Unified message format across different platforms Available Interfaces -------------------- **Stable Interfaces** (in ``interface/`` directory): * ``discord_interface`` – Discord bot integration. Requires ``DISCORD_BOT_TOKEN``. * ``matrix_interface`` – Matrix chat bridge powered by ``matrix-nio``. Requires homeserver credentials and tokenizer (password or access token). * ``ollama_compat_server`` – Ollama-compatible REST bridge that lets external clients talk to SyntH as if it were an Ollama instance. * ``telegram_bot`` – Telegram bot interface with media support. Requires ``BOTFATHER_TOKEN`` and trainer ID. **Development Interfaces** (in ``interface_dev/`` directory): * ``cli`` – Local command-line interface for direct interaction (no configuration). * ``reddit_interface`` – Asynchronous Reddit client for posts, comments, and DMs. Requires Reddit API credentials. * ``telethon_userbot`` – Advanced Telegram userbot using Telethon. Requires ``API_ID``, ``API_HASH``, and session. * ``webui`` – FastAPI-based web interface for browser access. Configurable host/port. * ``x_interface`` – Experimental X (Twitter) integration with timeline features. Requires ``X_USERNAME``. Discord Interface ----------------- The Discord interface provides full bot integration: **Setup Steps:** 1. Create an application at `Discord Developer Portal `_ 2. Add a bot user and copy the token 3. Enable required intents (Message Content Intent, etc.) 4. Generate invite URL with bot scope and permissions 5. Set ``DISCORD_BOT_TOKEN`` in environment variables 6. Start synth - the interface loads automatically **Features:** - Real-time message handling - Media upload/download support - Thread and channel management - Role and permission integration Telegram Bot Interface ---------------------- The Telegram bot interface offers comprehensive Telegram integration: **Configuration:** .. code-block:: bash BOTFATHER_TOKEN=your_bot_token TRAINER_IDS=telegram_bot:123456789 **Features:** - Message threading support - Media handling (photos, documents, voice) - Inline keyboard and callback support - Group and private chat handling - Trainer ID security validation - Wake/Sleep attention mode (commands ``/wake`` ``/awake`` ``/sleep`` ``/status``) - **Default**: awake (listens to all messages in the chat) - ``/sleep``: switches to mention/reply-only handling for that chat - ``/wake`` / ``/awake``: restores awake behavior - ``/status``: shows the current mode - ``CHAT_SLEEP_COMMANDS`` / ``CHAT_WAKE_COMMANDS``: configurable comma-separated phrases that can act as chat-level sleep/wake triggers (set via WebUI). Reddit Interface ---------------- The Reddit interface enables social media integration: **Required Credentials:** .. code-block:: bash REDDIT_CLIENT_ID=your_client_id REDDIT_CLIENT_SECRET=your_client_secret REDDIT_USERNAME=your_username REDDIT_PASSWORD=your_password REDDIT_USER_AGENT=synthFreedomProject/1.0 **Capabilities:** - Post creation and commenting - Direct message handling - Subreddit monitoring - User interaction tracking Web UI Interface ---------------- The web interface provides browser-based access: **Configuration:** .. code-block:: bash SYNTH_WEBUI_HOST=0.0.0.0 SYNTH_WEBUI_HTTP_PORT=8001 SYNTH_WEBUI_HTTPS_PORT=8000 See also: :doc:`compose_env_vars` for a complete list of Compose variables, defaults and recommendations. **Features:** - Modern web interface - Real-time chat updates - File upload support - Responsive design **Extended API Endpoints** The Web UI exposes additional endpoints used by external integrations such as Mate-Engine: - ``GET /api/animation_state`` – Current centralized animation state - ``POST /api/animation_state`` – Request a centralized animation state change. Body: ``{state, session_id?, loop?, context_id?, source?}`` - ``POST /api/animations/upload`` – Temporary animation upload (FBX/VRMA) - ``GET /api/animations/uploads`` – List temporary animation uploads - ``DELETE /api/animations/uploads/{upload_id}`` – Remove a temporary upload - ``POST /api/animations/promote`` – Promote a temporary upload into a skin - ``GET /api/about`` – About summary payload (uptime, sessions, system info) - ``GET /api/prompt_override`` – Interface prompt injection/override hints - ``POST /api/integrations/messages`` – Generic integration message endpoint. Body: ``{source, type, payload, metadata}``. ``type=chat`` is forwarded to the message chain; other types are stored for retrieval. - ``GET /api/integrations/outbox?source=`` – Retrieve queued messages for a given integration source (clears the queue on read). Use ``source=mate`` for Mate Engine clients. Plugins ------- A convenience plugin, ``plugins/mate_engine.py``, is provided as an optional integration helper. It exposes actions that LLMs can call and implements policy-sensitive behaviour such as promotion of temporary uploads: - ``send_mate_message`` – Enqueue a message to the Mate outbox (source="mate"). - ``promote_upload`` – Promote a temporary upload into a skin (requires ``SYNTH_MATEENGINE_PROMOTE_ENABLED=1`` to permit promotion). Set ``SYNTH_MATEENGINE_PROMOTE_ENABLED=1`` to enable promotion from uploads into person skins (default: disabled). **Mate Engine Flags** - ``SYNTH_MATEENGINE_UPLOAD_TTL_DAYS`` – Days before temporary uploads are removed (default: 7) - ``SYNTH_MATEENGINE_UPLOAD_CLEANUP_INTERVAL_S`` – Cleanup interval in seconds (default: 3600) - ``SYNTH_MATEENGINE_PROMOTE_ENABLED`` – Set to ``1`` to allow promotion of uploads Ollama-Compatible Server ------------------------ The **Ollama compatibility server** exposes Synthetic Heart through the same HTTP API used by `ollama `_. Any tool that can talk to an Ollama daemon—desktop chat apps, browser extensions, automation tooling—can instead point at SyntH and receive the responses generated by your active persona. **What it does** - Implements ``/api/generate`` and ``/api/chat`` with streaming NDJSON output. - Mirrors the Ollama ``/api/tags`` endpoint so discovery requests return a synthetic model catalogue. - Translates incoming prompts into the synth message chain, letting the currently loaded Cortex engine drive the reply. **Configuration** .. code-block:: bash OLLAMA_HOST=0.0.0.0 # Bind address for the compatibility server OLLAMA_PORT=11435 # Default Ollama port; update if you already run a native instance OLLAMA_DEFAULT_MODEL=SyntH # Name reported to clients when no model is specified OLLAMA_DEFAULT_MODEL_DISPLAY="Synthetic Heart" # Friendly label in /api/tags OLLAMA_MAX_HISTORY=20 # Conversation turns preserved between requests OLLAMA_STREAM_TIMEOUT=10.0 # Seconds to wait between streamed chunks before timing out OLLAMA_COMPLETION_TIMEOUT=0 # Optional deadline for non-streaming calls (0 disables) **Usage** 1. Start SyntH with the interface enabled (it registers automatically when ``interface/ollama_compat_server.py`` is present). 2. Point an Ollama client at your synth instance: .. code-block:: bash export OLLAMA_HOST=http://:11435 ollama list # returns the synthetic catalogue exposed by SyntH ollama chat SyntH # your client now exchanges messages with synth 3. Any third-party application that supports the Ollama REST API can reuse the same base URL. This makes it simple to integrate synth with dashboards, IDEs, or automation frameworks while the native Ollama engine support is still under development. Because the server streams responses as soon as the persona produces them, end users get the familiar Ollama experience while benefiting from SyntH's plugin ecosystem, persona memory, and dispatcher logic. Interface Registration System ----------------------------- Interfaces are automatically discovered and integrated: 1. **Directory Scanning**: Core scans ``interface/`` for Python modules 2. **Class Discovery**: Files checked for ``INTERFACE_CLASS`` or ``PLUGIN_CLASS`` 3. **Registration**: Interfaces register with the interface registry 4. **Capability Indexing**: Supported actions and features are cataloged 5. **Security Setup**: Trainer IDs configured from environment variables Developing Interfaces --------------------- Creating a new interface requires implementing the interface contract: .. code-block:: python from core.ai_plugin_base import AIPluginBase from core.core_initializer import register_interface from core.interfaces_registry import get_interface_registry class MyInterface(AIPluginBase): @staticmethod def get_interface_id() -> str: """Return unique interface identifier.""" return "myinterface" @staticmethod def get_supported_action_types() -> list[str]: """Return action types this interface supports.""" return ["message"] @staticmethod def get_supported_actions() -> dict: """Return action schemas using the optimized format.""" return { "message_myinterface": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "Message content to send" }, "interface_path": { "type": "string", "description": "Hierarchical interface path (e.g., 'telegram_bot/chat_id/thread_id')" }, "media": { "type": "string", "description": "Optional media attachment URL" } }, "required": ["text", "target"] }, "brief": "Send a message via MyInterface", "examples": { "description": "Send a message through MyInterface with optional media attachment.", "instructions": { "when_to_use": "Use to communicate through MyInterface channels or direct messages.", "common_pitfalls": [ "Ensure target exists and is accessible", "Media URLs must be publicly accessible" ] }, "examples": [ { "scenario": "Send text message", "payload": { "text": "Hello world!", "interface_path": "myinterface/channel1" } }, { "scenario": "Send message with media", "payload": { "text": "Check this out", "interface_path": "myinterface/user123", "media": "https://example.com/image.jpg" } } ] } } } def get_prompt_instructions(self, action_name: str) -> dict: """Provide LLM instructions for interface actions.""" if action_name == "message_myinterface": return { "description": "Send a message through MyInterface.", "payload": { "text": {"type": "string", "description": "Message content"}, "interface_path": {"type": "string", "description": "Hierarchical interface path (e.g., 'myinterface/channel1')"}, "media": {"type": "string", "description": "Optional media URL"} } } return {} def validate_payload(self, action_type: str, payload: dict) -> list[str]: """Validate action payloads.""" errors = [] if action_type == "message_myinterface": if "text" not in payload: errors.append("payload.text is required") if "interface_path" not in payload: errors.append("payload.interface_path is required") return errors async def start(self): """Initialize the interface.""" # Register with core systems register_interface("myinterface", self) core_initializer.register_interface("myinterface") # Start your platform connection here await self.connect_to_platform() async def connect_to_platform(self): """Platform-specific connection logic.""" # Implement platform connection pass async def handle_incoming_message(self, bot, message, prompt): """Handle incoming messages (if this interface also acts as LLM).""" # Optional: if interface can also generate responses pass # Required: Export the interface class INTERFACE_CLASS = MyInterface Interface Actions ----------------- Interfaces can provide actions that LLMs can invoke: **Message Sending:** .. code-block:: json { "type": "message_telegram_bot", "payload": { "text": "Hello from synth!", "interface_path": "telegram_bot/123456789/2" } } **Media Handling:** .. code-block:: json { "type": "send_media_discord", "payload": { "file_url": "https://example.com/image.png", "interface_path": "discord_interface/987654321/123" } } Security and Validation ----------------------- **Trainer ID Validation:** Interfaces validate that sensitive operations come from authorized users: .. code-block:: bash TRAINER_IDS=telegram_bot:123456789,discord_interface:987654321 **Rate Limiting:** Built-in rate limiting prevents abuse: - Per-user rate limits - Burst protection - Platform-specific constraints **Input Validation:** All inputs are validated before processing: - Payload schema validation - Type checking - Content filtering Best Practices -------------- **Action Schema Design** Use the new three-tier action format for optimal prompt efficiency. See :doc:`action_schema_format` for details. **Error Handling** Implement comprehensive error handling with user feedback. **Async Operations** Use async methods for all I/O operations. **Security First** Always validate trainer permissions for sensitive actions. **Platform Limits** Respect platform rate limits and content policies. **Documentation** Provide clear action schemas and examples in the ``examples`` tier. For complete implementations, examine ``interface/telegram_bot.py`` or ``interface/discord_interface.py`` in the repository.