yimo-kit 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. yimo/__init__.py +26 -0
  2. yimo/kit/__init__.py +98 -0
  3. yimo/kit/ai/__init__.py +110 -0
  4. yimo/kit/ai/_internal/__init__.py +27 -0
  5. yimo/kit/ai/_internal/failover.py +535 -0
  6. yimo/kit/ai/_internal/pool.py +526 -0
  7. yimo/kit/ai/_internal/rerank_transport.py +137 -0
  8. yimo/kit/ai/_internal/retry_after.py +51 -0
  9. yimo/kit/ai/_internal/sdk_client.py +463 -0
  10. yimo/kit/ai/_internal/service_base.py +115 -0
  11. yimo/kit/ai/_internal/types.py +28 -0
  12. yimo/kit/ai/agent/__init__.py +127 -0
  13. yimo/kit/ai/agent/approval.py +66 -0
  14. yimo/kit/ai/agent/errors.py +128 -0
  15. yimo/kit/ai/agent/loop.py +643 -0
  16. yimo/kit/ai/agent/mcp.py +278 -0
  17. yimo/kit/ai/agent/registry.py +203 -0
  18. yimo/kit/ai/agent/session.py +150 -0
  19. yimo/kit/ai/agent/skill.py +370 -0
  20. yimo/kit/ai/agent/types.py +161 -0
  21. yimo/kit/ai/chat_service.py +724 -0
  22. yimo/kit/ai/decision/__init__.py +57 -0
  23. yimo/kit/ai/decision/decima.py +853 -0
  24. yimo/kit/ai/decision/laya.py +552 -0
  25. yimo/kit/ai/embedding_service.py +198 -0
  26. yimo/kit/ai/exceptions.py +109 -0
  27. yimo/kit/ai/image_service.py +84 -0
  28. yimo/kit/ai/messages.py +105 -0
  29. yimo/kit/ai/model_builder.py +121 -0
  30. yimo/kit/ai/model_client.py +62 -0
  31. yimo/kit/ai/profiles.py +577 -0
  32. yimo/kit/ai/rerank_service.py +136 -0
  33. yimo/kit/ai/runner.py +1127 -0
  34. yimo/kit/common_kit.py +221 -0
  35. yimo/kit/config/__init__.py +44 -0
  36. yimo/kit/config/kit_config.py +210 -0
  37. yimo/kit/config/log_config.py +171 -0
  38. yimo/kit/crawl/__init__.py +71 -0
  39. yimo/kit/crawl/article_io.py +325 -0
  40. yimo/kit/crawl/article_models.py +172 -0
  41. yimo/kit/crawl/deepseek_kit.py +673 -0
  42. yimo/kit/crawl/web_article_kit.py +638 -0
  43. yimo/kit/crawl/wx_article_kit.py +692 -0
  44. yimo/kit/db/__init__.py +101 -0
  45. yimo/kit/db/audit.py +625 -0
  46. yimo/kit/db/base_db_kit.py +1265 -0
  47. yimo/kit/db/crud.py +423 -0
  48. yimo/kit/db/engine.py +235 -0
  49. yimo/kit/db/exceptions.py +45 -0
  50. yimo/kit/db/models/__init__.py +33 -0
  51. yimo/kit/db/models/base.py +56 -0
  52. yimo/kit/db/mysql_kit.py +348 -0
  53. yimo/kit/db/pg_kit.py +442 -0
  54. yimo/kit/db/query.py +338 -0
  55. yimo/kit/db/session.py +85 -0
  56. yimo/kit/db/sqlite_kit.py +462 -0
  57. yimo/kit/db/transaction.py +109 -0
  58. yimo/kit/docs/__init__.py +34 -0
  59. yimo/kit/docs/anydoc_kit.py +490 -0
  60. yimo/kit/docs/docx_kit.py +895 -0
  61. yimo/kit/docs/md2doc_kit.py +1801 -0
  62. yimo/kit/docs/mineru_kit.py +1497 -0
  63. yimo/kit/docs/rc_docparser_kit.py +654 -0
  64. yimo/kit/file_kit.py +518 -0
  65. yimo/kit/license_kit.py +533 -0
  66. yimo/kit/redis_kit.py +392 -0
  67. yimo_kit-0.1.0.dist-info/METADATA +1673 -0
  68. yimo_kit-0.1.0.dist-info/RECORD +70 -0
  69. yimo_kit-0.1.0.dist-info/WHEEL +4 -0
  70. yimo_kit-0.1.0.dist-info/licenses/LICENSE +201 -0
yimo/kit/db/query.py ADDED
@@ -0,0 +1,338 @@
1
+ """
2
+ Copyright (c) 2021-2026 溢墨修心(Yimo). All Rights Reserved.
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+
16
+ Project: yimo
17
+ Author: 溢墨修心(Yimo)
18
+ """
19
+
20
+ # date: 2025-04-19
21
+ """查询构建器(不可变)+ 线程安全查询缓存
22
+
23
+ QueryBuilder 采用不可变设计:每个链式方法返回新实例,避免状态副作用。
24
+ count() 从原始模型构建独立计数查询,仅复制 WHERE 条件,不受 limit/offset 影响。
25
+ """
26
+
27
+ import functools
28
+ import threading
29
+ import time
30
+ from collections.abc import Callable
31
+ from datetime import UTC, datetime, timedelta
32
+ from typing import Any, TypeVar
33
+
34
+ from sqlalchemy import func
35
+ from sqlalchemy.orm import load_only
36
+ from sqlmodel import Session, SQLModel, select
37
+
38
+ from yimo.kit.config.log_config import get_default_logger
39
+
40
+ logger = get_default_logger(__name__)
41
+
42
+ T = TypeVar("T", bound=SQLModel)
43
+
44
+
45
+ class QueryBuilder:
46
+ """不可变链式查询构建器
47
+
48
+ 每个链式方法返回新的 QueryBuilder 实例,避免修改原始 builder 的状态。
49
+ 这允许同一个 builder 安全复用于不同查询。
50
+
51
+ 用法::
52
+
53
+ qb = QueryBuilder(User, session)
54
+ active = qb.filter(User.is_active == True).all()
55
+ # qb 的状态未被修改,可继续复用
56
+ young = qb.filter(User.age < 30).all()
57
+ """
58
+
59
+ def __init__(self, model: type[T], session: Session):
60
+ self._model = model
61
+ self._session = session
62
+ self._statement = select(model)
63
+
64
+ def _clone(self) -> "QueryBuilder[T]":
65
+ """创建当前 builder 的浅拷贝(SQLAlchemy Select 不可变,直接引用即可)"""
66
+ new = QueryBuilder.__new__(QueryBuilder)
67
+ new._model = self._model
68
+ new._session = self._session
69
+ new._statement = self._statement
70
+ return new
71
+
72
+ def filter(self, *conditions) -> "QueryBuilder[T]":
73
+ """添加过滤条件"""
74
+ builder = self._clone()
75
+ if conditions:
76
+ builder._statement = builder._statement.where(*conditions)
77
+ return builder
78
+
79
+ def filter_by(self, **kwargs) -> "QueryBuilder[T]":
80
+ """按字段值过滤(等值条件)"""
81
+ conditions = [
82
+ getattr(self._model, key) == value for key, value in kwargs.items()
83
+ ]
84
+ return self.filter(*conditions)
85
+
86
+ def join(self, target, onclause=None, isouter: bool = False) -> "QueryBuilder[T]":
87
+ """添加 JOIN"""
88
+ builder = self._clone()
89
+ builder._statement = (
90
+ builder._statement.join(target, onclause, isouter=isouter)
91
+ if onclause
92
+ else builder._statement.join(target, isouter=isouter)
93
+ )
94
+ return builder
95
+
96
+ def order_by(self, *columns) -> "QueryBuilder[T]":
97
+ """排序"""
98
+ builder = self._clone()
99
+ builder._statement = builder._statement.order_by(*columns)
100
+ return builder
101
+
102
+ def limit(self, limit: int) -> "QueryBuilder[T]":
103
+ """限制返回行数"""
104
+ builder = self._clone()
105
+ builder._statement = builder._statement.limit(limit)
106
+ return builder
107
+
108
+ def offset(self, offset: int) -> "QueryBuilder[T]":
109
+ """跳过前 N 行"""
110
+ builder = self._clone()
111
+ builder._statement = builder._statement.offset(offset)
112
+ return builder
113
+
114
+ def distinct(self) -> "QueryBuilder[T]":
115
+ """去重"""
116
+ builder = self._clone()
117
+ builder._statement = builder._statement.distinct()
118
+ return builder
119
+
120
+ def only(self, *field_names: str) -> "QueryBuilder[T]":
121
+ """只加载指定字段"""
122
+ builder = self._clone()
123
+ columns = [getattr(self._model, name) for name in field_names]
124
+ builder._statement = builder._statement.options(load_only(*columns))
125
+ return builder
126
+
127
+ # ==================== 执行方法 ====================
128
+
129
+ def all(self) -> list[T]:
130
+ """获取所有记录"""
131
+ return list(self._session.exec(self._statement).all())
132
+
133
+ def first(self) -> T | None:
134
+ """获取第一条记录"""
135
+ return self._session.exec(self._statement.limit(1)).first()
136
+
137
+ def count(self) -> int:
138
+ """获取记录数(不受 limit/offset 影响)"""
139
+ # 从原始模型构建计数查询,仅保留 WHERE 条件,忽略 limit/offset
140
+ count_stmt = select(func.count()).select_from(self._model)
141
+ whereclause = self._statement.whereclause
142
+ if whereclause is not None:
143
+ count_stmt = count_stmt.where(whereclause)
144
+ return self._session.exec(count_stmt).one()
145
+
146
+ def exists(self) -> bool:
147
+ """检查是否存在符合条件的记录"""
148
+ from sqlalchemy import exists as sa_exists
149
+
150
+ exists_stmt = select(sa_exists().where(self._statement.whereclause))
151
+ return bool(self._session.exec(exists_stmt).one())
152
+
153
+ def paginate(self, page: int = 1, per_page: int = 20) -> dict[str, Any]:
154
+ """分页查询
155
+
156
+ Args:
157
+ page: 页码(从 1 开始)
158
+ per_page: 每页条数
159
+
160
+ Returns:
161
+ 包含 items/total/page/per_page/pages/has_prev/has_next 的字典
162
+ """
163
+ offset = (page - 1) * per_page
164
+ total = self.count()
165
+
166
+ paginated = self._statement.offset(offset).limit(per_page)
167
+ items = list(self._session.exec(paginated).all())
168
+
169
+ return {
170
+ "items": items,
171
+ "total": total,
172
+ "page": page,
173
+ "per_page": per_page,
174
+ "pages": (total + per_page - 1) // per_page if per_page > 0 else 0,
175
+ "has_prev": page > 1,
176
+ "has_next": page * per_page < total,
177
+ }
178
+
179
+
180
+ class QueryCache:
181
+ """线程安全的查询缓存(TTL + LRU 淘汰)"""
182
+
183
+ def __init__(self, default_ttl: int = 300, maxsize: int = 1000):
184
+ self._cache: dict[str, dict[str, Any]] = {}
185
+ self._default_ttl = default_ttl
186
+ self._maxsize = maxsize
187
+ self._lock = threading.RLock()
188
+
189
+ def get(self, key: str) -> Any | None:
190
+ """获取缓存值"""
191
+ with self._lock:
192
+ if key not in self._cache:
193
+ return None
194
+ item = self._cache[key]
195
+ if item["expires_at"] > datetime.now(UTC):
196
+ return item["value"]
197
+ del self._cache[key]
198
+ return None
199
+
200
+ def set(self, key: str, value: Any, ttl: int | None = None) -> None:
201
+ """设置缓存值"""
202
+ with self._lock:
203
+ # 达到上限时清理最早的条目
204
+ if len(self._cache) >= self._maxsize:
205
+ oldest = min(self._cache, key=lambda k: self._cache[k]["expires_at"])
206
+ del self._cache[oldest]
207
+ self._cache[key] = {
208
+ "value": value,
209
+ "expires_at": datetime.now(UTC)
210
+ + timedelta(seconds=ttl or self._default_ttl),
211
+ }
212
+
213
+ def delete(self, key: str) -> None:
214
+ """删除缓存"""
215
+ with self._lock:
216
+ self._cache.pop(key, None)
217
+
218
+ def clear(self) -> None:
219
+ """清空缓存"""
220
+ with self._lock:
221
+ self._cache.clear()
222
+
223
+ def clean_expired(self) -> int:
224
+ """清理过期缓存,返回清理的条目数"""
225
+ with self._lock:
226
+ now = datetime.now(UTC)
227
+ expired = [k for k, v in self._cache.items() if v["expires_at"] <= now]
228
+ for k in expired:
229
+ del self._cache[k]
230
+ return len(expired)
231
+
232
+
233
+ class QueryOptimizer:
234
+ """查询优化器:分析执行计划、建议索引、监控性能"""
235
+
236
+ def __init__(self, session: Session):
237
+ self.session = session
238
+ self._stats: list[dict[str, Any]] = []
239
+
240
+ def explain(self, statement) -> dict[str, Any]:
241
+ """分析查询执行计划"""
242
+ from sqlalchemy import text
243
+
244
+ dialect = self.session.get_bind().dialect.name
245
+ compiled = statement.compile(self.session.get_bind())
246
+
247
+ try:
248
+ if dialect == "postgresql":
249
+ result = self.session.execute(text(f"EXPLAIN (FORMAT JSON) {compiled}"))
250
+ return {"dialect": dialect, "plan": result.scalar()}
251
+ elif dialect == "mysql":
252
+ result = self.session.execute(text(f"EXPLAIN FORMAT=JSON {compiled}"))
253
+ return {"dialect": dialect, "plan": result.scalar()}
254
+ elif dialect == "sqlite":
255
+ result = self.session.execute(text(f"EXPLAIN QUERY PLAN {compiled}"))
256
+ return {
257
+ "dialect": dialect,
258
+ "plan": [dict(row._mapping) for row in result.fetchall()],
259
+ }
260
+ else:
261
+ return {"dialect": dialect, "plan": None, "error": "不支持的数据库"}
262
+ except Exception as e:
263
+ logger.error(f"❌ 查询分析失败: {e}")
264
+ return {"error": str(e)}
265
+
266
+ def suggest_indexes(
267
+ self, model: type[SQLModel], query_fields: list[str]
268
+ ) -> list[str]:
269
+ """建议索引"""
270
+ table_name = model.__tablename__
271
+ suggestions = [
272
+ f"CREATE INDEX idx_{table_name}_{field} ON {table_name}({field});"
273
+ for field in query_fields
274
+ ]
275
+ if len(query_fields) > 1:
276
+ composite = "_".join(query_fields[:3])
277
+ suggestions.append(
278
+ f"CREATE INDEX idx_{table_name}_{composite} "
279
+ f"ON {table_name}({', '.join(query_fields[:3])});"
280
+ )
281
+ return suggestions
282
+
283
+ def measure(self, statement, params: dict | None = None) -> dict[str, Any]:
284
+ """测量查询性能"""
285
+ start = time.time()
286
+ try:
287
+ result = self.session.execute(statement, params or {})
288
+ rows = result.fetchall()
289
+ elapsed = time.time() - start
290
+
291
+ stats: dict[str, Any] = {
292
+ "execution_time": elapsed,
293
+ "row_count": len(rows),
294
+ "timestamp": datetime.now(UTC).isoformat(),
295
+ }
296
+ if elapsed > 1.0:
297
+ stats["warning"] = "慢查询"
298
+ logger.warning(f"⚠️ 慢查询: {elapsed:.2f}s, 返回 {len(rows)} 行")
299
+ self._stats.append(stats)
300
+ return stats
301
+ except Exception as e:
302
+ logger.error(f"❌ 性能测量失败: {e}")
303
+ return {"error": str(e)}
304
+
305
+ @property
306
+ def stats(self) -> list[dict[str, Any]]:
307
+ """获取查询统计信息"""
308
+ return list(self._stats)
309
+
310
+ def clear_stats(self) -> None:
311
+ """清空统计信息"""
312
+ self._stats.clear()
313
+
314
+
315
+ def cached_query(ttl: int = 300, maxsize: int = 1000) -> Callable:
316
+ """查询缓存装饰器
317
+
318
+ 注意:被装饰的函数不应将 Session 作为参数,否则每次缓存键不同。
319
+ """
320
+ cache = QueryCache(default_ttl=ttl, maxsize=maxsize)
321
+
322
+ def decorator(func: Callable) -> Callable:
323
+ @functools.wraps(func)
324
+ def wrapper(*args, **kwargs):
325
+ cache_key = f"{func.__name__}:{repr(args)}:{repr(kwargs)}"
326
+ cached = cache.get(cache_key)
327
+ if cached is not None:
328
+ logger.debug(f"✅ 缓存命中: {func.__name__}")
329
+ return cached
330
+ result = func(*args, **kwargs)
331
+ cache.set(cache_key, result, ttl)
332
+ return result
333
+
334
+ # 暴露缓存实例供外部管理
335
+ wrapper._cache = cache # type: ignore
336
+ return wrapper
337
+
338
+ return decorator
yimo/kit/db/session.py ADDED
@@ -0,0 +1,85 @@
1
+ """
2
+ Copyright (c) 2021-2026 溢墨修心(Yimo). All Rights Reserved.
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+
16
+ Project: yimo
17
+ Author: 溢墨修心(Yimo)
18
+ """
19
+
20
+ # date: 2025-04-19
21
+ """统一的会话管理模块
22
+
23
+ 提供唯一的会话入口 session_scope,自动管理提交/回滚/关闭。
24
+ CRUD 操作不应在内部调用 commit/rollback,由 session_scope 统一管理事务边界。
25
+ """
26
+
27
+ from contextlib import contextmanager
28
+ from typing import Generator
29
+
30
+ from sqlmodel import Session
31
+
32
+ from yimo.kit.config.log_config import get_default_logger
33
+ from yimo.kit.db.engine import get_engine
34
+
35
+ logger = get_default_logger(__name__)
36
+
37
+
38
+ @contextmanager
39
+ def session_scope(
40
+ db_type: str | None = None,
41
+ *,
42
+ autocommit: bool = True,
43
+ ) -> Generator[Session, None, None]:
44
+ """会话作用域上下文管理器(唯一的会话入口)
45
+
46
+ 正常退出时自动提交(autocommit=True),异常时自动回滚,最终关闭会话。
47
+
48
+ Args:
49
+ db_type: 数据库类型(postgresql/mysql/sqlite),None 时使用配置默认值
50
+ autocommit: 是否在正常退出时自动提交事务
51
+
52
+ Yields:
53
+ SQLModel Session 实例
54
+
55
+ 用法::
56
+
57
+ with session_scope() as session:
58
+ user = User(name="test")
59
+ session.add(user)
60
+ # 退出时自动提交
61
+ """
62
+ engine = get_engine(db_type)
63
+ session = Session(engine)
64
+ db_name = db_type or "默认"
65
+
66
+ try:
67
+ yield session
68
+ if autocommit:
69
+ session.commit()
70
+ logger.info(f"✅ [{db_name}] 会话事务已提交")
71
+ except Exception as e:
72
+ session.rollback()
73
+ logger.warning(f"⚠️ [{db_name}] 会话事务已回滚,原因: {e}")
74
+ raise
75
+ finally:
76
+ session.close()
77
+
78
+
79
+ def get_session(db_type: str | None = None) -> Session:
80
+ """获取裸 Session(调用者需自行管理生命周期)
81
+
82
+ 建议优先使用 session_scope 上下文管理器。
83
+ """
84
+ engine = get_engine(db_type)
85
+ return Session(engine)