<h1 align="center">
<br>
<a href="https://sinapsis.tech/">
  <img
    src="https://github.com/Sinapsis-AI/brand-resources/blob/main/sinapsis_logo/4x/logo.png?raw=true"
    alt="" width="300">
</a>
<br>
Sinapsis Chat History
<br>
</h1>

<h4 align="center">Sinapsis templates for persistent chat history in chatbot workflows.</h4>

<p align="center">
<a href="#installation">🐍 Installation</a> •
<a href="#features">🚀 Features</a> •
<a href="#example">📚 Usage example</a> •
<a href="#documentation">📙 Documentation</a> •
<a href="#license">🔍 License</a>
</p>

The `sinapsis-chat-history` package provides templates for fetching, trimming, saving, deleting, and resetting persistent chat history associated with `LLMConversationPacket` conversations. It supports SQLite by default, plus optional PostgreSQL-compatible backends such as PostgreSQL and Supabase through the `postgres` extra.

<h2 id="installation">🐍 Installation</h2>

Install using your preferred package manager. We strongly recommend using <code>uv</code>.

Install the base package:

```bash
uv pip install sinapsis-chat-history --extra-index-url https://pypi.sinapsis.tech
```

Or with raw <code>pip</code>:

```bash
pip install sinapsis-chat-history --extra-index-url https://pypi.sinapsis.tech
```

> [!IMPORTANT]
> The base installation includes the `sqlite` provider. PostgreSQL and Supabase require the optional `postgres` extra:
>
> ```bash
> uv pip install sinapsis-chat-history[postgres] --extra-index-url https://pypi.sinapsis.tech
> ```
>
> `all` installs every optional dependency exposed by the package:
>
> ```bash
> uv pip install sinapsis-chat-history[all] --extra-index-url https://pypi.sinapsis.tech
> ```
>
> `ChatHistoryTrim` requires the optional `trim` extra:
>
> ```bash
> uv pip install sinapsis-chat-history[trim] --extra-index-url https://pypi.sinapsis.tech
> ```

<h2 id="features">🚀 Features</h2>

<h3>Templates Supported</h3>

- **ChatHistoryFetch**: Loads stored messages into `LLMConversationPacket.messages`.
- **ChatHistoryTrim**: Trims fetched history to fit a tokenizer-based prompt budget before the LLM call.
- **ChatHistorySave**: Persists packet messages to the configured history backend.
- **ChatHistoryDelete**: Deletes stored messages using explicit user/session scopes.
- **ChatHistoryReset**: Clears the configured history table or storage scope.

<h3>Providers Supported</h3>

- **sqlite**: Default provider for local development and lightweight deployments.
- **postgres**: Shared relational backend for multi-user or concurrent workloads.
- **supabase**: PostgreSQL-compatible backend reachable through the Supabase database connection.

<details>
<summary><strong><span style="font-size: 1.25em;">🧩 Common Attributes</span></strong></summary>

- `provider` (`"sqlite" | "postgres" | "supabase"`, optional): Storage backend to use. Defaults to `sqlite`.
- `db_config` (`dict`, optional): Provider-specific configuration.
  - `sqlite`: use `db_path` and optionally `table`.
  - `postgres` / `supabase`: use `user`, `password`, `host`, `port`, `db_name`, `sslmode`, and optionally `table`.
- `fetch_args.limit` (`int`, optional): Use `-1` to fetch all matching messages.

</details>

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

<h2 id="example">📚 Usage example</h2>

The following agent fetches stored chat history for the given `user_id` and `session_id` into
`LLMConversationPacket.messages`, then trims older turns so the next LLM call stays within a target token budget.

<details id='usage'><summary><strong><span style="font-size: 1.0em;"> Config</span></strong></summary>

```yaml
agent:
  name: chat_history_fetch_messages
  description: Fetches stored chat history into the conversation packet messages.

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

  - template_name: LLMConversationInput
    class_name: LLMConversationInput
    template_input: InputTemplate
    attributes:
      prompt: I'm thinking about taking Barnaby for a run, do you think I'm ready given my training?
      user_id: Sarah
      session_id: conv_1234

  - template_name: ChatHistoryFetch
    class_name: ChatHistoryFetch
    template_input: LLMConversationInput
    attributes:
      provider: sqlite
      db_config:
        db_path: "chat_history.sqlite3"
        table: "chat"
      fetch_args:
        limit: -1
        offset: 0
        order: asc
        order_by: created_at

  - template_name: ChatHistoryTrim
    class_name: ChatHistoryTrim
    template_input: ChatHistoryFetch
    attributes:
      tokenizer_model_name: "Qwen/Qwen3.5-9B"
      model_max_context: 16384
      reserved_output_tokens: 2048
      safety_margin_tokens: 256
      preserve_system_messages: true
```

</details>

<h2 id="documentation">📙 Documentation</h2>

Documentation for this and other sinapsis packages is available on the [sinapsis website](https://docs.sinapsis.tech/docs)

Tutorials for different projects within sinapsis are available at [sinapsis tutorials page](https://docs.sinapsis.tech/tutorials)

<h2 id="license">🔍 License</h2>

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

For commercial use, please refer to our [official Sinapsis website](https://sinapsis.tech) for information on obtaining a commercial license.
