neobot-storage 1.0.0__tar.gz

neobot_storage-1.0.0/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.3
+Name: neobot-storage
+Version: 1.0.0
+Summary: Storage layer for NeoBot — SQLAlchemy + Alembic
+Author: wsrsq, tangtian
+Author-email: wsrsq <wsrsq001@163.com>, tangtian <a14b@126.com>
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: alembic>=1.15.0
+Requires-Dist: neobot-contracts
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# neobot-storage
+
+SQLAlchemy 2.0 async storage layer for NeoBot. Implements the repository and unit-of-work ports defined in `neobot-contracts`.
+
+## Usage
+
+```python
+from neobot_storage import create_engine, make_uow_factory
+
+engine = create_engine("sqlite+aiosqlite:///neobot.db")
+uow_factory = make_uow_factory(engine)
+
+async with uow_factory() as uow:
+    await uow.messages.save_message(msg)
+    await uow.commit()
+```
+
+## Migrations
+
+Migrations are run automatically on app startup via `run_migrations(db_url)` (absolute path
+is injected, so no database file is created inside the source tree).
+
+To run the Alembic CLI manually, always pass an **absolute** database path:
+
+```bash
+cd packages/storage/src/neobot_storage
+alembic -x db_url=sqlite+aiosqlite:////absolute/path/to/neobot.db upgrade head
+```
+
+`alembic.ini` intentionally leaves `sqlalchemy.url` empty; a relative URL there would create a
+stray empty `neobot.db` in the working directory (which must never be committed).

neobot_storage-1.0.0/README.md

@@ -0,0 +1,31 @@
+# neobot-storage
+
+SQLAlchemy 2.0 async storage layer for NeoBot. Implements the repository and unit-of-work ports defined in `neobot-contracts`.
+
+## Usage
+
+```python
+from neobot_storage import create_engine, make_uow_factory
+
+engine = create_engine("sqlite+aiosqlite:///neobot.db")
+uow_factory = make_uow_factory(engine)
+
+async with uow_factory() as uow:
+    await uow.messages.save_message(msg)
+    await uow.commit()
+```
+
+## Migrations
+
+Migrations are run automatically on app startup via `run_migrations(db_url)` (absolute path
+is injected, so no database file is created inside the source tree).
+
+To run the Alembic CLI manually, always pass an **absolute** database path:
+
+```bash
+cd packages/storage/src/neobot_storage
+alembic -x db_url=sqlite+aiosqlite:////absolute/path/to/neobot.db upgrade head
+```
+
+`alembic.ini` intentionally leaves `sqlalchemy.url` empty; a relative URL there would create a
+stray empty `neobot.db` in the working directory (which must never be committed).

neobot_storage-1.0.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "neobot-storage"
+version = "1.0.0"
+description = "Storage layer for NeoBot — SQLAlchemy + Alembic"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "sqlalchemy[asyncio]>=2.0",
+    "aiosqlite>=0.20.0",
+    "alembic>=1.15.0",
+    "neobot-contracts",
+]
+
+[[project.authors]]
+name = "wsrsq"
+email = "wsrsq001@163.com"
+
+[[project.authors]]
+name = "tangtian"
+email = "a14b@126.com"
+
+[tool.uv.sources.neobot-contracts]
+workspace = true
+
+[build-system]
+requires = ["uv_build>=0.9.27,<0.10.0"]
+build-backend = "uv_build"

neobot_storage-1.0.0/pyproject.toml.orig

@@ -0,0 +1,23 @@
+[project]
+name = "neobot-storage"
+version = "1.0.0"
+description = "Storage layer for NeoBot — SQLAlchemy + Alembic"
+readme = "README.md"
+authors = [
+    { name = "wsrsq", email = "wsrsq001@163.com" },
+    { name = "tangtian", email = "a14b@126.com" },
+]
+requires-python = ">=3.13"
+dependencies = [
+    "sqlalchemy[asyncio]>=2.0",
+    "aiosqlite>=0.20.0",
+    "alembic>=1.15.0",
+    "neobot-contracts",
+]
+
+[tool.uv.sources]
+neobot-contracts = { workspace = true }
+
+[build-system]
+requires = ["uv_build>=0.9.27,<0.10.0"]
+build-backend = "uv_build"

neobot_storage-1.0.0/src/neobot_storage/__init__.py

@@ -0,0 +1,18 @@
+"""neobot_storage 公共 API。"""
+
+from neobot_storage.backup import backup_sqlite_database
+from neobot_storage.engine import create_engine, run_migrations, sqlite_url
+from neobot_storage.models import Base, MaintenanceRunRecord, ModelUsageRecord
+from neobot_storage.uow import SqlAlchemyUnitOfWork, make_uow_factory
+
+__all__ = [
+    "create_engine",
+    "run_migrations",
+    "sqlite_url",
+    "backup_sqlite_database",
+    "Base",
+    "MaintenanceRunRecord",
+    "ModelUsageRecord",
+    "SqlAlchemyUnitOfWork",
+    "make_uow_factory",
+]

neobot_storage-1.0.0/src/neobot_storage/_retry.py

@@ -0,0 +1,90 @@
+"""针对 SQLite 瞬时锁错误的重试辅助工具。"""
+
+from __future__ import annotations
+
+import asyncio
+import random
+from typing import Awaitable, Callable, Iterator, TypeVar
+
+T = TypeVar("T")
+
+# SQLite returns this error code / message when it cannot acquire a write lock
+_LOCKED_MESSAGES = (
+    "database is locked",
+    "database table is locked",
+    "locking protocol",
+    "deadlock",
+)
+
+
+def _iter_exception_chain(exc: BaseException) -> Iterator[BaseException]:
+    """按顺序产出 *exc* 及其 ``__cause__``/``__context__`` 异常链，循环安全。"""
+    seen: set[int] = set()
+    link: BaseException | None = exc
+    while link is not None and id(link) not in seen:
+        seen.add(id(link))
+        yield link
+        link = link.__cause__ or link.__context__
+
+
+def _is_locked_error(exc: Exception) -> bool:
+    # PendingRollbackError 的 message 内嵌原始 flush 异常
+    # （"Original exception was: ... database is locked"），
+    # 沿 __cause__/__context__ 链匹配可覆盖该场景，且不会对
+    # 普通含 "rolled back" 字样的错误过度匹配。
+    for link in _iter_exception_chain(exc):
+        msg = str(link).casefold()
+        if any(pattern in msg for pattern in _LOCKED_MESSAGES):
+            return True
+    return False
+
+
+async def retry_on_lock(
+    coro_factory: Callable[[], Awaitable[T]],
+    *,
+    max_retries: int = 3,
+    base_delay: float = 0.1,
+    max_delay: float = 2.0,
+    on_retry: Callable[[], Awaitable[None]] | None = None,
+) -> T:
+    """执行 *coro_factory*，当 SQLite 报告数据库被锁定时，
+    按指数退避 + 随机抖动重试。
+
+    Parameters
+    ----------
+    coro_factory : callable returning awaitable
+        每次调用都返回新协程的工厂函数（以便重试）。
+    max_retries : int
+        重试次数上限，超过后抛出最后一次异常。
+    base_delay : float
+        初始延迟（秒），每次重试翻倍。
+    max_delay : float
+        延迟上限。
+    on_retry : optional callable returning awaitable
+        每次重试尝试前（退避延迟之后）调用。失败的 flush
+        会让 SQLAlchemy 会话处于已回滚状态，可传入类似
+        ``session.rollback`` 的调用以恢复会话；重试的事务体
+        将在全新事务上重新执行。
+
+    Raises
+    ------
+    重试全部耗尽时抛出最后遇到的异常。
+    """
+    last_exc: Exception | None = None
+    for attempt in range(max_retries + 1):
+        try:
+            return await coro_factory()
+        except Exception as exc:
+            last_exc = exc
+            if not _is_locked_error(exc):
+                raise
+            if attempt >= max_retries:
+                break
+            delay = min(base_delay * (2**attempt), max_delay)
+            jitter = random.uniform(0, delay * 0.25)
+            await asyncio.sleep(delay + jitter)
+            if on_retry is not None:
+                await on_retry()
+
+    # All retries exhausted
+    raise last_exc  # type: ignore[misc]

neobot_storage-1.0.0/src/neobot_storage/alembic/env.py

@@ -0,0 +1,72 @@
+"""面向异步 SQLAlchemy 的 Alembic 环境。"""
+
+from __future__ import annotations
+
+import asyncio
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from neobot_storage.models import Base
+
+config = context.config
+if config.config_file_name:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def _resolve_database_url() -> str:
+    """解析数据库 URL：优先 ini（由 run_migrations 注入），其次命令行 -x db_url=...。
+
+    不回退到相对路径，避免 alembic CLI 在源码目录生成 neobot.db 这类构建产物。
+    """
+    url = config.get_main_option("sqlalchemy.url") or ""
+    if not url:
+        url = context.get_x_argument(as_dictionary=True).get("db_url", "")
+    if not url:
+        raise RuntimeError(
+            "未配置数据库 URL：应用启动时由 run_migrations(db_url) 注入；"
+            "命令行请使用 alembic -x db_url=sqlite+aiosqlite:///<绝对路径>/neobot.db upgrade head"
+        )
+    return url
+
+
+def run_migrations_offline() -> None:
+    context.configure(
+        url=_resolve_database_url(),
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_migrations_online() -> None:
+    engine = create_async_engine(_resolve_database_url())
+    async with engine.connect() as conn:
+        await conn.run_sync(
+            lambda sync_conn: context.configure(
+                connection=sync_conn,
+                target_metadata=target_metadata,
+            )
+        )
+        async with conn.begin():
+            await conn.run_sync(lambda _: context.run_migrations())
+    await engine.dispose()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    try:
+        asyncio.get_running_loop()
+        # 已在 event loop 中（如 app 启动时调用），用新线程跑
+        import concurrent.futures
+        with concurrent.futures.ThreadPoolExecutor() as pool:
+            pool.submit(asyncio.run, run_migrations_online()).result()
+    except RuntimeError:
+        # 没有 event loop（CLI 直接调用）
+        asyncio.run(run_migrations_online())

neobot_storage-1.0.0/src/neobot_storage/alembic/script.py.mako

@@ -0,0 +1,27 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

neobot_storage-1.0.0/src/neobot_storage/alembic/versions/0001_initial_schema.py

@@ -0,0 +1,81 @@
+"""初始表结构
+
+Revision ID: 0001
+Revises:
+Create Date: 2026-03-21 00:00:00.000000
+
+"""
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = "0001"
+down_revision: Union[str, None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "USER_DATA",
+        sa.Column("user_id", sa.String(), primary_key=True),
+        sa.Column("nick_name", sa.Text()),
+        sa.Column("relation_ship", sa.Text()),
+        sa.Column("profile", sa.Text()),
+        sa.Column("birthday", sa.Text()),
+        sa.Column("sex", sa.Text()),
+        sa.Column("city", sa.Text()),
+        sa.Column("country", sa.Text()),
+        sa.Column("labs", sa.Text()),
+        sa.Column("remark", sa.Text()),
+        sa.Column("age", sa.Integer()),
+        sa.Column("long_nick", sa.Text()),
+    )
+
+    op.create_table(
+        "GROUP_DATA",
+        sa.Column("group_id", sa.String(), primary_key=True),
+        sa.Column("group_name", sa.Text()),
+        sa.Column("profile", sa.Text()),
+        sa.Column("is_quite", sa.Boolean(), server_default=sa.false()),
+    )
+
+    op.create_table(
+        "EVENT_DATA",
+        sa.Column("event_id", sa.String(), primary_key=True),
+        sa.Column("event_message", sa.Text()),
+        sa.Column("embedded_data", sa.Text()),
+    )
+
+    op.create_table(
+        "messages",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
+        sa.Column("event_id", sa.String(), nullable=False, unique=True),
+        sa.Column("conversation_kind", sa.String(), nullable=False),
+        sa.Column("conversation_id", sa.String(), nullable=False),
+        sa.Column("sender_id", sa.String(), nullable=False),
+        sa.Column("sender_name", sa.Text(), nullable=False),
+        sa.Column("text", sa.Text(), nullable=False),
+        sa.Column("occurred_at", sa.DateTime(), nullable=False),
+    )
+
+    op.create_table(
+        "memories",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
+        sa.Column("conversation_kind", sa.String(), nullable=False),
+        sa.Column("conversation_id", sa.String(), nullable=False),
+        sa.Column("speaker_id", sa.String(), nullable=False),
+        sa.Column("content", sa.Text(), nullable=False),
+        sa.Column("created_at", sa.DateTime(), nullable=False),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("memories")
+    op.drop_table("messages")
+    op.drop_table("EVENT_DATA")
+    op.drop_table("GROUP_DATA")
+    op.drop_table("USER_DATA")

neobot_storage-1.0.0/src/neobot_storage/alembic/versions/0002_lowercase_table_names.py

@@ -0,0 +1,38 @@
+"""表名转小写
+
+Revision ID: 0002
+Revises: 0001
+Create Date: 2026-03-21 00:00:00.000000
+
+"""
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+from alembic import op
+
+revision: str = "0002"
+down_revision: Union[str, None] = "0001"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # SQLite treats table names as case-insensitive, so we need a two-step rename
+    for old, tmp, new in [
+        ("USER_DATA", "_tmp_user_data", "user_data"),
+        ("GROUP_DATA", "_tmp_group_data", "group_data"),
+        ("EVENT_DATA", "_tmp_event_data", "event_data"),
+    ]:
+        op.rename_table(old, tmp)
+        op.rename_table(tmp, new)
+
+
+def downgrade() -> None:
+    for old, tmp, new in [
+        ("user_data", "_tmp_user_data", "USER_DATA"),
+        ("group_data", "_tmp_group_data", "GROUP_DATA"),
+        ("event_data", "_tmp_event_data", "EVENT_DATA"),
+    ]:
+        op.rename_table(old, tmp)
+        op.rename_table(tmp, new)

neobot_storage-1.0.0/src/neobot_storage/alembic/versions/0003_add_archive_memories.py

@@ -0,0 +1,43 @@
+"""新增 archive_memories 表
+
+Revision ID: 0003
+Revises: 0002
+Create Date: 2026-03-22 00:00:00.000000
+
+"""
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = "0003"
+down_revision: Union[str, None] = "0002"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "archive_memories",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
+        sa.Column("table_name", sa.String(), nullable=False),
+        sa.Column("key", sa.String(), nullable=False),
+        sa.Column("value", sa.Text(), nullable=False),
+        sa.Column("tags", sa.Text()),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("version", sa.Integer(), nullable=False, server_default="1"),
+        sa.UniqueConstraint("table_name", "key", name="uq_archive_memories_table_key"),
+    )
+    
+    # 创建索引和唯一约束
+    op.create_index(
+        "ix_archive_memories_table_name_updated_at",
+        "archive_memories",
+        ["table_name", "updated_at"],
+    )
+def downgrade() -> None:
+    op.drop_index("ix_archive_memories_table_name_updated_at", "archive_memories")
+    op.drop_table("archive_memories")

neobot_storage-1.0.0/src/neobot_storage/alembic/versions/0004_add_images_table.py

@@ -0,0 +1,47 @@
+"""新增 images 表
+
+Revision ID: 0004
+Revises: 0003
+Create Date: 2026-04-09
+"""
+
+from __future__ import annotations
+
+from typing import Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision: str = "0004"
+down_revision: Union[str, None] = "0003"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "images",
+        sa.Column("id", sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column("file_hash", sa.String(), nullable=False),
+        sa.Column("source", sa.Text(), nullable=True),
+        sa.Column("mime_type", sa.String(), nullable=True),
+        sa.Column("original_width", sa.Integer(), nullable=True),
+        sa.Column("original_height", sa.Integer(), nullable=True),
+        sa.Column("processed_width", sa.Integer(), nullable=True),
+        sa.Column("processed_height", sa.Integer(), nullable=True),
+        sa.Column("analysis_text", sa.Text(), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("version", sa.Integer(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("file_hash", name="uq_images_file_hash"),
+    )
+    op.create_index("ix_images_updated_at", "images", ["updated_at"])
+    op.create_index("ix_images_source", "images", ["source"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_images_source", table_name="images")
+    op.drop_index("ix_images_updated_at", table_name="images")
+    op.drop_table("images")

neobot_storage-1.0.0/src/neobot_storage/alembic/versions/0005_add_user_profile_refresh_fields.py

@@ -0,0 +1,32 @@
+"""新增用户画像刷新字段
+
+Revision ID: 0005
+Revises: 0004
+Create Date: 2026-04-12
+"""
+
+from __future__ import annotations
+
+from typing import Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision: str = "0005"
+down_revision: Union[str, None] = "0004"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("user_data", sa.Column("known_gender", sa.Text(), nullable=True))
+    op.add_column(
+        "user_data",
+        sa.Column("fetched_at", sa.DateTime(timezone=True), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("user_data", "fetched_at")
+    op.drop_column("user_data", "known_gender")

neobot_storage-1.0.0/src/neobot_storage/alembic/versions/0006_add_emojis_table.py

@@ -0,0 +1,46 @@
+"""新增 emojis 表
+
+Revision ID: 0006
+Revises: 0005
+Create Date: 2026-04-24
+"""
+
+from __future__ import annotations
+
+from typing import Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision: str = "0006"
+down_revision: Union[str, None] = "0005"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "emojis",
+        sa.Column("id", sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column("file_hash", sa.String(), nullable=False),
+        sa.Column("file_name", sa.String(), nullable=False),
+        sa.Column("file_path", sa.String(), nullable=False),
+        sa.Column("mime_type", sa.String(), nullable=True),
+        sa.Column("original_width", sa.Integer(), nullable=True),
+        sa.Column("original_height", sa.Integer(), nullable=True),
+        sa.Column("analysis_text", sa.Text(), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("version", sa.Integer(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("file_hash", name="uq_emojis_file_hash"),
+    )
+    op.create_index("ix_emojis_updated_at", "emojis", ["updated_at"])
+    op.create_index("ix_emojis_file_name", "emojis", ["file_name"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_emojis_file_name", table_name="emojis")
+    op.drop_index("ix_emojis_updated_at", table_name="emojis")
+    op.drop_table("emojis")

neobot_storage-1.0.0/src/neobot_storage/alembic/versions/0007_add_creator_images.py

@@ -0,0 +1,52 @@
+"""新增 creator_images 表
+
+Revision ID: 0007
+Revises: 0006
+Create Date: 2026-04-25
+"""
+
+from __future__ import annotations
+
+from typing import Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision: str = "0007"
+down_revision: Union[str, None] = "0006"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "creator_images",
+        sa.Column("id", sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column("image_id", sa.String(), nullable=False),
+        sa.Column("source", sa.String(), nullable=False),
+        sa.Column("file_hash", sa.String(), nullable=False),
+        sa.Column("file_path", sa.String(), nullable=False),
+        sa.Column("prompt", sa.Text(), nullable=True),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column("mime_type", sa.String(), nullable=True),
+        sa.Column("original_width", sa.Integer(), nullable=True),
+        sa.Column("original_height", sa.Integer(), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("version", sa.Integer(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("image_id", name="uq_creator_images_image_id"),
+    )
+    op.create_index(
+        "ix_creator_images_source_updated_at",
+        "creator_images",
+        ["source", "updated_at"],
+    )
+    op.create_index("ix_creator_images_file_hash", "creator_images", ["file_hash"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_creator_images_file_hash", table_name="creator_images")
+    op.drop_index("ix_creator_images_source_updated_at", table_name="creator_images")
+    op.drop_table("creator_images")