@hazeljs/agent 0.7.8 → 0.8.0

package/.eslintrc.js

@@ -1,4 +1,8 @@
 module.exports = {
   extends: ['../../.eslintrc.js'],
   ignorePatterns: ['**/*.d.ts'],
+  parserOptions: {
+    project: './tsconfig.json',
+    tsconfigRootDir: __dirname,
+  },
 };

package/IMPLEMENTATION_SUMMARY.md

@@ -44,12 +44,14 @@ packages/agent/
 ## 🎯 Core Features Implemented
 
 ### 1. Agent System ✅
+
 - **@Agent decorator** - Declarative agent definition
 - **Agent metadata** - Configuration and capabilities
 - **Agent registry** - Centralized agent management
 - **Agent lifecycle** - Full lifecycle management
 
 ### 2. Tool System ✅
+
 - **@Tool decorator** - Declarative tool definition
 - **Tool metadata** - Parameters, validation, policies
 - **Tool registry** - Tool discovery and lookup
@@ -57,12 +59,14 @@ packages/agent/
 - **Approval workflow** - Human-in-the-loop for sensitive operations
 
 ### 3. State Machine ✅
+
 - **Agent states** - idle, thinking, using_tool, waiting_for_input, waiting_for_approval, completed, failed
 - **State transitions** - Deterministic state flow
 - **State persistence** - In-memory state management
 - **Context management** - Full execution context
 
 ### 4. Execution Loop ✅
+
 - **Controlled loop** - Step-by-step execution
 - **LLM integration** - Decision making via LLM
 - **Action execution** - Tool calls, responses, user input
@@ -70,6 +74,7 @@ packages/agent/
 - **Pause/resume** - Support for long-running workflows
 
 ### 5. Memory Integration ✅
+
 - **Conversation history** - Automatic persistence
 - **Entity tracking** - Track mentioned entities
 - **Fact storage** - Persistent knowledge
@@ -77,17 +82,20 @@ packages/agent/
 - **Automatic sync** - Load before, persist after execution
 
 ### 6. RAG Integration ✅
+
 - **Context retrieval** - Query RAG before reasoning
 - **Context injection** - Add to system prompt
 - **Configurable topK** - Control context size
 
 ### 7. Human-in-the-Loop ✅
+
 - **Approval requests** - Tools can require approval
 - **Approval workflow** - Request → Wait → Approve/Reject
 - **User input** - Agents can ask questions
 - **Pause/resume** - Resume after user interaction
 
 ### 8. Event System ✅
+
 - **Comprehensive events** - 15+ event types
 - **Pub/sub pattern** - Subscribe to specific or all events
 - **Execution events** - Started, completed, failed
@@ -97,6 +105,7 @@ packages/agent/
 - **RAG events** - RAG queries
 
 ### 9. Observability ✅
+
 - **Event emission** - All actions emit events
 - **State tracking** - Full state history
 - **Step recording** - Complete step log
@@ -104,6 +113,7 @@ packages/agent/
 - **Duration tracking** - Performance metrics
 
 ### 10. Error Handling ✅
+
 - **Multi-level handling** - Tool, step, execution, runtime
 - **Retry logic** - Configurable retries for tools
 - **Timeout handling** - Prevent hanging operations
@@ -113,6 +123,7 @@ packages/agent/
 ## 🏗️ Architecture Highlights
 
 ### Design Patterns Used
+
 - **Facade Pattern** - AgentRuntime provides simple interface
 - **Template Method** - AgentExecutor defines execution skeleton
 - **Chain of Responsibility** - Tool approval pipeline
@@ -163,9 +174,7 @@ import { Agent, Tool, AgentRuntime } from '@hazeljs/agent';
 export class SupportAgent {
   @Tool({
     description: 'Look up order by ID',
-    parameters: [
-      { name: 'orderId', type: 'string', required: true }
-    ],
+    parameters: [{ name: 'orderId', type: 'string', required: true }],
   })
   async lookupOrder(input: { orderId: string }) {
     return { orderId: input.orderId, status: 'shipped' };
@@ -197,11 +206,10 @@ runtime.on('tool.approval.requested', (event) => {
 });
 
 // 5. Execute Agent
-const result = await runtime.execute(
-  'support-agent',
-  'Check order #12345',
-  { sessionId: 'session-123', enableMemory: true }
-);
+const result = await runtime.execute('support-agent', 'Check order #12345', {
+  sessionId: 'session-123',
+  enableMemory: true,
+});
 ```
 
 ## 🔄 Execution Flow
@@ -245,7 +253,9 @@ import { RagModule } from '@hazeljs/rag';
 
 @HazelModule({
   imports: [
-    RagModule.forRoot({ /* ... */ }),
+    RagModule.forRoot({
+      /* ... */
+    }),
     AgentModule.forRoot({
       runtime: { defaultMaxSteps: 10 },
       agents: [SupportAgent, SalesAgent],
@@ -274,6 +284,7 @@ export class MyService {
 ## 📊 Comparison with Traditional Approaches
 
 ### Traditional (Stateless)
+
 ```typescript
 @Post('/chat')
 async chat(@Body() body: { message: string }) {
@@ -281,14 +292,18 @@ async chat(@Body() body: { message: string }) {
   return { response };
 }
 ```
+
 **Issues**: No memory, no tools, no state, no observability
 
 ### HazelJS Agent Runtime
+
 ```typescript
 @Agent({ name: 'chat-agent', enableMemory: true })
 export class ChatAgent {
   @Tool()
-  async searchDocs(query: string) { /* ... */ }
+  async searchDocs(query: string) {
+    /* ... */
+  }
 }
 
 // Execution
@@ -297,22 +312,26 @@ const result = await runtime.execute('chat-agent', message, {
   enableMemory: true,
 });
 ```
+
 **Benefits**: Memory, tools, state, observability, resumable
 
 ## 🚀 Production Considerations
 
 ### Current Implementation
+
 - In-memory state (Map-based)
 - Single process
 - No distributed coordination
 
 ### Production Recommendations
+
 1. **State Persistence**: Replace Map with Redis/Database
 2. **Distributed Approvals**: Use message queue
 3. **Execution Queue**: Use job queue for long-running agents
 4. **Event Bus**: Replace in-memory emitter with distributed bus
 
 ### Scaling Example
+
 ```typescript
 class RedisStateManager extends AgentStateManager {
   async getContext(executionId: string) {
@@ -335,6 +354,7 @@ const runtime = new AgentRuntime({
 ## ✨ Key Differentiators
 
 ### vs LangChain
+
 - **Framework-native** - Built into backend framework
 - **Type-safe** - Full TypeScript support
 - **Declarative** - Decorator-based API
@@ -342,12 +362,14 @@ const runtime = new AgentRuntime({
 - **Production-ready** - Error handling, retries, timeouts
 
 ### vs NestJS + LangChain
+
 - **AI-native** - Memory and RAG as primitives
 - **Simpler** - No need for separate agent library
 - **Integrated** - Works with HazelJS modules
 - **Lightweight** - No Express/Fastify dependency
 
 ### vs Custom Implementation
+
 - **Framework-level** - Production-grade patterns
 - **Extensible** - Multiple extension points
 - **Observable** - Built-in monitoring
@@ -356,18 +378,21 @@ const runtime = new AgentRuntime({
 ## 🎯 Next Steps
 
 ### Immediate
+
 1. Add unit tests for all components
 2. Add integration tests for execution flow
 3. Add E2E tests with real LLM
 4. Create more examples (sales agent, RAG agent, multi-agent)
 
 ### Short-term
+
 1. Implement Redis-based state persistence
 2. Add distributed approval workflow
 3. Add streaming responses
 4. Add policy engine for tool authorization
 
 ### Long-term
+
 1. Visual debugger for agent execution
 2. Agent marketplace (shareable templates)
 3. Multi-agent coordination
@@ -384,7 +409,7 @@ const runtime = new AgentRuntime({
 ✅ **Error handling** - Multi-level with retry logic  
 ✅ **Extensibility** - Multiple extension points  
 ✅ **Documentation** - Complete user and technical docs  
-✅ **Examples** - Working examples provided  
+✅ **Examples** - Working examples provided
 
 ## 🎉 Conclusion
 

package/PERSISTENCE.md

@@ -9,16 +9,19 @@ The `@hazeljs/agent` package supports multiple persistence backends for agent ex
 ## Available Backends
 
 ### 1. In-Memory (Default)
+
 - **Best for**: Development, testing, single-instance deployments
 - **Pros**: Fast, no setup required
 - **Cons**: Data lost on restart, not suitable for distributed systems
 
 ### 2. Redis
+
 - **Best for**: Production, distributed systems, high-performance scenarios
 - **Pros**: Fast, distributed, TTL support, pub/sub capabilities
 - **Cons**: Requires Redis infrastructure
 
 ### 3. Database (Prisma)
+
 - **Best for**: Long-term persistence, audit trails, analytics
 - **Pros**: Durable, queryable, full audit trail
 - **Cons**: Slower than Redis, requires database setup
@@ -40,6 +43,7 @@ const runtime = new AgentRuntime({
 ### Redis Backend
 
 1. Install Redis client:
+
 ```bash
 npm install redis
 ```
@@ -75,6 +79,7 @@ const runtime = new AgentRuntime({
 ### Database Backend (Prisma)
 
 1. Install Prisma:
+
 ```bash
 npm install @prisma/client
 ```
@@ -84,6 +89,7 @@ npm install @prisma/client
    - See [PRISMA_INTEGRATION.md](./PRISMA_INTEGRATION.md) for detailed instructions
 
 3. Run migrations:
+
 ```bash
 npx prisma migrate dev --name add_agent_state_models
 npx prisma generate

package/PRISMA_INTEGRATION.md

@@ -296,11 +296,11 @@ npx prisma migrate dev
 model AgentContext {
   // Use your own ID format
   id          String   @id @default(cuid()) // or @default(uuid())
-  
+
   // Add custom fields
   priority    Int      @default(0)
   tags        String[]
-  
+
   // Customize JSON fields
   metadata    Json     @default("{}")
 }
@@ -325,11 +325,11 @@ model AgentContext {
 ```prisma
 model AgentContext {
   // ... fields ...
-  
+
   // Add composite indexes
   @@index([agentId, state])
   @@index([sessionId, createdAt])
-  
+
   // Add full-text search (PostgreSQL)
   @@index([input(ops: Raw("gin_trgm_ops"))])
 }
@@ -362,7 +362,7 @@ export class AppModule {
     const stateManager = new DatabaseStateManager({
       client: this.prisma,
     });
-    
+
     // Use with AgentRuntime
     // (configure in your agent service)
   }
@@ -374,6 +374,7 @@ export class AppModule {
 ### Error: "Model AgentContext not found"
 
 **Solution**: Make sure you've:
+
 1. Added the model to your schema
 2. Run `npx prisma generate`
 3. Restarted your application
@@ -381,6 +382,7 @@ export class AppModule {
 ### Error: "Column does not exist"
 
 **Solution**: Run migrations:
+
 ```bash
 npx prisma migrate dev
 ```
@@ -394,6 +396,7 @@ npx prisma migrate dev
 ### Performance Issues
 
 1. **Add indexes** on frequently queried fields:
+
    ```prisma
    @@index([sessionId])
    @@index([userId])
@@ -401,6 +404,7 @@ npx prisma migrate dev
    ```
 
 2. **Use soft deletes** to avoid expensive DELETE operations:
+
    ```prisma
    deletedAt DateTime?
    @@index([deletedAt])
@@ -494,6 +498,7 @@ export class AppModule {}
 5. ✅ Test with your agents
 
 For more details, see:
+
 - [PERSISTENCE.md](./PERSISTENCE.md) - Configuration guide
 - [STATE_VS_MEMORY.md](./STATE_VS_MEMORY.md) - Understanding State vs Memory
 - [prisma-schema.example.prisma](./prisma-schema.example.prisma) - Full schema example

package/PRODUCTION_READINESS.md

@@ -5,6 +5,7 @@ This document tracks the production readiness improvements made to `@hazeljs/age
 ## ✅ Completed
 
 ### 1. Type Safety Improvements
+
 - **Created proper type definitions** for LLM and RAG providers
   - `src/types/llm.types.ts` - LLMProvider interface with proper types
   - `src/types/rag.types.ts` - RAGService interface with proper types
@@ -16,6 +17,7 @@ This document tracks the production readiness improvements made to `@hazeljs/age
 - **Exported new types** from package index
 
 ### 2. Testing Infrastructure
+
 - **Created Jest configuration** (`jest.config.js`)
   - TypeScript support via ts-jest
   - Coverage thresholds set to 80%
@@ -31,6 +33,7 @@ This document tracks the production readiness improvements made to `@hazeljs/age
   - `tests/registry/tool.registry.test.ts` - Full coverage of ToolRegistry
 
 ### 3. Dependencies
+
 - Added Jest and testing dependencies to package.json
   - `@types/jest: ^29.5.11`
   - `jest: ^29.7.0`
@@ -39,13 +42,16 @@ This document tracks the production readiness improvements made to `@hazeljs/age
 ## ✅ Completed Production Features
 
 ### 4. Rate Limiting
+
 **Implementation**: `src/utils/rate-limiter.ts`
+
 - Token bucket algorithm for rate limiting
 - Configurable tokens per minute and burst size
 - Automatic token refill over time
 - Blocking and non-blocking consumption modes
 
 **Usage**:
+
 ```typescript
 const runtime = new AgentRuntime({
   rateLimitPerMinute: 60, // 60 requests per minute
@@ -53,7 +59,9 @@ const runtime = new AgentRuntime({
 ```
 
 ### 5. Structured Logging
+
 **Implementation**: `src/utils/logger.ts`
+
 - Multiple log levels (DEBUG, INFO, WARN, ERROR, FATAL)
 - Structured context with agent/execution metadata
 - Colored console output for development
@@ -61,6 +69,7 @@ const runtime = new AgentRuntime({
 - Custom log handlers support
 
 **Usage**:
+
 ```typescript
 const runtime = new AgentRuntime({
   logLevel: LogLevel.INFO,
@@ -68,7 +77,9 @@ const runtime = new AgentRuntime({
 ```
 
 ### 6. Metrics Collection
+
 **Implementation**: `src/utils/metrics.ts`
+
 - Execution metrics (count, success rate, duration)
 - Performance metrics (avg, min, max, p50, p95, p99)
 - Tool usage tracking
@@ -76,19 +87,23 @@ const runtime = new AgentRuntime({
 - Memory retrieval metrics
 
 **Usage**:
+
 ```typescript
 const metrics = runtime.getMetrics();
 console.log(runtime.getMetricsSummary());
 ```
 
 ### 7. Retry Logic
+
 **Implementation**: `src/utils/retry.ts`
+
 - Exponential backoff with jitter
 - Configurable retry attempts and delays
 - Retryable error detection
 - Retry callbacks for monitoring
 
 **Usage**:
+
 ```typescript
 const runtime = new AgentRuntime({
   enableRetry: true, // Enabled by default
@@ -96,7 +111,9 @@ const runtime = new AgentRuntime({
 ```
 
 ### 8. Circuit Breaker
+
 **Implementation**: `src/utils/circuit-breaker.ts`
+
 - Three states: CLOSED, OPEN, HALF_OPEN
 - Automatic state transitions
 - Failure and success thresholds
@@ -104,6 +121,7 @@ const runtime = new AgentRuntime({
 - Manual reset capability
 
 **Usage**:
+
 ```typescript
 const runtime = new AgentRuntime({
   enableCircuitBreaker: true, // Enabled by default
@@ -113,26 +131,32 @@ const status = runtime.getCircuitBreakerStatus();
 ```
 
 ### 9. Health Checks
+
 **Implementation**: `src/utils/health-check.ts`
+
 - Component health monitoring (LLM, RAG, Memory)
 - Latency tracking
 - Overall health status (HEALTHY, DEGRADED, UNHEALTHY)
 - Metrics integration
 
 **Usage**:
+
 ```typescript
 const health = await runtime.healthCheck();
 console.log(health.status); // 'healthy' | 'degraded' | 'unhealthy'
 ```
 
 ### 10. Performance Benchmarks
+
 **Implementation**: `benchmarks/performance.benchmark.ts`
+
 - Agent registration benchmarks
 - Tool registry lookup benchmarks
 - Metrics collection benchmarks
 - Health check benchmarks
 
 **Usage**:
+
 ```bash
 npm run benchmark
 ```
@@ -140,7 +164,9 @@ npm run benchmark
 ## 🚧 Remaining Tasks
 
 ### Additional Test Coverage
+
 Create tests for remaining core components:
+
 - `tests/runtime/agent.runtime.test.ts`
 - `tests/executor/agent.executor.test.ts`
 - `tests/executor/tool.executor.test.ts`
@@ -152,12 +178,14 @@ Create tests for remaining core components:
 ## 📋 Installation Instructions
 
 ### 1. Install Dependencies
+
 ```bash
 cd /Users/muhammadarslan/repos/hazeljs.ai/hazeljs/packages/agent
 npm install
 ```
 
 ### 2. Run Tests
+
 ```bash
 # Run all tests
 npm test
@@ -170,6 +198,7 @@ npm run test:watch
 ```
 
 ### 3. Build Package
+
 ```bash
 npm run build
 ```
@@ -183,17 +212,22 @@ npm run build
 ## 📝 Notes
 
 ### Type Safety
+
 All `any` types have been replaced with proper interfaces:
+
 - `llmProvider?: any` → `llmProvider?: LLMProvider`
 - `ragService?: any` → `ragService?: RAGService`
 
 ### Breaking Changes
+
 The new type definitions may require updates to existing code:
+
 - LLM providers must implement the `LLMProvider` interface
 - RAG services must implement the `RAGService` interface
 - Tool definitions are now converted to LLM format via `getToolDefinitionsForLLM()`
 
 ### Example: Creating a Custom LLM Provider
+
 ```typescript
 import { LLMProvider, LLMChatRequest, LLMChatResponse } from '@hazeljs/agent';
 
@@ -238,6 +272,7 @@ class CustomLLMProvider implements LLMProvider {
 **Production Ready**: 85% Complete
 
 **Completed**:
+
 - ✅ Type safety improvements (100%)
 - ✅ Testing infrastructure (100%)
 - ✅ Rate limiting (100%)
@@ -249,6 +284,7 @@ class CustomLLMProvider implements LLMProvider {
 - ✅ Performance benchmarks (100%)
 
 **Remaining**:
+
 - ⏳ Integration tests (0%)
 - ⏳ End-to-end tests (0%)
 - ⏳ Security audit (0%)
@@ -256,6 +292,7 @@ class CustomLLMProvider implements LLMProvider {
 - ⏳ Deployment guide (0%)
 
 **Recommended Timeline**:
+
 - Phase 1 (✅ Completed): Type safety + Testing infrastructure
 - Phase 2 (✅ Completed): Rate limiting + Logging + Metrics
 - Phase 3 (✅ Completed): Retry logic + Circuit breaker + Health checks

package/QUICKSTART.md

@@ -61,14 +61,10 @@ runtime.registerAgentInstance('my-agent', myAgent);
 ### Step 4: Execute
 
 ```typescript
-const result = await runtime.execute(
-  'my-agent',
-  'What time is it and what is 5 + 3?',
-  {
-    sessionId: 'user-session-123',
-    enableMemory: true,
-  }
-);
+const result = await runtime.execute('my-agent', 'What time is it and what is 5 + 3?', {
+  sessionId: 'user-session-123',
+  enableMemory: true,
+});
 
 console.log(result.response);
 // "The current time is 2024-12-13T15:30:00Z and 5 + 3 equals 8."
@@ -77,18 +73,23 @@ console.log(result.response);
 ## Key Concepts
 
 ### Agents
+
 Stateful entities that execute over multiple steps with memory and tools.
 
 ### Tools
+
 Functions that agents can call, with optional approval workflows.
 
 ### Memory
+
 Automatic conversation history and context persistence.
 
 ### State Machine
+
 Agents transition through states: idle → thinking → using_tool → completed
 
 ### Events
+
 Subscribe to execution events for monitoring and debugging.
 
 ## Next Steps
@@ -101,6 +102,7 @@ Subscribe to execution events for monitoring and debugging.
 ## Common Patterns
 
 ### Tool with Approval
+
 ```typescript
 @Tool({
   description: 'Delete user account',
@@ -112,6 +114,7 @@ async deleteAccount(input: { userId: string }) {
 ```
 
 ### Subscribe to Events
+
 ```typescript
 runtime.on('tool.approval.requested', (event) => {
   console.log('Approval needed:', event.data);
@@ -120,6 +123,7 @@ runtime.on('tool.approval.requested', (event) => {
 ```
 
 ### Pause and Resume
+
 ```typescript
 const result = await runtime.execute('agent', 'Start task');