Skip to content

Commit 93c5fb1

Browse files
marcosf63marcosf63
committed
feat: add human-in-the-loop system and release v0.11.0
Part 5/5 - Infrastructure Layer completion Implements comprehensive human oversight for agent operations: Components: - ApprovalManager: Workflow approval system with multiple policies - Policies: ALWAYS, NEVER, COST_THRESHOLD, RISK_LEVEL, FIRST_TIME, CUSTOM - Auto-approval based on rules - Async approval with callbacks - Request expiration and timeout - Approval history and audit trail - Thread-safe implementation - InterventionManager: Real-time human intervention mechanisms - Intervention types: PAUSE, STOP, MODIFY, SKIP, CONTINUE, REDIRECT - Configurable intervention points by action type - Step-by-step execution mode - Global pause/resume controls - Real-time parameter modification - Intervention history tracking - FeedbackCollector: Comprehensive feedback collection and analysis - Feedback types: Rating (1-5), Thumbs, Comment, Correction, Bug report, Feature request - Rating aggregation and statistics - Thumbs up/down tracking with rates - Correction tracking for agent improvement - Acknowledgment system for feedback - Data export capabilities Features: - Thread-safe implementations - Async operations with callbacks - Flexible policy configuration - Comprehensive statistics - Integration-ready design Demo includes: 1. Approval workflows with multiple policies 2. Intervention mechanisms and step mode 3. Feedback collection (all types) 4. Integrated workflow (approval + intervention + feedback) 5. Async approval with callbacks Version bump: 0.10.1 → 0.11.0 - Updated pyproject.toml - Updated __init__.py with new version - Updated CHANGELOG.md with comprehensive release notes Layer 4 (Agentic Infrastructure) now 100% complete: ✅ Part 1/5: Monitoring (Metrics, Logger, Telemetry) ✅ Part 2/5: Resilience (Retry, Circuit Breaker, Fallback, Timeout) ✅ Part 3/5: Security (RBAC, Sandbox, Audit, Secrets) ✅ Part 4/5: Cost Control (Budget, Rate Limiter, Quota) ✅ Part 5/5: Human-in-the-Loop (Approval, Intervention, Feedback) Total: ~5500 lines of production-ready infrastructure code
1 parent 22512db commit 93c5fb1

8 files changed

Lines changed: 2336 additions & 4 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,208 @@ Todas as mudanças notáveis neste projeto serão documentadas neste arquivo.
55
O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.0/),
66
e este projeto adere ao [Semantic Versioning](https://semver.org/lang/pt-BR/).
77

8+
## [0.11.0] - 2025-01-11
9+
10+
### 🚀 Nova Feature: Layer 4 - Agentic Infrastructure
11+
12+
**Implementação completa da camada de infraestrutura para agentes production-ready**
13+
14+
Esta release implementa a **Layer 4** do framework Agentic AI, adicionando componentes essenciais para produção:
15+
16+
#### 📊 Part 1/5: Monitoring System
17+
18+
**Componentes:**
19+
- **AgentMetrics**: Sistema de métricas com suporte Prometheus
20+
- Contadores thread-safe para execuções, erros, tokens
21+
- Export em formato Prometheus
22+
- Tracking de custo e duração
23+
- Context manager para tracking automático
24+
25+
- **AgentLogger**: Sistema de logging estruturado
26+
- Formato JSON para ingestão em sistemas de observabilidade
27+
- Níveis configuráveis (DEBUG, INFO, WARNING, ERROR, CRITICAL)
28+
- Propagação de contexto entre operações
29+
- Suporte a file e console output
30+
31+
- **AgentTelemetry**: Sistema de rastreamento distribuído
32+
- Criação de traces e spans
33+
- Tracking de duração e status
34+
- Compatível com OpenTelemetry
35+
- Propagação de trace_id entre componentes
36+
37+
**Arquivos:**
38+
- `react_agent_framework/infrastructure/monitoring/metrics.py` (290 linhas)
39+
- `react_agent_framework/infrastructure/monitoring/logger.py` (248 linhas)
40+
- `react_agent_framework/infrastructure/monitoring/telemetry.py` (244 linhas)
41+
- `react_agent_framework/examples/infrastructure_monitoring_demo.py` (189 linhas)
42+
43+
#### 🛡️ Part 2/5: Resilience System
44+
45+
**Componentes:**
46+
- **RetryStrategy**: Sistema de retry automático
47+
- Estratégias: Fixed, Exponential, Linear backoff
48+
- Jitter para prevenir thundering herd
49+
- Max attempts e delay configuráveis
50+
- Filtro de exceções retryable
51+
52+
- **CircuitBreaker**: Proteção contra falhas em cascata
53+
- Estados: CLOSED, OPEN, HALF_OPEN
54+
- Transição automática baseada em threshold
55+
- Recovery timeout configurável
56+
- Métricas de falhas e sucessos
57+
58+
- **FallbackStrategy**: Estratégias de degradação graceful
59+
- Static fallback (valor fixo)
60+
- Function fallback (função alternativa)
61+
- Chain fallback (múltiplas alternativas)
62+
- Preservação de argumentos originais
63+
64+
- **TimeoutManager**: Gerenciamento de timeouts
65+
- Timeout configurável por operação
66+
- Thread-based timeout enforcement
67+
- Context manager para uso fácil
68+
- Cleanup automático de threads
69+
70+
**Arquivos:**
71+
- `react_agent_framework/infrastructure/resilience/retry.py` (252 linhas)
72+
- `react_agent_framework/infrastructure/resilience/circuit_breaker.py` (287 linhas)
73+
- `react_agent_framework/infrastructure/resilience/fallback.py` (220 linhas)
74+
- `react_agent_framework/infrastructure/resilience/timeout.py` (212 linhas)
75+
- `react_agent_framework/examples/infrastructure_resilience_demo.py` (259 linhas)
76+
77+
#### 🔒 Part 3/5: Security System
78+
79+
**Componentes:**
80+
- **RBACManager**: Role-Based Access Control
81+
- 20+ permissions predefinidas
82+
- Roles: user, developer, admin, auditor
83+
- Wildcard support (tool.*, file.*)
84+
- Permission inheritance
85+
86+
- **Sandbox**: Ambiente de execução isolado
87+
- File system isolation
88+
- Network access control
89+
- Command whitelist/blacklist
90+
- Path resolution e validation
91+
92+
- **AuditLogger**: Sistema de auditoria completo
93+
- Níveis: INFO, WARNING, SECURITY, COMPLIANCE
94+
- Formato JSON estruturado
95+
- File e console output
96+
- Retenção de logs configurável
97+
98+
- **SecretsManager**: Gerenciamento de segredos
99+
- Armazenamento criptografado
100+
- Expiração de segredos
101+
- Rotation support
102+
- Environment variables integration
103+
104+
**Arquivos:**
105+
- `react_agent_framework/infrastructure/security/permissions.py` (373 linhas)
106+
- `react_agent_framework/infrastructure/security/sandbox.py` (336 linhas)
107+
- `react_agent_framework/infrastructure/security/audit.py` (367 linhas)
108+
- `react_agent_framework/infrastructure/security/secrets.py` (342 linhas)
109+
- `react_agent_framework/examples/infrastructure_security_demo.py` (320 linhas)
110+
111+
#### 💰 Part 4/5: Cost Control System
112+
113+
**Componentes:**
114+
- **BudgetTracker**: Tracking de orçamento multi-período
115+
- Períodos: Hourly, Daily, Weekly, Monthly
116+
- Gastos por categoria
117+
- Alert thresholds (soft/hard limits)
118+
- Projeção de custos
119+
- Relatórios detalhados
120+
121+
- **RateLimiter**: Rate limiting com múltiplos algoritmos
122+
- Token Bucket (com burst support)
123+
- Sliding Window
124+
- Per-user rate limiting
125+
- Wait time calculation
126+
- Estatísticas de uso
127+
128+
- **QuotaManager**: Gerenciamento de quotas de recursos
129+
- Tipos: Requests, Tokens, Storage, Executions, API calls
130+
- Reset automático por período
131+
- Per-user e global quotas
132+
- Warning thresholds
133+
- Usage reporting
134+
135+
**Arquivos:**
136+
- `react_agent_framework/infrastructure/cost_control/budget.py` (400+ linhas)
137+
- `react_agent_framework/infrastructure/cost_control/rate_limiter.py` (350+ linhas)
138+
- `react_agent_framework/infrastructure/cost_control/quota.py` (380+ linhas)
139+
- `react_agent_framework/examples/infrastructure_cost_control_demo.py` (520+ linhas)
140+
141+
#### 👤 Part 5/5: Human-in-the-Loop System
142+
143+
**Componentes:**
144+
- **ApprovalManager**: Sistema de aprovação de workflows
145+
- Políticas: ALWAYS, NEVER, COST_THRESHOLD, RISK_LEVEL, FIRST_TIME, CUSTOM
146+
- Auto-approval baseado em regras
147+
- Async approval com callbacks
148+
- Request expiration
149+
- Approval history e audit trail
150+
151+
- **InterventionManager**: Mecanismos de intervenção humana
152+
- Tipos: PAUSE, STOP, MODIFY, SKIP, CONTINUE, REDIRECT
153+
- Intervention points configuráveis
154+
- Step-by-step execution mode
155+
- Global pause/resume
156+
- Real-time parameter modification
157+
158+
- **FeedbackCollector**: Coleta e análise de feedback
159+
- Tipos: Rating (1-5), Thumbs up/down, Comment, Correction, Bug report, Feature request
160+
- Agregação de ratings
161+
- Thumbs statistics
162+
- Correction tracking
163+
- Acknowledgment system
164+
- Export de dados
165+
166+
**Arquivos:**
167+
- `react_agent_framework/infrastructure/human_loop/approval.py` (450+ linhas)
168+
- `react_agent_framework/infrastructure/human_loop/intervention.py` (420+ linhas)
169+
- `react_agent_framework/infrastructure/human_loop/feedback.py` (500+ linhas)
170+
- `react_agent_framework/examples/infrastructure_human_loop_demo.py` (550+ linhas)
171+
172+
### 📈 Estatísticas da Release
173+
174+
- **Total de arquivos novos**: 20
175+
- **Total de linhas de código**: ~5500 linhas
176+
- **Componentes implementados**: 15
177+
- **Demos criados**: 5
178+
179+
### 🎯 Completude do Framework
180+
181+
Com esta release, o framework atinge os seguintes níveis de completude nas 4 camadas do Agentic AI:
182+
183+
- **Layer 1 (LLMs)**: 90% ✅
184+
- **Layer 2 (AI Agents)**: 85% ✅
185+
- **Layer 3 (Multi-Agent Systems)**: 5%
186+
- **Layer 4 (Agentic Infrastructure)**: 100% ✅✅✅
187+
188+
### 🔧 Técnico
189+
190+
- Todas as implementações são **thread-safe**
191+
- Suporte a **configuração flexível** via parâmetros
192+
- **Error handling** abrangente
193+
- **Type hints** completos
194+
- Demos **executáveis** e documentados
195+
- Padrões de design **production-ready**
196+
197+
### 📝 Breaking Changes
198+
199+
Esta release **NÃO introduz breaking changes**. Toda a infraestrutura é opt-in e pode ser adicionada a agentes existentes sem modificar código.
200+
201+
### ⚡ Próximos Passos (v0.12.0+)
202+
203+
- Testes unitários completos (pytest)
204+
- CI/CD pipeline
205+
- Layer 3: Multi-Agent Systems
206+
- Publicação no PyPI
207+
208+
---
209+
8210
## [0.10.1] - 2025-01-11
9211

10212
### 🐛 Correções

‎pyproject.toml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
44

55
[project]
66
name = "react-agent-framework"
7-
version = "0.10.1"
8-
description = "Complete AI agent framework with MCP support, environments, reasoning strategies, objectives, memory, and built-in tools"
7+
version = "0.11.0"
8+
description = "Complete AI agent framework with MCP support, infrastructure layer (monitoring, resilience, security, cost control, human-in-the-loop), environments, reasoning strategies, objectives, memory, and built-in tools"
99
authors = [
1010
{name = "Marcos", email = "marcosf63@gmail.com"}
1111
]

‎react_agent_framework/__init__.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,12 @@
99
- Reasoning strategies: ReAct, ReWOO, Reflection, Plan-Execute
1010
- Environments: Web, CLI, File system interaction
1111
- MCP Integration: Connect to Model Context Protocol servers
12+
- Infrastructure Layer: Monitoring, Resilience, Security, Cost Control, Human-in-the-Loop
1213
"""
1314

14-
__version__ = "0.10.1"
15+
__version__ = "0.11.0"
1516
__author__ = "Marcos"
16-
__description__ = "Complete AI agent framework with MCP support, environments, multiple reasoning strategies, multi-provider support, built-in tools, memory, and objectives"
17+
__description__ = "Production-ready AI agent framework with complete infrastructure layer (monitoring, resilience, security, cost control, human-in-the-loop), MCP support, environments, reasoning strategies, multi-provider support, built-in tools, memory, and objectives"
1718

1819
from react_agent_framework.core.react_agent import ReactAgent
1920
from react_agent_framework.core.objectives.objective import Objective

0 commit comments

Comments
 (0)