"""
AIEL Memory SDK Guidance
=======================

Use this module to persist and retrieve:
- conversation context (messages)
- working/runtime state (structured JSON)
- checkpoints (resumable snapshots)
- long-term recall (namespaced key/value memory)

What to use
-----------
- InMemorySaver
    Local/dev usage (process memory only, non-persistent).

- RemoteSaver
    Production usage backed by the AIEL Memory API.

- ThreadMessage, Thread, ThreadState, Checkpoint, RecallItem, RecallQuery
    Stable data types returned by saver methods.

Core concepts
-------------
- thread_key
    Your stable external handle for a conversation/session.
    Keep it deterministic (example: "user:42/session:abc").

- thread_id
    Backend-derived internal ID returned by API reads/writes.

- state
    Structured JSON-like object for workflow/runtime state.

- checkpoint
    Resumable snapshot of state + metadata.

- recall
    Long-term key/value memory grouped by namespace.

Quick start (RemoteSaver)
-------------------------
Example usage with the remote Memory API.

    from aiel_sdk import AielClient
    from aiel_sdk.memory import RemoteSaver, ThreadMessage, RecallQuery

    client = AielClient(base_url="https://api.example.com", api_key="TOKEN")
    saver = RemoteSaver(client, workspace_id="ws_123", project_id="proj_456")

    # 1) Write short-term memory (messages)
    saver.thread_write(
        thread_key="user:42/session:abc",
        messages=[ThreadMessage(role="human", content="Hello!")],
        ttl_seconds=3600,
    )

    # 2) Read short-term memory (messages)
    thread = saver.thread_read(thread_key="user:42/session:abc", limit=50)

    # 3) Patch/read structured state
    saver.state_patch(thread_key="user:42/session:abc", patch={"step": "triage"})
    state = saver.state_read(thread_key="user:42/session:abc")

    # 4) Checkpoint state for recovery
    cp = saver.checkpoint_write(
        thread_key="user:42/session:abc",
        state=state.state,
        metadata={"source": "agent"},
    )

    # 5) Long-term recall
    saver.recall_put(
        namespace=["users", "42"],  # must be list[str], not plain str
        key="preferences",
        value={"tone": "concise"},
        tags={"app": "support"},
    )
    item = saver.recall_get(namespace=["users", "42"], key="preferences")
    items = saver.recall_search(query=RecallQuery(namespace=["users", "42"], limit=20))

Input rules (important)
----------------------
- thread_key
    - required
    - non-empty
    - trimmed
    - max length: 512 chars

- ThreadMessage.content
    - required
    - non-empty
    - max length: 20,000 chars

- ttl_seconds (when provided)
    - range: 60 to 31,536,000

- namespace (for recall)
    - must be list[str]
    - example: ["tenant", "user_id"]

Recommended patterns
--------------------
- Build deterministic thread_key values from business identifiers.
- Use state_patch for mutable workflow state and checkpoint_write at key milestones.
- Keep recall keys domain-specific (examples: "preferences", "profile:v2").
- Always pass a bounded limit on reads/searches to control payload size.
- Use InMemorySaver in tests and RemoteSaver in staging/production.

Errors and reliability
----------------------
- Validation errors raise ValueError locally for malformed inputs.
- Remote API/network failures surface as SDK API errors.
- For production observability, ensure request correlation is enabled in your client stack.
"""

from .thread_key import normalize_thread_key
from .types import (
    Role,
    ThreadScope,
    ThreadMessage,
    Thread,
    ThreadState,
    ThreadStateIn,
    Checkpoint,
    RecallItem,
    RecallResult,
    RecallPutResult,
    RecallQuery,
    SaverCapability,
    SaverCapabilities,
    DEFAULT_CAPABILITIES,
)
from .saver import Saver
from .in_memory import InMemorySaver
from .remote import RemoteSaver

__all__ = [
    "normalize_thread_key",
    "Role",
    "ThreadScope",
    "ThreadMessage",
    "Thread",
    "ThreadState",
    "ThreadStateIn",
    "Checkpoint",
    "RecallItem",
    "RecallResult",
    "RecallPutResult",
    "RecallQuery",
    "SaverCapability",
    "SaverCapabilities",
    "DEFAULT_CAPABILITIES",
    "Saver",
    "InMemorySaver",
    "RemoteSaver",
]