Metadata-Version: 2.4
Name: 3tears-conversations
Version: 0.14.0
Summary: Conversation entity, three-tier collection, and per-agent schema migrations shared by memory and tool packages
Project-URL: Repository, https://github.com/pacepace/3tears
Author: pace
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.14
Requires-Dist: 3tears
Requires-Dist: 3tears-agent-acl
Requires-Dist: 3tears-langgraph
Requires-Dist: 3tears-observe
Description-Content-Type: text/markdown

# 3tears-conversations

Canonical owner of the per-agent `conversations` table plus its entity and three-tier collection.

## Purpose

Tracks one row per user-facing conversation an agent is engaged in: ownership scope (`agent_id`, `customer_id`, `user_id`), external reference (`channel_type`, `conversation_ref`), lifecycle (`status`, `summary`), timestamps (`date_created`, `date_updated`, `date_last_message`).

This table is owned here because multiple packages key off `conversation_id` (memory, agent-tools context items, workspace bindings) and no single consumer is the natural owner of the shape. Owning the table here lets each downstream package depend on `conversations` without pulling in memory's extraction pipeline.

## Public API

Exports (see `src/threetears/conversations/__init__.py`):

- `Conversation` -- `BaseEntity` subclass for a single row.
- `ConversationsCollection` -- three-tier (`L1` SQLite / `L2` NATS KV / `L3` postgres) collection with the usual `get` / `save` / `subscript` semantics.
- `register(runner)` -- agent-scope migration entry point. Contributes the `conversations` table creation to a canonical `threetears.core.data.migrations.MigrationRunner`. No `depends_on` edges; this is the root of the agent-schema dependency graph, so memory / workspace / tools migrations that reference `conversations.id` sort after it.

## Minimal usage

```python
from threetears.conversations import Conversation, ConversationsCollection, register
from threetears.core.data.migrations import MigrationRunner

# 1. register the package's migrations on the runner
runner = MigrationRunner(store)
register(runner)
await store.run_migrations(runner)

# 2. use the collection like any other 3tears collection
collection = ConversationsCollection(registry=registry)
conv = await collection.get(conversation_id)
conv.summary = "follow-up on last week's analysis"
await conv.save()
```

## Reference

- Downstream consumers: `threetears.agent.memory`, `threetears.agent.tools` (context items), `threetears.agent.workspace` (bindings)
