09 Dec 15:12

xuemzhan

3763e09

v0.4.0 Latest

Latest

Changelog

All notable changes to this project will be documented in this file.

格式说明：

Features / 新特性：新增能力、重要增强。
Bugfixes / 缺陷修复：行为错误、并发问题、稳定性修复。
Breaking Changes / 兼容性变更：可能影响现有代码的 API 或行为变更。

[0.4.0] - 2025-12-09

Features / 新特性

Observability & Telemetry

统一可观测性体系
- 增强 gecko/core/telemetry.py：
  - 使用 opentelemetry-sdk>=1.38 推荐方式创建 Resource，支持 service.name、service.version、deployment.environment 等标准字段。
  - 新增 TelemetryConfig 配置项：batch_export_interval_ms、max_export_batch_size，可根据生产环境吞吐和延迟需求调优。
- get_telemetry() 支持 自动初始化：首次调用时会创建默认 GeckoTelemetry 并立即 setup()，降低接入门槛。
- Telemetry 与 logging 的 trace_id/span_id 通过 ContextVar 打通，保证日志与 Trace 关联一致。
Metrics 指标体系
- 引入轻量级指标模块 gecko/core/metrics.py（Counter/Gauge/Histogram）：
  - 支持高并发下的分片锁（shard-based locking）减少锁竞争。
  - 提供计时场景的上下文管理器，便捷记录接口耗时。
  - 支持导出 Prometheus 文本格式，便于对接监控系统。
ExecutionStats 执行统计
- 新增 gecko/core/engine/stats.py（或同名模块）：
  - 统一记录引擎执行维度的统计信息：total_steps、total_time、input_tokens、output_tokens、tool_calls、errors、estimated_cost。
  - 内部使用 threading.Lock 保证并发安全。
  - 提供 get_avg_step_time()、get_error_rate()、get_total_tokens() 等便捷方法。
- 各 Engine 通过 Hook 在每步执行后更新统计，为后续成本监控与性能分析打基础。

Memory / 记忆系统

HybridMemory：短期 + 长期混合记忆
- 新增 gecko/core/memory/hybrid.py：
  - 基于 TokenMemory（短期上下文）与向量库（长期记忆）的组合设计。
  - get_history() 中并行执行短期与长期检索（asyncio.gather），在给模型的上下文中按照：
    System Prompt → Long-term Context(System) → Short-term History 的顺序拼装消息。
  - 长期检索使用 embedder.embed_query + vector_store.search(filters={"session_id": self.session_id})，保证多会话隔离。
  - archive_message() 仅归档长度大于一定阈值的消息，减少噪声数据写入向量库。
- 在 gecko/core/memory/__init__.py 中导出 HybridMemory，可直接：
  from gecko.core.memory import HybridMemory 使用。

Workflow / 组合与工作流

Workflow Engine DAG 并行与恢复能力增强
- gecko/compose/workflow/graph.py：
  - 负责管理 Workflow DAG：节点/边维护、拓扑排序、并行层级构建。
  - 增强静态校验：环检测（cycle detection）、孤立节点检测，异常一律使用 WorkflowError 子类。
- gecko/compose/workflow/engine.py：
  - 按层级并行执行 DAG（每一层使用 TaskGroup 并行）。
  - 引入 COW + Diff Merge 的上下文管理策略：
    - 并行节点使用 copy-on-write 视图，避免互相污染；
    - 执行结束后按“最后写入优先”策略合并变更。
  - 支持 Next(...) 动态控制流：
    - 节点返回 Next 指令可以覆盖默认拓扑路径，实现条件跳转与动态分支。
  - 支持断点恢复：
    - 可以从持久化状态恢复并从指定节点继续执行。
Team 执行策略扩展（并行/赛马）
- gecko/compose/team.py：
  - 新增 ExecutionStrategy：ALL 与 RACE 模式：
    - ALL：等待所有 Agent 成员执行完成（Map-Reduce 默认模式）。
    - RACE：赛马模式，取第一个成功结果，其它任务自动取消。
  - 新增 input_mapper，支持从一个输入生成多个子输入（Sharding）后分配给不同成员。
  - 为 RACE 模式引入 _winner_lock，保证并发场景下只有一个“获胜者”被选中。

Structure / 结构化输出

结构化输出自愈修复能力
- 新增 gecko/core/structure/repair.py：
  - 提供基于 LLM 的 JSON 自修复功能：
    - 将「破损/不合法 JSON + 解析错误信息」作为 Prompt，交给模型生成修复后的结构化输出。
- gecko/core/structure/engine.py 更新解析策略：
  - 结构化解析路径分为三层：
    1. 优先从 ToolCall 直接解析为结构化数据；
    2. 从文本中提取 JSON（json_extractor），再做 Pydantic 校验；
    3. 如仍失败，调用 repair 模块进行 LLM 自愈（有限次数）。
JSON 提取器增强
- gecko/core/structure/json_extractor.py：
  - 提供多策略 JSON 提取：正则、括号匹配、Markdown 代码块等；
  - 支持插件式扩展提取策略。

Resilience / 系统韧性

熔断器（Circuit Breaker）模块
- 新增 gecko/core/resilience.py：
  - 实现通用熔断器，可包装模型调用或任意外部 IO。
  - 支持失败计数、半开窗口、冷却时间等配置。
  - 防止下游服务连续失败导致整系统被拖垮。

Models / Provider 适配

统一 Provider 异常体系
- 新增 gecko/plugins/models/exceptions.py：
  - 引入 ProviderError 及其子类（RateLimit/Auth/ServiceUnavailable 等），统一继承自 ModelError。
  - 将模型服务相关错误统一编码为 ErrorCode，便于上层统一处理与监控。
LiteLLM Driver 生产级化
- gecko/plugins/models/drivers/litellm_driver.py：
  - 引入 tokenizer 预加载：优先使用 tiktoken，不可用时退回字符长度估算，提升 Token 计数精度。
  - 使用 gecko/core/resilience 的熔断器包装请求，增强对 LiteLLM / 模型代理不稳定的容错能力。
  - 将 LiteLLM 错误统一映射到 ProviderError 子类，填充 ErrorCode 和可重试信息。
  - 增加响应适配层，将 LiteLLM 输出转换为框架统一的响应结构。

Bugfixes / 缺陷修复

Concurrency / 并发安全

ToolBox 统计并发问题修复
- gecko/core/toolbox.py：
  - get_stats() 中改为在持有锁时对 self._tools 做快照（tool_names = list(self._tools.keys())），并在迭代时检查 name in self._execution_count，防止工具在统计过程中被移除引发 KeyError。
流式缓冲区完整性修复
- gecko/core/engine/buffer.py：
  - 增强对流式 tool_calls 的索引和分片处理：记录 _max_tool_index，保证乱序/分片场景下的结果正确重组。
  - 增加 _max_content_chars 上限，防止异常长返回撑爆内存。
  - 引入 RLock 保护更新和构建逻辑，在多线程/异步混用场景下保持一致性。

Engine / Workflow 行为修复

ReAct 引擎 Message 参数不兼容问题
- gecko/core/engine/react.py：
  - 修复 Message.assistant(tool_calls=...) 与 Message 模型签名不一致导致的 TypeError。
  - 优先从 tool_calls 解析结构化结果，其次才回退到 content 文本解析，避免丢失 ToolCall 信息。
Next 控制流透传问题
- gecko/compose/workflow/executor.py：
  - 修复部分路径下 Next(...) 被当作普通返回值处理的问题，确保由 Executor 识别并作为控制流指令传回 WorkflowEngine。
Workflow 图校验增强
- gecko/compose/workflow/graph.py：
  - 增强环检测和孤立节点检测逻辑，并统一使用 WorkflowError 子类抛出，避免工作流在运行时才暴露拓扑问题。

Logging & Tracing

日志上下文一致性修复
- gecko/core/logging.py 与 gecko/core/telemetry.py：
  - 统一使用同一组 ContextVar（trace_id_var、span_id_var、extra_context_var），确保日志和 OTEL trace 共享相同的 TraceId/SpanId。
  - 修复少量日志消息与 ImportWarning 文本中的小拼写问题。

其他稳定性修复

DI 容器线程安全
- gecko/core/container.py：
  - 使用 RLock 保护依赖注册和解析流程，修复多线程环境下潜在的状态竞争。
记忆系统执行器关闭
- gecko/core/memory/__init__.py：
  - 确保 shutdown_token_executor 对外可见，避免在进程结束前遗留线程池或任务。

Breaking Changes / 兼容性变更

注意：0.4.0 版本在设计上尽量保持向后兼容，未主动引入显式的 API 破坏性调整。
下面列出的是潜在行为变更，可能会在极少数场景中影响已有系统行为。

Telemetry 自动初始化行为
- get_telemetry() 现在会在首次调用时自动创建并初始化默认 GeckoTelemetry 实例。
- 如果已有代码在自定义 Telemetry 之前调用了 get_telemetry()，可能会导致实际使用的是默认配置。推荐做法：
  - 在应用启动阶段显式调用 configure_telemetry(...) 设置自定义配置。
结构化解析策略调整
- StructureEngine 现在优先从 ToolCall 中解析结构化数据，其次才从文本 JSON 中解析，最后才通过 LLM 自愈修复。
- 如果上层逻辑依赖于“始终从纯文本中解析”这一旧行为，结果可能略有差异（但通常是更合理的解析路径）。
Workflow 并行与上下文合并行为
- 引入 COW + Diff Merge 的上下文管理策略后，多个并行节点对上下文的写入冲突将按“最后写入优先”规则处理。
- 如果之前依赖于共享可变对象的“非确定性行为”，现在可能会变得更稳定和可预测。

总体而言：未发现 API 层面的硬性 Breaking Change。若在升级 0.4.0 后遇到行为差异，建议重点检查：

是否依赖旧的 Telemetry 初始化方式；

是否依赖旧的结构化输出解析路径；

是否在 Workflow 中存在对并行写共享状态的特殊假设。

[0.3.1]

Summary / 概述

0.3.1 是在 0.3.0 基础上的小版本维护更新：
- 对部分核心模块（Workflow Models、Memory、Storage 等）做了工程化整理；
- 同步文档与版本元数据（gecko/version.py 中更新 __version__ 等）；
- 为后续 0.4.0 的 Telemetry / Workflow / Memory 重构铺路。

该版本未引入已知的 Breaking Changes。

Notes

从 0.3.1 → 0.4.0 的升级建议：
1. 在应用启动阶段显式调用 configure_telemetry()，而不是依赖默认自动初始化。
2. 如有自定义 Workflow 或 Team 执行逻辑，建议补充集成测试，验证在并行执行、Next 跳转和断点恢复场景下行为符合预期。
3. 如对结构化输出高度依赖，建议开启日志，观察 StructureEngine 的解析与修复过程，评估新策略的效果。

Assets 2

01 Dec 15:52

xuemzhan

v0.3.1

3cfdb88

v0.3.1

Full Changelog: v0.2.0...v0.3.1

Gecko v0.3.1 变更日志 (Changelog)

🚨 重大变更 (Breaking Changes)

Workflow 架构重构与状态持久化变更
- 变更：Workflow 模块从单文件拆分为 engine, graph, executor, persistence, models 等子模块。
- 影响：虽然对外 API 保持了大部分兼容，但在持久化存储中的 Context 数据结构发生了变化（增加了 next_pointer，移除了冗余的 executions 轨迹数据以“瘦身”）。旧版本的 Session 数据可能需要迁移才能在 v0.3.1 中恢复。
- 输入处理：移除了 Team 和 Workflow 中针对字典输入的“魔法解包”（Magic Unpacking/Extraction）。数据现在会原样传递给下游节点，不再自动提取 content 字段，以支持更复杂的结构化数据流转。
依赖项变更
- 新增核心依赖：opentelemetry-api, opentelemetry-sdk (遥测), filelock (跨进程锁)。
- 建议依赖：structlog (结构化日志)。

✨ 新特性 (New Features)

1. 工作流引擎增强 (Workflow Engine 2.0)

断点恢复 (Resume Capability)：
- 新增 workflow.resume(session_id) 接口。
- 引入 next_pointer 机制，支持在 Next 指令跳转后、目标节点执行前发生崩溃的场景下，精确恢复执行路径和输入参数。
两阶段提交 (Two-Phase Checkpoint)：
- 引入 Pre-Commit (状态置为 RUNNING) 和 Post-Commit (状态置为 SUCCESS/FAILED) 机制。确保即使节点执行过程中进程崩溃，重启后也能准确定位失败节点。
持久化策略 (Checkpoint Strategy)：
- 新增 CheckpointStrategy 枚举 (ALWAYS, FINAL, MANUAL)，允许开发者在数据安全性和 I/O 性能之间做平衡。
上下文瘦身 (Context Slimming)：
- 在持久化时自动剥离 executions (轨迹) 和过早的 history，防止随着对话轮数增加导致数据库 I/O 爆炸。

2. 多智能体并行 (Team Improvements)

赛马模式 (Race Strategy)：
- 新增 ExecutionStrategy.RACE。多个 Agent 并行执行，取最快返回的成功结果，并自动取消其他慢速任务（降低延迟）。
输入分片 (Input Sharding)：
- 新增 input_mapper 参数，支持将大任务切分后分发给不同的 Agent 处理（Map-Reduce 模式基础）。

3. 可观测性体系 (Observability)

OpenTelemetry 集成：
- 新增 gecko.core.telemetry 模块，支持完整的 Trace 和 Span 追踪。
- 自动注入 trace_id 和 span_id 到日志中。
指标监控 (Metrics)：
- 新增 gecko.core.metrics，提供 Counter, Gauge, Histogram，用于监控 Token 消耗、延迟和错误率。

4. 记忆模块优化 (Memory 2.0)

异步计算与防抖：
- TokenMemory 新增全局线程池 (_executor)，将 CPU 密集型的 Token 计数任务卸载到子线程，避免阻塞 Async Event Loop。
- SummaryTokenMemory 新增 background_update (后台更新) 和 min_update_interval (防抖)，大幅降低长上下文场景下的首字延迟。

5. 存储层增强 (Storage)

SQLite 高并发优化：
- 引入 ThreadOffloadMixin，将所有同步 SQL 操作卸载到线程池。
- 引入 AtomicWriteMixin 配合 FileLock，实现进程级互斥锁，彻底解决多 Worker 下 SQLite database is locked 问题。
- 开启 WAL (Write-Ahead Logging) 模式提升并发读写性能。
TTL 支持：
- Session 和 RedisStorage/SQLiteStorage 原生支持 TTL (Time-To-Live) 和自动过期清理。

6. 安全与防护 (Guardrails)

输入清洗：
- 新增 gecko.plugins.guardrails，提供 Prompt Injection 检测（如 "Ignore previous instructions"）和 PII 敏感信息过滤中间件。

🛠 改进与优化 (Improvements)

模型层 (LiteLLM Driver)：
- Tokenizer 预加载：优化了 Tiktoken 的加载逻辑，支持更多模型别名映射，避免推理热路径上的 IO 开销。
- Pydantic 兼容性：重写了 _sanitize_response，通过 LiteLLMAdapter 彻底解决 LiteLLM 返回对象与 Pydantic v2 序列化的冲突问题。
- Token 计数回退：实现了 Tiktoken -> LiteLLM -> 字符估算的三级回退策略，增强健壮性。
结构化输出 (Structure Engine)：
- 新增多种 JSON 提取策略（Markdown 代码块提取、暴力括号匹配、自动纠错）。
- 支持从 Tool Calls 中直接提取结构化数据，优先于文本解析。
工具箱 (ToolBox)：
- JSON 容错：当 LLM 生成的 JSON 参数格式错误时，不再直接抛出异常，而是将错误信息封装后返回给 LLM，引导其自我修正（Self-Correction）。
- 线程安全统计：工具调用统计增加锁保护。
CLI：
- 新增 gecko.cli 模块，提供 gecko chat 等命令行工具。

🐛 修复 (Bug Fixes)

ReAct 死循环熔断：修复了在流式输出模式下，死循环检测逻辑未正确触发或反馈给用户的问题。现在会注入 "System Alert" 并强制中断。
Event Loop 阻塞：修复了在 Async 流程中调用同步库（如 sqlite3, tiktoken）导致 Event Loop 阻塞的问题。
LiteLLM 资源泄漏：增加了 gecko.utils.cleanup，利用 atexit 确保在进程退出时关闭 LiteLLM 的全局 HTTP session，消除 ResourceWarning。
不可序列化对象崩溃：修复了 Context 中包含 Lock 或 Socket 等对象导致持久化崩溃的问题。现在会自动将其替换为占位符标记。

📊 架构对比图解

v0.2 架构（单体式）

graph TD
    Agent --> ReActEngine
    ReActEngine --> Workflow(Monolithic)
    Workflow --> Memory(Sync Token Count)
    Memory --> Storage(Direct IO)

v0.3.1 架构（分层与异步优化）

graph TD
    Agent --> ReActEngine
    ReActEngine --> Workflow(Modular)
    
    subgraph Workflow Engine
        Graph[Topology Graph]
        Executor[Smart Executor]
        Persistence[Async Persistence]
    end
    
    Workflow --> Graph
    Workflow --> Executor
    Workflow --> Persistence
    
    Persistence -- Offload --> ThreadPool
    Memory -- Offload --> ThreadPool
    
    subgraph Observability
        OTEL[OpenTelemetry]
        Metrics
    end
    
    Agent -.-> OTEL

📝 升级建议

对于从 v0.2 升级到 v0.3.1 的用户：

检查持久化数据：由于 Context 结构变化，建议在升级前备份旧的 Session 数据，或清空旧 Session。
安装新依赖：运行 pip install filelock opentelemetry-api opentelemetry-sdk。
配置调整：如果在生产环境使用 SQLite，请确保文件系统支持文件锁（NFS 环境需谨慎）。
代码调整：如果之前依赖了 Workflow 的内部属性（如 _nodes），请改用新的公开 API。确保 Team 的输入数据结构明确，不再依赖隐式解包。

Assets 2

27 Nov 01:49

xuemzhan

v0.2.0

13bb251

v0.2.0

Full Changelog: v0.2-beta...v0.2.0

🎯 Overview

This release focuses on stability, robustness, and production-readiness improvements across the entire Gecko framework, with 12 bug fixes and 3 major refactoring efforts to address critical stability issues.

🐛 Bug Fixes (12 Total)

Compose Module

Typo Fix: Corrected field description in Next.input
State Recovery: Deferred next_pointer cleanup until first step succeeds to prevent premature state loss
Error Handling: Enhanced exception handling in task group operations

Core Module

Streaming UX: Added user notifications when streaming loop exits, eliminating "silent failures"
Concurrency: Implemented lazy initialization with asyncio.Lock for SummaryTokenMemory to prevent race conditions
Auto-save: Added debounce mechanism to Session auto-save to reduce I/O overhead
Thread Safety: Ensured thread-safe iteration in ToolBox stats collection
JSON Safety: Added length limits to JSON extraction in structured outputs
Handler Deduplication: Used id() for robust event handler deduplication

Plugins Module

Storage Registration: Added missing @register_storage decorator to SQLiteStorage
Tokenizer Loading: Improved preloading logic for non-OpenAI model tokenizers
Private Attributes: Used Pydantic PrivateAttr for RetrievalTool to prevent serialization issues

🔧 Major Improvements

1. Workflow Engine Stability

Two-Phase Checkpoint System: Implemented pre-commit checkpoints to ensure execution idempotency
Dynamic Jump Persistence: Added next_pointer to WorkflowContext for explicit dynamic jump tracking
Atomic State Saves: Immediate persistence triggered upon receiving Next instructions
Smart Resume Logic: Prioritizes next_pointer over static graph inference for correct crash recovery

2. ReAct Engine Robustness

Structured Output Safety:
- Validates tool calls match expected targets when using response_model
- Supports parallel tool call scanning
- Raises descriptive StructureParseError instead of crashing on validation failures
Infinite Loop Handling: Injects "System Alert" messages for better LLM context during auto-retry
Streaming Refactor: Converted recursive streaming loop to iterative while loop, eliminating RecursionError risks
Event Bus Integration: Added tool_execution_start/end events to eliminate streaming "silence"

3. Session Management Improvements

Race Condition Fix: Implemented synchronous snapshot mechanism - state is deep-copied while holding lock before async I/O
New API: Added get_info() method for statistical observability
Concurrency Safety: Prevents data inconsistency under high-concurrency scenarios

📚 New Examples & Demos

event_bus_stream_demo.py: Showcases new streaming UX improvements
workflow_next_resume_demo.py: Demonstrates crash recovery during Next instruction jumps
rag_pipeline_demo.py: Memory-efficient streaming RAG ingestion example

✅ Testing

Python Compatibility: Tested on Python 3.10, 3.11, 3.12
Test Fixes:
- Resolved pytest fixture scope errors
- Updated workflow test assertions for new persistence behavior
- Fixed broken imports in examples
- Added comprehensive tests for structured outputs and concurrent operations

🔄 Breaking Changes

None - This release maintains full backward compatibility.

📦 Migration Required

None - Upgrade seamlessly from v0.2.0-beta.

🎓 Key Technical Highlights

Architecture: Decoupled litellm dependency with lazy imports
Fault Tolerance: Improved JSON parsing with LLM self-correction feedback loops
Observability: Enhanced error messages and system alerts throughout the framework

Assets 2

23 Nov 01:21

xuemzhan

v0.2-beta

0295074

Gecko v0.2-beta

Full Changelog: https://github.com/xuemzhan/gecko/commits/v0.2-beta

Assets 2

Releases: xuemzhan/gecko

v0.4.0

Changelog

[0.4.0] - 2025-12-09

Features / 新特性

Observability & Telemetry

Memory / 记忆系统

Workflow / 组合与工作流

Structure / 结构化输出

Resilience / 系统韧性

Models / Provider 适配

Bugfixes / 缺陷修复

Concurrency / 并发安全

Engine / Workflow 行为修复

Logging & Tracing

其他稳定性修复

Breaking Changes / 兼容性变更

[0.3.1]

Summary / 概述

Notes

Uh oh!

v0.3.1

Gecko v0.3.1 变更日志 (Changelog)

🚨 重大变更 (Breaking Changes)

✨ 新特性 (New Features)

1. 工作流引擎增强 (Workflow Engine 2.0)

2. 多智能体并行 (Team Improvements)

3. 可观测性体系 (Observability)

4. 记忆模块优化 (Memory 2.0)

5. 存储层增强 (Storage)

6. 安全与防护 (Guardrails)

🛠 改进与优化 (Improvements)

🐛 修复 (Bug Fixes)

📊 架构对比图解

v0.2 架构（单体式）

v0.3.1 架构（分层与异步优化）

📝 升级建议

Uh oh!

v0.2.0

🎯 Overview

🐛 Bug Fixes (12 Total)

Compose Module

Core Module

Plugins Module

🔧 Major Improvements

1. Workflow Engine Stability

2. ReAct Engine Robustness

3. Session Management Improvements

📚 New Examples & Demos

✅ Testing

🔄 Breaking Changes

📦 Migration Required

🎓 Key Technical Highlights

Uh oh!

Gecko v0.2-beta

Uh oh!