Sinapsis Chatbots Base

Sinapsis templates for chatbot inputs, contextualization, and endpoint-backed completions.

🐍 Installation • 🚀 Features • 📚 Usage example • 📙 Documentation • 🔍 License

The sinapsis-chatbots-base package provides the shared chatbot foundation. It includes the base abstractions for LLM templates together with the core templates for building LLMConversationPacket inputs, adding document context from preloaded data, and sending chat requests to OpenAI-compatible HTTP endpoints.

🐍 Installation

Install using your preferred package manager. We strongly recommend using uv.

Install the base package:

uv pip install sinapsis-chatbots-base --extra-index-url https://pypi.sinapsis.tech

Or with raw pip:

pip install sinapsis-chatbots-base --extra-index-url https://pypi.sinapsis.tech

[!IMPORTANT] EndpointLLMCompletion and EndpointLLMCompletionWithMCP require the optional endpoint extra:

uv pip install sinapsis-chatbots-base[endpoint] --extra-index-url https://pypi.sinapsis.tech

all installs every optional dependency exposed by the package:

uv pip install sinapsis-chatbots-base[all] --extra-index-url https://pypi.sinapsis.tech

🚀 Features

Templates Supported

• LLMConversationInput: Creates an LLMConversationPacket from a prompt, system prompt, and packet metadata.
• QueryContextualizeFromFile: Builds packet contexts from files or documents already loaded into the container.
• EndpointLLMCompletion: Sends chat requests to OpenAI-compatible endpoints such as OpenAI, Ollama, llama.cpp server, vLLM server, or compatible hosted APIs.
• EndpointLLMCompletionWithMCP: Adds MCP tool support on top of EndpointLLMCompletion for OpenAI-compatible endpoints.
• EndpointLLMStreamingCompletion: Streams chat-completion chunks from OpenAI-compatible endpoints and emits partial packet updates.
• EndpointLLMMultiModal: Sends text + image user turns to OpenAI-compatible multimodal endpoints.

[!NOTE] EndpointLLMCompletionWithMCP is currently validated for llama.cpp served Qwen 3.5 models and other OpenAI-compatible endpoints may also work depending on tool-calling behavior.

[!TIP] Use CLI command sinapsis info --all-template-names to show a list with all the available Template names installed with Sinapsis Chatbots Base.

📚 Usage example

The following agent builds an LLMConversationPacket and sends it to an OpenAI-compatible endpoint.

agent:
  name: openai_api_agent

templates:
  - template_name: InputTemplate
    class_name: InputTemplate
    attributes: {}

  - template_name: LLMConversationInput
    class_name: LLMConversationInput
    template_input: InputTemplate
    attributes:
      prompt: Give three short tips for staying organized during a busy week.
      system_prompt: You are a helpful assistant.

  - template_name: EndpointLLMCompletion
    class_name: EndpointLLMCompletion
    template_input: LLMConversationInput
    attributes:
      init_args:
        base_url: "https://api.openai.com/v1"
        llm_model_name: "gpt-4o-mini"
      completion_args:
        max_tokens: 2048

📙 Documentation

Documentation for this and other sinapsis packages is available on the sinapsis website

Tutorials for different projects within sinapsis are available at sinapsis tutorials page

🔍 License

This project is licensed under the AGPLv3 license, which encourages open collaboration and sharing. For more details, please refer to the LICENSE file.

For commercial use, please refer to our official Sinapsis website for information on obtaining a commercial license.