@limo-labs/deity 0.1.0-alpha.2 → 0.1.1-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,184 @@
+# Changelog
+
+All notable changes to Deity 3.0 will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0-alpha.3] - 2026-02-17
+
+### Added
+
+#### Workflow Runtime Export (Task #1 - P0 Critical)
+- **Exported Workflow API** - `defineWorkflow`, `runWorkflow`, `WorkflowBuilder` now available at top level
+- **Exported Execution Primitives** - `Step`, `Sequence`, `Parallel`, `Conditional`, `Loop` for composable workflows
+- **Exported Core Types** - `AgentComponent`, `ExecutionContext`, `Tool`, `Message`, `LLMAdapter` as first-class exports
+- **Module Organization** - 8 organized namespace modules: `workflow`, `execution`, `primitives`, `guidance`, `adapters`, `state`, `tools`, `helpers`
+- **Flat Imports** - Convenience imports for commonly used APIs
+- **Namespace Imports** - Alternative `import * as deity from '@limo-labs/deity-3.0'` style supported
+
+#### Tool Error Handling (Task #2 - P0 Critical)
+- **Tool Result Type** - New `ToolResult<T>` interface for returning success/error instead of throwing
+- **ActionConfig** - New configuration for `DefaultAction` with `onError` and `validateBeforeExecute` options
+- **Auto-Retry on Tool Errors** - New `retryOnToolError` option in component retry config
+- **LLM Error Feedback** - New `feedbackErrorToLLM` option to send tool errors back to LLM for correction
+- **Pre-Execution Validation** - Tools now validate input schema before execution
+- **Graceful Error Handling** - Tools can return errors instead of throwing, enabling automatic recovery
+
+#### Documentation (Task #3 - P1 High)
+- **Updated README.md** - Complete rewrite with working examples using actual exported API
+- **API Guide** - New `doc/api-guide.md` with side-by-side API comparisons
+- **Migration Guide** - New `doc/migration.md` with migration paths from 2.x and manual implementations
+- **Stability Matrix** - Clear indication of stable vs experimental modules
+- **When to Use What** - Decision trees and comparison tables for choosing the right API
+
+### Changed
+
+#### API Organization
+- **Renamed Pipeline → Workflow** - Terminology update throughout codebase
+- **Module Exports** - Organized exports into 8 distinct modules instead of flat structure
+- **Import Patterns** - Support both flat imports and namespace imports
+
+#### Tool System
+- **Tool Interface** - Tools can now return `ToolResult<T>` or throw (both supported)
+- **Error Handling** - Changed from "throw only" to "return or throw" model
+- **Validation** - Added pre-execution validation layer
+
+#### Retry System
+- **Default Behavior** - `feedbackOnError` now defaults to `true`
+- **Tool Retry** - Added `retryOnToolError` option (defaults to `true`)
+- **Error Feedback** - Added `feedbackErrorToLLM` option (defaults to `true`)
+
+### Fixed
+- **API Documentation Mismatch** - README examples now use actually exported APIs
+- **Tool Validation Crashes** - Tool parameter errors no longer crash entire workflow
+- **Missing Exports** - Workflow runtime and execution primitives now properly exported
+- **Type Safety** - Core types now exported at top level to avoid conflicts
+
+### Documentation
+- **README.md** - Complete rewrite with accurate API examples
+- **doc/api-guide.md** - New comprehensive API comparison guide
+- **doc/migration.md** - New migration guide for 2.x and manual implementations
+- **CHANGELOG.md** - This file
+
+---
+
+## [0.1.0-alpha.2] - 2026-02-16
+
+### Added
+- Initial workflow system implementation
+- Execution primitives (Step, Sequence, Parallel, Conditional, Loop)
+- Biological primitives (Perception, Action, Memory, Feedback, Communication)
+- Adaptive tool calling system
+- State management with event sourcing
+- Validation and guidance system
+- OpenAI and VS Code adapters
+
+### Known Issues
+- Workflow API not exported (fixed in 0.1.0-alpha.3)
+- Tool error handling crashes on validation failure (fixed in 0.1.0-alpha.3)
+- Documentation examples use non-exported APIs (fixed in 0.1.0-alpha.3)
+
+---
+
+## [0.1.0-alpha.1] - 2026-02-15
+
+### Added
+- Initial alpha release
+- Core type system
+- Basic primitives implementation
+- LLM adapter interface
+
+---
+
+## Version History
+
+| Version | Date | Key Changes |
+|---------|------|-------------|
+| 0.1.0-alpha.3 | 2026-02-17 | Workflow runtime export, tool error handling, documentation update |
+| 0.1.0-alpha.2 | 2026-02-16 | Workflow system, execution primitives, adaptive tools |
+| 0.1.0-alpha.1 | 2026-02-15 | Initial alpha release |
+
+---
+
+## Upgrade Guide
+
+### From 0.1.0-alpha.2 to 0.1.0-alpha.3
+
+**No breaking changes** - This is a feature addition release.
+
+#### New Features to Adopt
+
+1. **Use exported Workflow API:**
+
+```typescript
+// Now available!
+import {
+  defineWorkflow,
+  runWorkflow,
+  type AgentComponent
+} from '@limo-labs/deity-3.0';
+```
+
+2. **Enable tool error handling:**
+
+```typescript
+const Component: AgentComponent = {
+  // ... other fields ...
+  retry: {
+    maxAttempts: 3,
+    feedbackOnError: true,      // ✅ Default true in alpha.3
+    retryOnToolError: true,     // ✅ NEW: Retry on tool errors
+    feedbackErrorToLLM: true    // ✅ NEW: Send errors to LLM
+  }
+};
+```
+
+3. **Use execution primitives:**
+
+```typescript
+import { Sequence, Parallel, Loop, Step } from '@limo-labs/deity-3.0/execution';
+
+const workflow = defineWorkflow({
+  stages: Sequence([
+    Step(Component1),
+    Parallel([Step(Component2), Step(Component3)]),
+    Step(Component4)
+  ])
+});
+```
+
+---
+
+## Roadmap
+
+### v0.1.0-beta.1 (Planned)
+- [ ] Streaming support for LLM responses
+- [ ] Progressive guidance integration
+- [ ] Loop iteration context
+- [ ] ConversationManager helper
+- [ ] Memory system integration with workflow runtime
+
+### v0.1.0 (Planned)
+- [ ] Full test coverage (>90%)
+- [ ] Performance benchmarks
+- [ ] Production examples
+- [ ] Complete API documentation
+
+### v0.2.0 (Planned)
+- [ ] Distributed execution
+- [ ] Advanced state management
+- [ ] Plugin system
+- [ ] UI dashboard
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines.
+
+---
+
+## License
+
+MIT © Limo Labs