feat: cascade StrEnum validation + chat-agent integration guide#273
feat: cascade StrEnum validation + chat-agent integration guide#273Fearvox wants to merge 4 commits into
Conversation
Add ChangeKind, ChangeType, and ChangeStatus StrEnums to enforce valid values on the cascade work-queue table's kind, change_type, and status fields. Previously these accepted arbitrary strings despite documented valid values, causing confusing 'no handler registered' errors on typos. Follows the existing RunStatus(StrEnum) pattern in infra/ome/records.py. Refs: EverMind-AI#193
…ind-AI#193) Add docs/chat-agent-integration.md covering on-demand search vs per-turn RAG, write/read paths, time-range filtering, and an OpenAI-compatible memory_search tool schema. Add cross-reference from api.md /search section and entry in docs/index.md. Closes EverMind-AI#193 (documentation part).
The layered-architecture contract forbids everos.memory from importing everos.infra. Move ChangeKind/ChangeType/ChangeStatus to everos.core.enums — a shared layer accessible from both infra and memory. This also fixes the integration test_lap_append_during_handler_no_loss failure caused by the enum definitions living in a module that the memory layer could not legally reach.
P1-1: SQLAlchemy Enum stores enum *names* (EPISODE) not values (episode). Add values_callable=lambda e: [x.value for x in e] to all three StrEnum fields so SQLite stores lowercase values matching existing data and partial indexes. P1-2: Tool schema missed user_id/agent_id (required by SearchRequest) and had wrong top_k default (10 vs -1). Fixed schema and added XOR note. P2: Added test_db_stores_lowercase_enum_values — raw SQL round-trip verifying stored values are lowercase, not enum names.
|
@cyfyifanchen @hylarucoder Ready for review. Part A — Part B — Cross-model brake (GPT-5.5) already applied: caught SQLAlchemy Enum name-vs-value storage bug + tool schema field mismatches. All 7 CI gates green. |
| from enum import StrEnum | ||
|
|
||
|
|
||
| class ChangeKind(StrEnum): |
There was a problem hiding this comment.
src/everos/core/enums.py 这里的 Enum 命名太短了，按我的理解，如果提取到公用的 core 级别，命名需要有区分度，从 core 看代码可以直接知道是用在什么地方。可以适当参考 领域命名+字段命名结合。
这里 ChangeKind 太通用了，MemoryCascadeChangeKind 会直观很多。
There was a problem hiding this comment.
是的 应该再细分一下taxonomy Thx
| index=True, | ||
| sa_type=SAEnum(ChangeStatus, values_callable=lambda e: [x.value for x in e]), | ||
| ) | ||
| """Lifecycle: ``PENDING`` → ``PROCESSING`` → ``DONE`` | ``FAILED``.""" |
There was a problem hiding this comment.
我这里更倾向于 status: CascadeMutation = EnumField(ChangeStatus, nullable=False) 的封装，更加干净一些。可以考虑和 codex 聊一下封装 @Fearvox
What
Two improvements addressing validation gaps and documentation gaps:
Part A: StrEnum for cascade work-queue tables
md_change_state.kind,change_type, andstatuspreviously acceptedarbitrary strings despite documented valid values. A typo like
kind="epsiode"would silently fail with a confusing "no handlerregistered" error. This PR adds
ChangeKind,ChangeType, andChangeStatusStrEnums following the existingRunStatuspattern(
infra/ome/records.py).episode,atomic_fact,foresight,agent_case,agent_skill,user_profileadded,modified,deletedpending,processing,done,failedPart B: Chat-agent integration guide (#193)
Adds
docs/chat-agent-integration.mdwith:memory_searchtool JSON SchemaCloses #193 (documentation part — tool schema question).
Testing
make lintcleanscripts/check_docs.pypassed