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/redis_kit.py ADDED
@@ -0,0 +1,392 @@
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: 2026-08-22
21
+ """Redis 工具类,封装 Redis 的初始化、存储和读取操作
22
+
23
+ 重构说明(破坏性内部、外部零风险):
24
+ - 用 redis-py 自带的 ConnectionPool + Retry(指数退避)替代手写连接池
25
+ 与手写重试装饰器,大幅精简维护代码。
26
+ - decode_responses=True:运行期读操作直接返回 str,外部无需手动解码。
27
+ - 公开方法名、签名、返回值语义与重构前一致,外部调用零影响。
28
+
29
+ 类型说明:redis-py 的静态 stub 无法感知 decode_responses,返回值类型标注
30
+ 为 ``bytes | str`` 等较宽集合;运行时在 decode 模式下实际为 ``str``。
31
+ 为保持对外类型精确(`RedisValue`),本模块在与 redis-py 边界处使用显式
32
+ ``cast``(类型安全,非 type:ignore)。
33
+ """
34
+
35
+ from collections.abc import Iterator
36
+ from contextlib import contextmanager
37
+ from typing import cast
38
+
39
+ import redis
40
+ from redis.backoff import ExponentialWithJitterBackoff
41
+ from redis.retry import Retry
42
+
43
+ from yimo.kit.config.kit_config import get_settings
44
+ from yimo.kit.config.log_config import get_default_logger
45
+
46
+ settings = get_settings()
47
+ logger = get_default_logger(__name__)
48
+
49
+ # Redis 值类型(decode_responses=True 下,非字符串值仍可能为 bytes/int/float)
50
+ type RedisValue = str | int | float | bytes
51
+
52
+ _DEFAULT_SCAN_COUNT: int = 100
53
+ _RETRY_TOTAL: int = 3
54
+ _SOCKET_TIMEOUT: float = 5.0
55
+
56
+
57
+ class RedisKit:
58
+ """Redis 工具类,提供 Redis 连接管理和基本操作
59
+
60
+ 基于 redis-py 的 ConnectionPool 管理连接,所有方法均为类方法,
61
+ 业务代码无需实例化。
62
+ """
63
+
64
+ _POOL: redis.ConnectionPool | None = None
65
+ _CLIENT: redis.Redis | None = None
66
+
67
+ @classmethod
68
+ def _get_client(cls) -> redis.Redis:
69
+ """获取共享 Redis 客户端(惰性创建连接池)"""
70
+ if cls._CLIENT is None or cls._POOL is None:
71
+ cls._POOL = redis.ConnectionPool(
72
+ host=settings.REDIS_HOST,
73
+ port=settings.REDIS_PORT,
74
+ db=settings.REDIS_DB,
75
+ password=settings.REDIS_PASSWORD,
76
+ decode_responses=True,
77
+ socket_connect_timeout=_SOCKET_TIMEOUT,
78
+ retry=Retry(
79
+ ExponentialWithJitterBackoff(base=0.5, cap=8.0),
80
+ retries=_RETRY_TOTAL,
81
+ ),
82
+ retry_on_timeout=True,
83
+ retry_on_error=[redis.ConnectionError, redis.TimeoutError],
84
+ )
85
+ cls._CLIENT = redis.Redis(connection_pool=cls._POOL)
86
+ logger.info(
87
+ f"✅ Redis 连接池已初始化: "
88
+ f"{settings.REDIS_HOST}:{settings.REDIS_PORT}/db{settings.REDIS_DB}"
89
+ )
90
+ return cls._CLIENT
91
+
92
+ @classmethod
93
+ @contextmanager
94
+ def get_client(cls) -> Iterator[redis.Redis]:
95
+ """上下文管理器,获取 Redis 客户端
96
+
97
+ redis-py 的 ConnectionPool 保证线程安全,无需手动释放。
98
+ 保留此方法仅为兼容既有调用方式。
99
+ """
100
+ yield cls._get_client()
101
+
102
+ @classmethod
103
+ def set(cls, key: str, value: str, expire: int | None = None) -> bool:
104
+ """设置键值对
105
+
106
+ Args:
107
+ key: 键
108
+ value: 值
109
+ expire: 过期时间(秒),None 表示不过期
110
+
111
+ Returns:
112
+ True 表示设置成功
113
+ """
114
+ try:
115
+ cls._get_client().set(key, value, ex=expire)
116
+ return True
117
+ except redis.RedisError as e:
118
+ logger.error(f"❌ Redis 设置键值对失败: {e}, Key: {key}")
119
+ return False
120
+
121
+ @classmethod
122
+ def get(cls, key: str) -> RedisValue | None:
123
+ """获取键对应的值"""
124
+ try:
125
+ return cast(RedisValue | None, cls._get_client().get(key))
126
+ except redis.RedisError as e:
127
+ logger.error(f"❌ Redis 获取键值对失败: {e}, Key: {key}")
128
+ return None
129
+
130
+ @classmethod
131
+ def delete(cls, key: str) -> bool:
132
+ """删除键值对"""
133
+ try:
134
+ cls._get_client().delete(key)
135
+ return True
136
+ except redis.RedisError as e:
137
+ logger.error(f"❌ Redis 删除键值对失败: {e}, Key: {key}")
138
+ return False
139
+
140
+ @classmethod
141
+ def exists(cls, key: str) -> bool:
142
+ """检查键是否存在"""
143
+ try:
144
+ return bool(cls._get_client().exists(key))
145
+ except redis.RedisError as e:
146
+ logger.error(f"❌ Redis 检查键是否存在失败: {e}, Key: {key}")
147
+ return False
148
+
149
+ @classmethod
150
+ def keys(cls, pattern: str) -> list[str]:
151
+ """根据模式获取所有匹配的键"""
152
+ try:
153
+ client = cls._get_client()
154
+ matched: list[str] = []
155
+ cursor = 0
156
+ while True:
157
+ cursor, keys_batch = client.scan(
158
+ cursor=cursor, match=pattern, count=_DEFAULT_SCAN_COUNT
159
+ )
160
+ for key in keys_batch:
161
+ matched.append(
162
+ key.decode("utf-8") if isinstance(key, bytes) else key
163
+ )
164
+ if cursor == 0:
165
+ break
166
+ logger.info(f"✅ 成功获取 {len(matched)} 个匹配键")
167
+ return matched
168
+ except redis.RedisError as e:
169
+ logger.error(f"❌ Redis 获取匹配键失败: {e}, Pattern: {pattern}")
170
+ return []
171
+
172
+ @classmethod
173
+ def batch_set(
174
+ cls, key_value_pairs: dict[str, str], expire: int | None = None
175
+ ) -> bool:
176
+ """批量设置键值对"""
177
+ if not key_value_pairs:
178
+ logger.warning("批量设置操作的键值对字典为空")
179
+ return False
180
+ try:
181
+ pipe = cls._get_client().pipeline()
182
+ for key, value in key_value_pairs.items():
183
+ pipe.set(key, value, ex=expire)
184
+ pipe.execute()
185
+ logger.info(f"✅ 成功批量设置 {len(key_value_pairs)} 个键值对")
186
+ return True
187
+ except redis.RedisError as e:
188
+ logger.error(f"❌ Redis 批量设置键值对失败: {e}")
189
+ return False
190
+
191
+ @classmethod
192
+ def batch_get(cls, keys: list[str]) -> dict[str, RedisValue | None]:
193
+ """批量获取键对应的值"""
194
+ if not keys:
195
+ logger.warning("批量获取操作的键列表为空")
196
+ return {}
197
+ try:
198
+ pipe = cls._get_client().pipeline()
199
+ for key in keys:
200
+ pipe.get(key)
201
+ values = pipe.execute()
202
+ logger.info(f"✅ 成功批量获取 {len(keys)} 个键值对")
203
+ return cast(dict[str, RedisValue | None], dict(zip(keys, values)))
204
+ except redis.RedisError as e:
205
+ logger.error(f"❌ Redis 批量获取键值对失败: {e}")
206
+ return {}
207
+
208
+ @classmethod
209
+ def batch_delete(cls, keys: list[str]) -> bool:
210
+ """批量删除键值对"""
211
+ if not keys:
212
+ logger.warning("批量删除操作的键列表为空")
213
+ return False
214
+ try:
215
+ cls._get_client().delete(*keys)
216
+ logger.info(f"✅ 成功批量删除 {len(keys)} 个键值对")
217
+ return True
218
+ except redis.RedisError as e:
219
+ logger.error(f"❌ Redis 批量删除键值对失败: {e}")
220
+ return False
221
+
222
+ @classmethod
223
+ def close(cls) -> None:
224
+ """关闭所有 Redis 连接"""
225
+ if cls._POOL is not None:
226
+ cls._POOL.disconnect()
227
+ cls._POOL = None
228
+ cls._CLIENT = None
229
+ logger.info("Redis 连接池已关闭")
230
+
231
+ @classmethod
232
+ def hset(cls, key: str, field: str, value: RedisValue) -> bool:
233
+ """设置 Hash 字段值"""
234
+ try:
235
+ cls._get_client().hset(key, field, value)
236
+ return True
237
+ except redis.RedisError as e:
238
+ logger.error(f"❌ Redis Hash 设置失败: {e}, Key: {key}, Field: {field}")
239
+ return False
240
+
241
+ @classmethod
242
+ def hget(cls, key: str, field: str) -> RedisValue | None:
243
+ """获取 Hash 字段值"""
244
+ try:
245
+ return cast(RedisValue | None, cls._get_client().hget(key, field))
246
+ except redis.RedisError as e:
247
+ logger.error(f"❌ Redis Hash 获取失败: {e}, Key: {key}, Field: {field}")
248
+ return None
249
+
250
+ @classmethod
251
+ def hgetall(cls, key: str) -> dict[str, RedisValue]:
252
+ """获取 Hash 所有字段和值"""
253
+ try:
254
+ raw = cls._get_client().hgetall(key)
255
+ return cast(dict[str, RedisValue], raw)
256
+ except redis.RedisError as e:
257
+ logger.error(f"❌ Redis Hash 获取所有失败: {e}, Key: {key}")
258
+ return {}
259
+
260
+ @classmethod
261
+ def hdel(cls, key: str, *fields: str) -> bool:
262
+ """删除 Hash 字段"""
263
+ try:
264
+ cls._get_client().hdel(key, *fields)
265
+ return True
266
+ except redis.RedisError as e:
267
+ logger.error(f"❌ Redis Hash 删除失败: {e}, Key: {key}")
268
+ return False
269
+
270
+ @classmethod
271
+ def lpush(cls, key: str, *values: RedisValue) -> bool:
272
+ """从左侧推入 List 元素"""
273
+ try:
274
+ cls._get_client().lpush(key, *values)
275
+ return True
276
+ except redis.RedisError as e:
277
+ logger.error(f"❌ Redis List 左侧推入失败: {e}, Key: {key}")
278
+ return False
279
+
280
+ @classmethod
281
+ def rpush(cls, key: str, *values: RedisValue) -> bool:
282
+ """从右侧推入 List 元素"""
283
+ try:
284
+ cls._get_client().rpush(key, *values)
285
+ return True
286
+ except redis.RedisError as e:
287
+ logger.error(f"❌ Redis List 右侧推入失败: {e}, Key: {key}")
288
+ return False
289
+
290
+ @classmethod
291
+ def lpop(cls, key: str) -> RedisValue | None:
292
+ """从左侧弹出 List 元素"""
293
+ try:
294
+ return cast(RedisValue | None, cls._get_client().lpop(key))
295
+ except redis.RedisError as e:
296
+ logger.error(f"❌ Redis List 左侧弹出失败: {e}, Key: {key}")
297
+ return None
298
+
299
+ @classmethod
300
+ def rpop(cls, key: str) -> RedisValue | None:
301
+ """从右侧弹出 List 元素"""
302
+ try:
303
+ return cast(RedisValue | None, cls._get_client().rpop(key))
304
+ except redis.RedisError as e:
305
+ logger.error(f"❌ Redis List 右侧弹出失败: {e}, Key: {key}")
306
+ return None
307
+
308
+ @classmethod
309
+ def lrange(cls, key: str, start: int, stop: int) -> list[RedisValue]:
310
+ """获取 List 指定范围的元素"""
311
+ try:
312
+ return cast(list[RedisValue], cls._get_client().lrange(key, start, stop))
313
+ except redis.RedisError as e:
314
+ logger.error(f"❌ Redis List 范围获取失败: {e}, Key: {key}")
315
+ return []
316
+
317
+ @classmethod
318
+ def sadd(cls, key: str, *members: RedisValue) -> bool:
319
+ """添加 Set 成员"""
320
+ try:
321
+ cls._get_client().sadd(key, *members)
322
+ return True
323
+ except redis.RedisError as e:
324
+ logger.error(f"❌ Redis Set 添加成员失败: {e}, Key: {key}")
325
+ return False
326
+
327
+ @classmethod
328
+ def srem(cls, key: str, *members: RedisValue) -> bool:
329
+ """删除 Set 成员"""
330
+ try:
331
+ cls._get_client().srem(key, *members)
332
+ return True
333
+ except redis.RedisError as e:
334
+ logger.error(f"❌ Redis Set 删除成员失败: {e}, Key: {key}")
335
+ return False
336
+
337
+ @classmethod
338
+ def smembers(cls, key: str) -> list[RedisValue]:
339
+ """获取 Set 所有成员"""
340
+ try:
341
+ return cast(list[RedisValue], cls._get_client().smembers(key))
342
+ except redis.RedisError as e:
343
+ logger.error(f"❌ Redis Set 获取成员失败: {e}, Key: {key}")
344
+ return []
345
+
346
+ @classmethod
347
+ def sismember(cls, key: str, member: RedisValue) -> bool:
348
+ """检查成员是否在 Set 中"""
349
+ try:
350
+ return bool(cls._get_client().sismember(key, cast(str, member)))
351
+ except redis.RedisError as e:
352
+ logger.error(f"❌ Redis Set 检查成员失败: {e}, Key: {key}")
353
+ return False
354
+
355
+ @classmethod
356
+ def zadd(cls, key: str, mapping: dict[RedisValue, float]) -> bool:
357
+ """添加 Sorted Set 成员"""
358
+ try:
359
+ cls._get_client().zadd(key, cast(dict[str, float], mapping))
360
+ return True
361
+ except redis.RedisError as e:
362
+ logger.error(f"❌ Redis Sorted Set 添加成员失败: {e}, Key: {key}")
363
+ return False
364
+
365
+ @classmethod
366
+ def zrange(
367
+ cls,
368
+ key: str,
369
+ start: int,
370
+ stop: int,
371
+ withscores: bool = False,
372
+ ) -> list[RedisValue] | list[tuple[RedisValue, float]]:
373
+ """获取 Sorted Set 指定范围的成员
374
+
375
+ Args:
376
+ key: 键
377
+ start: 起始索引
378
+ stop: 结束索引
379
+ withscores: 是否同时返回分数
380
+
381
+ Returns:
382
+ withscores=False 时返回成员列表;
383
+ withscores=True 时返回 (成员, 分数) 元组列表
384
+ """
385
+ try:
386
+ if withscores:
387
+ raw = cls._get_client().zrange(key, start, stop, withscores=True)
388
+ return cast(list[tuple[RedisValue, float]], raw)
389
+ return cast(list[RedisValue], cls._get_client().zrange(key, start, stop))
390
+ except redis.RedisError as e:
391
+ logger.error(f"❌ Redis Sorted Set 范围获取失败: {e}, Key: {key}")
392
+ return []