Skip to content

Provider Reference

4. Provider Reference

This section details the specific functionalities, configurations, and usage scenarios for each provider integrated into the SLOP Server.

Template Example (template_example)

  • Overview: A minimal example provider demonstrating the basic structure and required methods for integrating a new provider into the SLOP Server.
  • Description:
    • Prerequisites: None. This provider is self-contained and requires no external setup.
    • Authentication: None. The example tool does not interact with any authenticated services.
    • Common Use Cases / Scenarios:
      1. Testing Provider Registration: Verify that the provider is correctly registered and its tool appears in the tool list.
        • Narrative: A developer wants to confirm the basic setup of a new provider.
        • API Call Sequence: 
          GET /tools
          (Verify template_example.example_tool is listed)
      2. Executing the Example Tool: Run the basic tool to see parameter handling and execution flow.
        • Narrative: A developer tests the tool execution mechanism.
        • API Call Sequence: 
          POST /api/tools/template_example.example_tool
{
  "param1": "hello",
  "param2": 123
}
          (Expected Response: {"message":"Executed example tool with param1=hello and param2=123"})
    • Limitations: This is a basic template and does not implement advanced features like webhooks, jobs, storage, or complex configuration.
  • Tools:
    • template_example.example_tool
      • Description: An example tool that demonstrates provider functionality by accepting two parameters and returning a message.
      • Parameters:
        • param1 (string, required): First parameter.
        • param2 (integer, optional): Second parameter.
      • Returns: A map containing a message string.
  • Webhooks: None implemented.
  • Events: None published.
  • Jobs: None registered.
  • Configuration: None required.
  • Notes: This provider serves as the primary starting point and reference for creating new providers. Refer to the pkg/providers/template_example/adapter.go file and the Provider Development Guide for implementation details.

Filesystem (filesystem)

  • Overview: Provides tools for interacting with the local filesystem within the SLOP server's execution environment.
  • Description:
    • Prerequisites: Access permissions for the ubuntu user within the sandbox environment to read/write/list files in the target directories.
    • Authentication: None. Operations are performed with the privileges of the SLOP server process.
    • Common Use Cases / Scenarios:
      1. Writing Text to a File: Save generated text or data to a file.
        • Narrative: An LLM generates a report, and the user wants to save it.
        • API Call Sequence: 
          POST /api/tools/filesystem.write_file
{
  "path": "/home/ubuntu/report.txt",
  "content": "This is the generated report content...",
  "append": false
}
      2. Reading File Content: Retrieve the content of an existing file.
        • Narrative: A user wants to load instructions or data from a file.
        • API Call Sequence: 
          POST /api/tools/filesystem.read_file
{
  "path": "/home/ubuntu/instructions.txt"
}
      3. Listing Directory Contents: See the files and subdirectories within a specific path.
        • Narrative: A developer wants to check the contents of a working directory.
        • API Call Sequence: 
          POST /api/tools/filesystem.list_directory
{
  "path": "/home/ubuntu/data/"
}
    • Limitations: Operations are confined to the sandbox environment where the SLOP server runs. Path traversal vulnerabilities should be considered; the implementation includes security checks (isSecurePath) to prevent access outside designated base directories (typically /home/ubuntu/ and /tmp/). File size limits for reading/writing might apply depending on server configuration or system resources.
  • Tools:
    • filesystem.read_file
      • Description: Reads the content of a specified file.
      • Parameters:
        • path (string, required): Absolute path to the file.
      • Returns: File content as a string.
    • filesystem.write_file
      • Description: Writes or appends content to a specified file. Creates the file and any necessary parent directories if they don't exist.
      • Parameters:
        • path (string, required): Absolute path to the file.
        • content (string, required): The text content to write.
        • append (boolean, optional, default: false): If true, appends content to the file; otherwise, overwrites it.
      • Returns: Success message or error.
    • filesystem.list_directory
      • Description: Lists files and subdirectories within a specified directory path.
      • Parameters:
        • path (string, required): Absolute path to the directory.
      • Returns: A list of file/directory names or detailed information (check implementation in pkg/providers/filesystem/operations.go).
  • Webhooks: None implemented.
  • Events: None published.
  • Jobs: None registered.
  • Configuration: None required.
  • Notes: Path security is enforced. Ensure the server process has the necessary filesystem permissions.

LLM (llm)

  • Overview: Acts as an interface to Large Language Model services, primarily focusing on OpenAI's API for chat completions and potentially function/tool calling.
  • Description:
    • Prerequisites: An active account and API key from the configured LLM provider (e.g., OpenAI).
    • Authentication: Requires an API key from the LLM provider (e.g., OpenAI API Key). This key must be configured in the SLOP server's environment.
    • Common Use Cases / Scenarios:
      1. Chat Completion: Send a sequence of messages (system, user, assistant) to the LLM and receive a response.
        • Narrative: A user interacts with a chatbot powered by the LLM.
        • API Call Sequence (Conceptual - assumes a generic chat tool, might map to /api/chat endpoint directly rather than a specific provider tool): 
          POST /api/chat
{
  "thread_id": "optional_thread_id",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is the capital of France?"}
  ],
  "model": "gpt-4o" // Or configured default
}
      2. Tool Invocation by LLM: The LLM determines that a function/tool (exposed by other SLOP providers) needs to be called to fulfill a user request.
        • Narrative: User asks "What's the weather in London?", the LLM decides to call a weather tool.
        • API Call Sequence (Handled internally by the /api/chat endpoint logic):
          1. User sends message via POST /api/chat.
          2. SLOP Server sends messages + available tool definitions to LLM provider.
          3. LLM provider responds indicating a tool call is needed (e.g., weather.get_weather with arguments {"location": "London"}).
          4. SLOP Server executes the tool (POST /api/tools/weather.get_weather).
          5. SLOP Server sends tool result back to LLM provider.
          6. LLM provider generates final response based on tool result.
          7. SLOP Server returns final response to user.
    • Limitations: Dependent on the capabilities, rate limits, and costs associated with the configured LLM provider (e.g., OpenAI). Performance depends on the LLM's response time. Specific model features (e.g., context window size, tool calling support) vary.
  • Tools: While the core LLM interaction might be handled by the central /api/chat endpoint, the llm provider itself (specifically pkg/providers/llm/openai/openai.go) likely implements the underlying logic called by that endpoint. It might not register distinct tools under the llm. prefix in the same way other providers do. The primary interaction is often abstracted via the /api/chat endpoint.
  • Webhooks: None implemented.
  • Events: None published directly by this provider (though chat interactions might trigger events elsewhere).
  • Jobs: None registered.
  • Configuration:
    • OPENAI_API_KEY (Required): Your API key for the OpenAI service.
    • OPENAI_MODEL (Optional): Default model to use (e.g., gpt-4o, gpt-3.5-turbo).
    • OPENAI_BASE_URL (Optional): For using proxy servers or alternative OpenAI-compatible APIs.
  • Notes: This provider is central to the SLOP server's conversational AI capabilities. Ensure the API key is kept secure and monitor usage costs.

Unipile (unipile)

  • Overview: Integrates with the Unipile unified API, providing tools and handling webhooks to interact with various communication channels (Email, Messaging, etc.) linked by users.
  • Description:
    • Prerequisites: A Unipile developer account and API key. A configured PostgreSQL database accessible by the SLOP server for storing account information and tokens (pg_store.go). Network connectivity from the SLOP server to the Unipile API endpoint.
    • Authentication: Requires a global Unipile API Key set via the UNIPILE_API_KEY environment variable for the provider to authenticate with the Unipile API itself. Individual user accounts (e.g., Gmail, Outlook) are connected to Unipile through an OAuth-like flow, likely initiated via a specific tool or the Unipile platform. The provider securely stores and manages user-specific account credentials/tokens in its PostgreSQL store (pg_store.go).
    • Common Use Cases / Scenarios:
      1. Listing Connected Accounts: Retrieve the list of communication accounts (e.g., Gmail, Outlook) the user has connected via Unipile.
        • Narrative: A user wants to see which email accounts are currently linked and active.
        • API Call Sequence: 
          POST /api/tools/unipile.list_accounts
{
  "user_id": "user-xyz" // Assuming user context is passed or inferred
}
      2. Receiving a New Email via Webhook: Unipile notifies SLOP about a new email in a connected account.
        • Narrative: An email arrives in a user's linked Gmail account.
        • Flow: External Email -> Unipile Service -> Unipile sends POST /webhooks/unipile/{webhook_id} to SLOP -> unipile provider's webhook handler (email_webhook_handler.go) parses payload -> Stores raw payload as a resource -> Publishes internal event unipile.email.received with relevant IDs (account, email, resource).
      3. Fetching Specific Email Content: Retrieve the details of a specific email message.
        • Narrative: A downstream job (like email_draft_preparator) needs the full content of an email identified by an event.
        • API Call Sequence: 
          POST /api/tools/unipile.get_email
{
  "account_id": "acc_12345", // ID of the connected Unipile account
  "email_id": "email_abcde" // ID of the specific email
}
    • Limitations: Functionality is dependent on the features, supported integrations, and rate limits of the Unipile API. Data synchronization might have delays. Specific error handling for disconnected accounts or API issues is crucial.
  • Tools: (Based on structure and common needs)
    • unipile.list_accounts
      • Description: Lists the communication accounts connected by the user via Unipile.
      • Parameters: (Potentially user_id or inferred from auth context).
      • Returns: List of account objects (ID, type, status, etc.).
    • unipile.get_email
      • Description: Retrieves the details of a specific email message.
      • Parameters:
        • account_id (string, required): The ID of the relevant connected account.
        • email_id (string, required): The ID of the email to fetch.
      • Returns: Email object containing headers, body, attachments, etc. (e.g., unipile/models.Email).
    • unipile.get_account_status
      • Description: Checks the synchronization status or connectivity of a specific connected account.
      • Parameters: account_id (string, required).
      • Returns: Account status information.
    • unipile.register_webhook (Likely internal or setup tool)
      • Description: Registers SLOP webhook endpoints with the Unipile service for a specific account or globally.
      • Parameters: (Varies, might include account_id, callback URL details).
      • Returns: Success/failure status.
    • (Potential) unipile.initiate_account_connection
      • Description: Starts the process for a user to connect a new communication account (e.g., redirects user to Unipile OAuth flow).
      • Parameters: (Potentially user_id, account_type).
      • Returns: Redirection URL or status.
  • Webhooks (Incoming):
    • Handles various webhooks from Unipile, registered via webhook_registration.go.
    • Examples: Email events (email_webhook_handler.go), Job/Sync events (jobs_webhook.go), Account connection events.
    • Handlers typically parse the payload, store relevant data (often as resources), and publish internal events or schedule jobs.
  • Events (Published):
    • unipile.email.received: When a new email webhook is processed.
    • unipile.account.sync_status.updated: When the sync status of a connected account changes.
    • unipile.account.disconnected: When a connected account becomes disconnected.
    • unipile.email.thread.created: (As mentioned in chaining doc) Potentially published after processing/grouping emails into threads.
  • Jobs:
    • Account Synchronization (sync_job.go): Periodically or trigger-based job to synchronize data for connected accounts.
  • Configuration:
    • UNIPILE_API_KEY (string, required): API key for authenticating with the Unipile service.
    • UNIPILE_API_ENDPOINT (string, optional): Base URL for the Unipile API (defaults if not set).
    • Database connection details are handled globally by the SLOP server.
  • Notes: This provider is essential for integrating real-time communication data. It manages complex state related to user account connections and synchronization. It serves as a key upstream component in processing chains like the one involving email_draft_preparator. Uses PostgreSQL (pg_store.go) extensively for persistence.

Email Draft Preparator (email_draft_preparator)

  • Overview: Processes email data, often received from the unipile provider, transforming it into a structured format (like XML) suitable for further processing or presentation.
  • Description:
    • Prerequisites: Requires the unipile provider to be active and configured for fetching email content. An event trigger mechanism (or a direct job scheduling mechanism) must be set up to initiate processing based on unipile.email.received events or similar triggers. Requires access to the SLOP server's Job Manager and potentially the Resource Manager and Pub/Sub system.
    • Authentication: None directly. It operates on data sourced internally, typically triggered by events from authenticated unipile sessions. It does not directly interact with external services requiring its own authentication.
    • Common Use Cases / Scenarios:
      1. Processing a New Email from Unipile: Automatically process an email received via Unipile into a structured format.
        • Narrative: An email arrives via Unipile, and the system needs to prepare a structured summary (e.g., XML) for an LLM or another process.
        • Flow: unipile.email.received event published -> Event Trigger schedules email_draft_preparator.process_email job -> Job executes -> Job calls unipile.get_email tool -> Job processes content (using processor.go, mailer/ helpers) -> Job stores result (e.g., as resource) -> Job publishes email.draft.prepared event.
      2. Manually Triggering Processing (Less Common): If an email ID is known, processing could potentially be triggered manually via an API call that schedules the job.
        • Narrative: A developer needs to re-process a specific email.
        • API Call Sequence (Conceptual - assumes manual job creation): 
          POST /api/jobs
{
  "process_id": "email_draft_preparator.process_email",
  "name": "Manual Reprocess Email email_abcde",
  "params": {
    "account_id": "acc_12345",
    "email_id": "email_abcde"
  }
}
    • Limitations: Primarily designed to process emails fetched via unipile. The quality of the output depends heavily on the structure and content of the input email and the robustness of the parsing logic (mailer/ package). May not handle all email formats or edge cases perfectly. Performance depends on the complexity of email processing and the time taken by the unipile.get_email tool.
  • Tools: Does not typically expose direct tools for external use. Its primary function is executed via background jobs triggered by events.
  • Webhooks (Incoming): While it doesn't receive webhooks directly from external services, it acts as a consumer in the provider chain, effectively processing data originating from unipile's webhook handlers via internal events and jobs.
  • Events (Published):
    • email.draft.prepared: Published after successfully processing an email and potentially storing the structured result (e.g., as an XML resource). The payload typically includes references like the original email ID, account ID, and the ID of the resource containing the processed output.
  • Jobs:
    • email_draft_preparator.process_email
      • Description: The core job that fetches email content (using unipile.get_email), processes it (parsing, cleaning, potentially using helpers in mailer/ like Boomerang detection, text extraction), transforms it into the target format (e.g., XML via mailer/xmlgen.go), stores the result, and publishes the email.draft.prepared event.
      • Trigger: Typically triggered by an Event Trigger listening for unipile.email.received.
      • Parameters: Expects account_id and email_id.
  • Configuration: Generally requires no specific configuration beyond the standard SLOP server setup (database access, job manager, pub/sub).
  • Notes: This provider is a prime example of a downstream processor in a Provider Chaining scenario. Its mailer/ sub-package contains significant logic for cleaning, parsing, and formatting email content.