# State Persistence

This document covers saving and restoring agent conversations.

## Overview

Sagents separates **configuration** from **state**:

| Component | Stored In | Contains |
|-----------|-----------|----------|
| Configuration | Code | Model, middleware, tools, prompts |
| State | Database | Messages, todos, metadata |

This separation means:
- You can update middleware without migrating data
- Agent capabilities are version-controlled with code
- Secrets (API keys) stay out of the database

## Data Model

### What Gets Persisted

```elixir
# State structure
%State{
  agent_id: "conversation-123",     # Links to conversation
  messages: [...],                  # Full conversation history
  todos: [...],                     # Current TODO list
  metadata: %{                      # Middleware-specific data
    "conversation_title" => "...",
    "preferences" => %{...}
  },
  interrupt: nil                    # Pending HITL (if any)
}
```

### What Stays in Code

```elixir
# Agent configuration
%Agent{
  model: %ChatAnthropic{...},      # LLM configuration
  middleware: [...],                # Middleware stack
  tools: [...],                     # Additional tools
  base_system_prompt: "...",        # System prompt
  callbacks: %{...}                 # Event callbacks
}
```

## Code Generator

### Basic Usage

```bash
mix sagents.gen.persistence MyApp.Conversations
```

This generates:
- `lib/my_app/conversations.ex` - Context module
- `lib/my_app/conversations/conversation.ex` - Conversation schema
- `lib/my_app/conversations/agent_state.ex` - State schema
- `lib/my_app/conversations/display_message.ex` - UI message schema
- `priv/repo/migrations/..._create_conversations.exs` - Migration

### With Options

```bash
mix sagents.gen.persistence MyApp.Conversations \
  --scope MyApp.Accounts.Scope \
  --owner-type user \
  --owner-field user_id \
  --owner-module MyApp.Accounts.User \
  --table-prefix sagents_
```

Options:
- `--scope` - Application scope module (required)
- `--owner-type` - Owner type (user, account, team, org, none)
- `--owner-field` - Foreign key field name
- `--owner-module` - Owner schema module
- `--table-prefix` - Database table prefix

## Generated Schemas

### Conversation

```elixir
defmodule MyApp.Conversations.Conversation do
  use Ecto.Schema

  schema "sagents_conversations" do
    field :title, :string
    field :scope, :map  # {:user, 123} stored as %{"type" => "user", "id" => 123}

    belongs_to :user, MyApp.Accounts.User

    has_one :agent_state, MyApp.Conversations.AgentState
    has_many :display_messages, MyApp.Conversations.DisplayMessage

    timestamps()
  end
end
```

### AgentState

```elixir
defmodule MyApp.Conversations.AgentState do
  use Ecto.Schema

  schema "sagents_agent_states" do
    field :data, :map  # Serialized State struct

    belongs_to :conversation, MyApp.Conversations.Conversation

    timestamps()
  end
end
```

### DisplayMessage

```elixir
defmodule MyApp.Conversations.DisplayMessage do
  use Ecto.Schema

  schema "sagents_display_messages" do
    field :role, Ecto.Enum, values: [:user, :assistant, :tool, :system]
    field :content, :string
    field :metadata, :map  # Tool calls, token usage, etc.
    field :sequence, :integer  # Ordering

    belongs_to :conversation, MyApp.Conversations.Conversation

    timestamps()
  end
end
```

## Context Module

The generated context provides CRUD operations:

```elixir
defmodule MyApp.Conversations do
  # Conversation CRUD
  def create_conversation(scope, attrs)
  def get_conversation(scope, id)
  def update_conversation(conversation, attrs)
  def delete_conversation(scope, id)
  def list_conversations(scope, opts \\ [])

  # Agent state
  def save_agent_state(conversation_id, state)
  def load_agent_state(conversation_id)

  # Display messages
  def append_display_message(conversation_id, role, content, metadata \\ %{})
  def load_display_messages(conversation_id)
  def clear_display_messages(conversation_id)
end
```

## Usage Patterns

### Creating a Conversation

```elixir
# Get scope from current user
scope = {:user, current_user.id}

# Create conversation
{:ok, conversation} = MyApp.Conversations.create_conversation(scope, %{
  title: "New Chat"
})

# Conversation is now ready for an agent
```

### Starting an Agent with Persistence

```elixir
defmodule MyApp.Agents.Coordinator do
  def start_conversation_session(conversation_id) do
    agent_id = "conversation-#{conversation_id}"

    case AgentServer.whereis(agent_id) do
      nil -> start_new_agent(agent_id, conversation_id)
      pid -> {:ok, %{agent_id: agent_id, pid: pid}}
    end
  end

  defp start_new_agent(agent_id, conversation_id) do
    # Load or create state
    initial_state = case Conversations.load_agent_state(conversation_id) do
      {:ok, state} -> state
      {:error, :not_found} -> State.new!()
    end

    # Create agent from code
    {:ok, agent} = AgentFactory.create_agent(agent_id: agent_id)

    # Start with auto-save
    {:ok, pid} = AgentServer.start_link(
      agent: agent,
      initial_state: initial_state,
      pubsub: {Phoenix.PubSub, MyApp.PubSub},
      auto_save: [
        callback: fn _id, state ->
          Conversations.save_agent_state(conversation_id, state)
        end,
        interval: 30_000,
        on_idle: true
      ],
      conversation_id: conversation_id,
      save_new_message_fn: fn conv_id, message ->
        Conversations.save_message(conv_id, message)
      end
    )

    {:ok, %{agent_id: agent_id, pid: pid}}
  end
end
```

### Auto-Save Configuration

```elixir
AgentServer.start_link(
  agent: agent,
  auto_save: [
    # Function called to save state
    callback: fn agent_id, state ->
      conversation_id = extract_conversation_id(agent_id)
      Conversations.save_agent_state(conversation_id, state)
    end,

    # Save interval (only if changed)
    interval: 30_000,  # 30 seconds

    # Save when execution completes
    on_idle: true,

    # Save before shutdown
    on_shutdown: true  # default: true
  ]
)
```

### Manual Save

```elixir
# Get current state
state = AgentServer.export_state(agent_id)

# Save to database
Conversations.save_agent_state(conversation_id, state)
```

### Loading Conversations

```elixir
# List user's conversations
conversations = Conversations.list_conversations(scope, [
  order_by: [desc: :updated_at],
  limit: 20
])

# Get specific conversation with messages
conversation = Conversations.get_conversation(scope, id)
display_messages = Conversations.load_display_messages(id)
```

## Display Messages

Display messages are a UI-friendly representation of the conversation:

### Why Separate from State?

1. **Performance**: Don't deserialize full state just to show message list
2. **Flexibility**: Format content differently for UI vs LLM
3. **History**: Keep display messages even if the Agent's internal state is summarized

### Saving Display Messages

```elixir
# Configure callback when starting agent
AgentServer.start_link(
  agent: agent,
  conversation_id: conversation_id,
  save_new_message_fn: fn conv_id, message ->
    # This is called for each message (user, assistant, tool)
    # Returns {:ok, [saved_display_messages]} or {:error, reason}
    Conversations.save_message(conv_id, message)
  end
)

# Or save manually based on events
def handle_info({:agent, {:llm_message, message}}, socket) do
  Conversations.append_display_message(
    socket.assigns.conversation_id,
    :assistant,
    message.content,
    %{token_usage: extract_usage(message)}
  )
  {:noreply, socket}
end
```

### Loading for UI

```elixir
def mount(%{"id" => id}, _session, socket) do
  conversation = Conversations.get_conversation(scope, id)
  messages = Conversations.load_display_messages(id)

  {:ok, assign(socket,
    conversation: conversation,
    messages: messages
  )}
end
```

## Serialization

### State Serialization

```elixir
# State.to_serialized/1
%{
  "messages" => [
    %{
      "role" => "user",
      "content" => "Hello",
      "metadata" => %{}
    },
    %{
      "role" => "assistant",
      "content" => "Hi there!",
      "tool_calls" => [],
      "metadata" => %{}
    }
  ],
  "todos" => [
    %{
      "id" => "todo-1",
      "content" => "Task description",
      "status" => "completed"
    }
  ],
  "metadata" => %{
    "conversation_title" => "Greeting",
    "custom_data" => %{...}
  }
}
```

### State Deserialization

```elixir
# State.from_serialized/2
{:ok, state} = State.from_serialized(agent_id, serialized_data)
```

The `agent_id` is required because it's not stored in the serialized data (it's the conversation's identity).

### Custom Serialization

Middleware can define custom serialization:

```elixir
defmodule MyMiddleware do
  @behaviour Sagents.Middleware

  @impl true
  def state_schema do
    [
      my_data: %{
        serialize: fn data -> Base.encode64(:erlang.term_to_binary(data)) end,
        deserialize: fn str -> :erlang.binary_to_term(Base.decode64!(str)) end
      }
    ]
  end
end
```

## Migration Patterns

### Adding New Middleware

When adding middleware to existing agents, the middleware itself should handle missing state gracefully rather than migrating stored agent state. This keeps migration logic colocated with the middleware and avoids touching persisted data:

```elixir
defmodule MyNewMiddleware do
  @behaviour Sagents.Middleware

  @impl true
  def init(config), do: {:ok, config}

  @impl true
  def before_model(state, _config) do
    # Initialize state if this middleware hasn't been used before
    state = case State.get_metadata(state, :my_feature) do
      nil -> State.put_metadata(state, :my_feature, default_value())
      _ -> state
    end

    {:ok, state}
  end

  defp default_value, do: %{initialized: true, data: []}
end
```

This approach is preferred because:
- Migration logic lives with the middleware, not in persistence layer
- No database migrations needed when adding middleware
- Each middleware is responsible for its own defaults
- Existing conversations seamlessly gain new capabilities

### Changing Middleware Configuration

Since middleware config is in code, just update the code:

```elixir
# Before
{FileSystem, [enabled_tools: ["ls", "read_file"]]}

# After - existing states work fine
{FileSystem, [enabled_tools: ["ls", "read_file", "write_file"]]}
```

### Removing Middleware

Orphaned metadata is harmless and can be left in place:

```elixir
# Before
middleware: [TodoList, OldMiddleware, FileSystem]

# After - OldMiddleware's metadata stays in state but is ignored
middleware: [TodoList, FileSystem]
```

The unused metadata has no effect on agent behavior and will naturally disappear as conversations expire or are deleted.

## Scope Pattern

Scopes isolate data between users/organizations:

```elixir
defmodule MyApp.Accounts.Scope do
  defstruct [:type, :id]

  def for_user(user) do
    %__MODULE__{type: :user, id: user.id}
  end

  def for_org(org) do
    %__MODULE__{type: :organization, id: org.id}
  end
end
```

Usage in context:

```elixir
def list_conversations(%Scope{type: :user, id: user_id}, opts) do
  Conversation
  |> where([c], c.user_id == ^user_id)
  |> order_by([c], desc: c.updated_at)
  |> Repo.all()
end

def list_conversations(%Scope{type: :organization, id: org_id}, opts) do
  Conversation
  |> join(:inner, [c], u in User, on: c.user_id == u.id)
  |> where([c, u], u.organization_id == ^org_id)
  |> Repo.all()
end
```

## Best Practices

### 1. Always Use Scopes

```elixir
# Good
Conversations.get_conversation(scope, id)

# Bad - no authorization
Conversations.get_conversation(id)
```

### 2. Save on Completion

```elixir
# Configure auto-save with on_idle
auto_save: [
  callback: &save/2,
  on_idle: true  # Save when agent becomes idle
]
```

### 3. Handle Missing State Gracefully

```elixir
case Conversations.load_agent_state(id) do
  {:ok, state} ->
    # Restore conversation
    state

  {:error, :not_found} ->
    # Fresh state - this is normal for new conversations
    State.new!()

  {:error, :deserialization_failed} ->
    # Data corruption - log and start fresh
    Logger.error("Failed to deserialize state for #{id}")
    State.new!()
end
```

### 4. Keep Display Messages in Sync

```elixir
# In LiveView
def handle_info({:agent, {:llm_message, message}}, socket) do
  # Save to database
  {:ok, display_msg} = Conversations.append_display_message(
    socket.assigns.conversation_id,
    :assistant,
    message.content
  )

  # Update UI
  {:noreply, update(socket, :messages, &(&1 ++ [display_msg]))}
end
```

### 5. Clean Up Old Conversations

```elixir
# Periodic cleanup job
def cleanup_old_conversations do
  cutoff = DateTime.add(DateTime.utc_now(), -30, :day)

  Conversation
  |> where([c], c.updated_at < ^cutoff)
  |> Repo.delete_all()
end
```