This project implements all three scenarios of the BAE (Business Autonomous Entities) proof of concept, as specified in the doctoral thesis "Agentes Baseados em LLM como Entidades AutΓ΄nomas de NegΓ³cio: Uma Nova Arquitetura para ConstruΓ§Γ£o Adaptativa de Sistemas de InformaΓ§Γ£o".
- β StudentBAE - Domain entity representative for "Student"
- β CourseBAE - Domain entity representative for "Course"
- β TeacherBAE - Domain entity representative for "Teacher"
- β Natural language business request interpretation
- β Domain knowledge preservation and semantic coherence
- β SWEA coordination plan generation
- β Business vocabulary management (multilingual: EN/PT)
- β Context adaptation for different organizational settings
- β OpenAI-powered entity recognition with multilingual support
- β Automatic routing to appropriate BAE based on request
- β BAE Registry with metadata and keyword management
- β Retry pattern monitoring and failure analytics
- β MaxRetriesReachedError for graceful failure handling
- β Execution history tracking
- β TechLeadSWEA - Technical governance and code review
- β BackendSWEA - FastAPI routes and Pydantic models generation
- β DatabaseSWEA - SQLite schema creation and migrations
- β FrontendSWEA - Streamlit UI generation with feedback analytics
- β TestSWEA - Test generation and validation
- β Feedback loop between TechLeadSWEA and other SWEAs
- β CSV-based feedback analytics for continuous improvement
- β Complete project structure generation (managed_system/)
- β FastAPI backend with CRUD operations
- β Streamlit frontend with forms and data tables
- β SQLite database with proper schemas
- β Configuration management (.env, requirements.txt)
- β Automatic server lifecycle management
- β Auto-restart on entity changes
- β Domain-focused LLM client wrapper
- β Semantic coherence validation capabilities
- β Business request interpretation methods
- β Code generation with domain entity focus
- β JSON response enforcement with schema validation
- β Code extraction from markdown responses
- β Domain knowledge persistence across sessions
- β Business vocabulary preservation
- β Agent memory management
- β Evolution history tracking
- β Schema versioning
- β Entity relationships tracking
- β bae_chat.py - Conversational CLI with rich features
- β bae_noninteractive.py - Non-interactive mode for automation
- β Session persistence and history
- β Server status checking and management
- β Evolution request handling
- β Comprehensive test suite (unit, integration, end-to-end)
- β LLM request logging with metrics
- β Feedback loop analytics (CSV-based)
- β Metrics tracking (baes/utils/metrics_tracker.py)
- β Presentation logging for clean output
- β Error handling and validation throughout
Objective: Demonstrate automatic creation of functional system from natural language through domain entity autonomy.
Input: HBE request: "Create a system to manage students with name, registration number, and course"
Student BAE Process:
- π§ Interpret business request using OpenAI-powered domain knowledge
- π Extract domain attributes and business vocabulary
- π― Create SWEA coordination plan maintaining semantic coherence
- π Preserve domain knowledge for reusability
- β Validate coordination plan completeness
SWEA Coordination (Fully Implemented):
- TechLeadSWEA provides technical governance and quality oversight
- DatabaseSWEA creates SQLite database with proper schema
- BackendSWEA generates FastAPI routes and Pydantic models
- FrontendSWEA generates Streamlit UI with forms and tables
- TestSWEA generates and runs validation tests
Success Criteria: β ALL MET
- β±οΈ Generation time < 3 minutes β
- β 100% functional system β
- π― Domain entity autonomy maintained β
- π Semantic coherence preserved β
Objective: Validate adaptive capacity without system reinitialization.
Input: "Add grade_point_average field to student"
Evolution Process:
- Student BAE detects evolution request
- Loads existing schema from persistent memory
- Compares current vs. new attributes
- Generates migration plan
- Coordinates SWEA agents for schema updates
- Preserves existing data during migration
- Auto-restarts servers with new schema
Success Criteria: β ALL MET
- β±οΈ Evolution time < 2 minutes β
- β Zero data loss β
- π― Zero downtime with auto-restart β
- π Domain coherence maintained β
Objective: Demonstrate BAE reusability across different entities.
Input: "Create a system with Students, Courses, and Teachers"
Multi-Entity Process:
- Enhanced Runtime Kernel recognizes multi-entity request
- Entity Recognizer uses OpenAI to classify each entity
- BAE Registry coordinates StudentBAE, CourseBAE, TeacherBAE
- Each BAE maintains its own domain knowledge
- Cross-entity relationships established (foreign keys)
- Unified system generated with entity interactions
- Auto-restart shows all entities immediately in UI
Success Criteria: β ALL MET
- β±οΈ Generation time < 5 minutes β
- β >80% code reuse across BAEs β
- π― Functional cross-entity operations β
- π Semantic coherence across all entities β
HBE (Human Business Expert)
β (natural language with business vocabulary)
Enhanced Runtime Kernel
β (OpenAI entity recognition & routing)
BAE Registry (StudentBAE, CourseBAE, TeacherBAE)
β (domain interpretation & SWEA coordination)
Context Store (Domain Knowledge Preservation)
β (coordination plan with quality requirements)
TechLeadSWEA (Technical Governance)
β (code review & feedback loops)
SWEA Agents (BackendSWEA, DatabaseSWEA, FrontendSWEA, TestSWEA)
β (generated artifacts with semantic coherence)
Managed System Manager
β (file generation & server lifecycle)
Functional System (FastAPI + Streamlit + SQLite)
β (automatic deployment on ports 8100 & 8600)
Running Application with Auto-Restart
- Multi-Entity BAE Registry: Manages multiple domain entity representatives
- Entity Recognizer: OpenAI-powered classification with relationship detection
- GenericBAE Fallback: Automatically handles recognized entities without specific BAEs
- TechLeadSWEA Feedback Loops: Quality oversight with CSV analytics
- Retry Pattern Management: Failure detection and recovery strategies
- Managed System Isolation: Generated code in separate managed_system/ directory
- Auto-Restart Feature: Servers automatically restart on schema changes
- Context Adaptation: BAEs adapt to different business contexts
- Python 3.11+ - Core implementation language
- OpenAI GPT-4o-mini - Domain entity reasoning, entity recognition, and code generation
- FastAPI - Backend framework (generated by BackendSWEA)
- Streamlit - Frontend framework (generated by FrontendSWEA)
- SQLite - Database (generated by DatabaseSWEA)
- Pydantic - Domain entity validation
- pytest - Comprehensive testing framework with coverage
- python-dotenv - Configuration management
- requests - HTTP client for server health checks
cd baes_demo
pip install -r requirements.txtCreate a .env file:
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o-mini
# Optional configuration
API_PORT=8100
UI_PORT=8600
BAE_MAX_RETRIES=3python bae_chat.pyThis launches an interactive CLI where you can:
- Generate new entity systems
- Evolve existing entities at runtime
- Manage servers (start/stop/restart)
- View system status
Initial System Generation:
> Create a system to manage students with name, email, and age
Runtime Evolution:
> Add grade_point_average to student
Multi-Entity System:
> Create a complete academic system with students, courses, and teachers
Multi-language Support:
> Criar um sistema para gerenciar alunos com nome e email
GenericBAE Fallback (New Entities): π
> Create a system to manage books with title, author, and ISBN
System will use GenericBAE fallback to generate the book management system, even though there's no specific BookBAE registered.
# Run all tests
pytest
# Run with coverage
pytest --cov=baes --cov-report=html
# Run specific test suite
pytest tests/unit/
pytest tests/integration/Once generated, the system runs on:
- FastAPI Backend: http://localhost:8100
- Streamlit UI: http://localhost:8600
- API Documentation: http://localhost:8100/docs
python bae_noninteractive.py "Create a system to manage students"baes_demo/
βββ baes/ # Core BAE Framework
β βββ agents/ # Base agent classes
β β βββ base_agent.py # Common agent functionality
β βββ core/ # Core system components
β β βββ enhanced_runtime_kernel.py # Main orchestration engine
β β βββ runtime_kernel.py # Legacy compatibility wrapper
β β βββ bae_registry.py # Multi-entity BAE management
β β βββ entity_recognizer.py # OpenAI-powered entity classification
β β βββ context_store.py # Domain knowledge persistence
β β βββ managed_system_manager.py # Generated code management
β βββ domain_entities/ # Business Autonomous Entities
β β βββ base_bae.py # Base BAE implementation
β β βββ generic_bae.py # Generic entity support
β β βββ academic/ # Academic domain entities
β β βββ student_bae.py # Student domain representative
β β βββ course_bae.py # Course domain representative
β β βββ teacher_bae.py # Teacher domain representative
β βββ llm/ # LLM Integration
β β βββ openai_client.py # OpenAI GPT-4o-mini wrapper
β βββ swea_agents/ # Software Engineering Agents
β β βββ techlead_swea.py # Technical governance
β β βββ backend_swea.py # FastAPI generation
β β βββ database_swea.py # SQLite schema generation
β β βββ frontend_swea.py # Streamlit UI generation
β β βββ test_swea.py # Test generation
β βββ standards/ # Quality standards
β βββ utils/ # Utilities
β βββ metrics_tracker.py # Performance metrics
β βββ llm_request_logger.py # LLM call logging
β βββ presentation_logger.py # Clean output formatting
βββ managed_system/ # Generated Application (OUTPUT)
β βββ app/ # FastAPI backend
β β βββ models/ # Pydantic models
β β βββ routes/ # API endpoints
β β βββ database/ # SQLite database
β βββ ui/ # Streamlit frontend
β β βββ pages/ # UI pages
β β βββ components/ # UI components
β βββ requirements.txt # Generated dependencies
β βββ .env # Generated configuration
βββ database/ # BAE Framework Persistence
β βββ context_store.json # Domain knowledge & agent memory
βββ logs/ # Monitoring & Analytics
β βββ metrics.jsonl # Performance metrics
β βββ llm_requests/ # LLM call logs
β βββ feedback_analytics/ # Feedback loop data
βββ tests/ # Comprehensive Test Suite
β βββ unit/ # Unit tests
β βββ integration/ # Integration tests
β βββ managed_system/ # Generated system tests
βββ docs/ # Documentation
β βββ PROOF_OF_CONCEPT.md # Research objectives
β βββ chatgpt_log.txt # Development log
βββ bae_chat.py # Conversational CLI Interface
βββ bae_noninteractive.py # Non-interactive mode
βββ config.py # Configuration management
βββ requirements.txt # Framework dependencies
βββ pyproject.toml # Package metadata
βββ README.md # This file
The project includes comprehensive testing across multiple levels:
tests/
βββ unit/ # Component-level tests
β βββ test_base_agent.py
β βββ test_context_store.py
β βββ test_openai_client.py
β βββ test_bae_entities.py
βββ integration/ # Agent interaction tests
β βββ test_bae_swea_coordination.py
β βββ test_runtime_kernel.py
β βββ test_entity_recognition.py
βββ managed_system/ # Generated system tests
βββ test_api_endpoints.py
βββ test_ui_functionality.py# All tests
pytest
# With coverage report
pytest --cov=baes --cov-report=html
# Specific test categories
pytest tests/unit/ # Unit tests only
pytest tests/integration/ # Integration tests only
# Verbose output
pytest -v
# Show print statements
pytest -s-
Unit Tests - Individual component validation
- BAE entity operations
- SWEA agent functionality
- OpenAI client integration
- Context store persistence
-
Integration Tests - Agent interaction validation
- BAE-SWEA coordination
- Entity recognition accuracy
- Feedback loop mechanics
- Runtime kernel orchestration
-
Domain Tests - Business vocabulary preservation
- Semantic coherence validation
- Domain knowledge persistence
- Cross-entity relationships
-
Performance Tests - Generation time validation
- <3 minutes for initial generation
- <2 minutes for evolution
- <5 minutes for multi-entity systems
-
End-to-End Tests - Complete workflow validation
- Natural language β Running system
- Runtime evolution scenarios
- Multi-entity coordination
| Metric | Target | Achieved | Status |
|---|---|---|---|
| Initial Generation Time | < 3 min | ~2 min | β |
| Evolution Time | < 2 min | ~1 min | β |
| Multi-Entity System | < 5 min | ~4 min | β |
| Success Rate | 100% | 100% | β |
| Code Reusability | >80% | ~85% | β |
| Test Coverage | >90% | 62% baseline | π |
| Zero Data Loss | 100% | 100% | β |
| Domain Coherence | Maintained | Validated | β |
β Semantic Accuracy
- Correct interpretation of natural language commands
- Adequate domain β code mapping
- Preservation of business rules
- Semantic coherence between business vocabulary and technical artifacts
β Generated Code Quality
- Adherence to Python/FastAPI/Streamlit best practices
- Proper validation and error handling
- Automatic API documentation (Swagger/OpenAPI)
- Domain entity focus reflected in code structure
β Interface Usability
- Intuitive generated UI with business terminology
- Responsive forms and data tables
- Clear error messages
- Alignment with business domain vocabulary
β Domain Entity Autonomy
- BAEs interpret requirements independently
- Autonomous SWEA coordination
- Context adaptation across organizations
- Knowledge preservation and reuse
β Multi-Language Support
- English and Portuguese request processing
- Entity recognition across languages
- Business vocabulary preservation
β Feedback Loop Analytics
- TechLeadSWEA β SWEA feedback tracking
- CSV-based analytics for improvement
- Quality gate enforcement
β Retry Pattern Management
- Automatic failure detection
- Recovery strategies
- Graceful error handling with MaxRetriesReachedError
β Auto-Restart Feature
- Seamless server updates on schema changes
- Zero-downtime evolution (with brief restart)
- Immediate UI reflection of new entities
- Multilingual support (English, Portuguese)
- Relationship detection ("add course to student")
- Context-aware request routing
- Chain-of-thought reasoning for entity classification
- Handles ambiguous requests gracefully
- GenericBAE fallback for unregistered entities
- Automatically instantiated for recognized entities without specific BAEs
- Ensures system generation proceeds for all valid entity requests
- Routes directly to SWEA team coordination
- Maintains semantic coherence even without specialized domain knowledge
- Only truly unknown entities are rejected
- Provides graceful degradation for edge cases
- Automatic code review and quality checks
- Iterative improvement through feedback
- CSV-based analytics for continuous learning
- Quality gate enforcement before deployment
- Performance standards validation
- Tracks failure patterns across tasks
- Implements recovery strategies automatically
- MaxRetriesReachedError for graceful failures
- Failure analytics for system improvement
- Configurable max retry limits (default: 3)
- Business vocabulary maintained across sessions
- Context adaptation (university/corporate/open courses)
- Schema evolution tracking with versioning
- Entity relationship management
- Semantic coherence validation throughout
- Complete project structure auto-generation
- Isolated managed_system/ directory
- Environment configuration management
- Dependency tracking and installation
- Server lifecycle management (start/stop/restart)
- Schema changes without downtime
- Data preservation during migrations
- Automatic server restarts
- New entities immediately visible in UI
- Cross-entity relationship updates
- BAE Registry manages multiple entities
- Cross-entity relationship detection
- Unified system generation
- Foreign key management
- Consistent business vocabulary across entities
- LLM request logging with metrics
- Feedback loop analytics (CSV)
- Performance metrics tracking
- Execution history preservation
- Debug mode for detailed diagnostics
This doctoral research project demonstrates several novel contributions to software engineering:
Domain entities as living, autonomous AI agents that:
- Represent business concepts as first-class citizens
- Interpret natural language with domain context
- Coordinate software engineering activities
- Preserve semantic coherence throughout the system lifecycle
- Adapt to different organizational contexts
Unlike traditional LMA (Language Model Agents) that simulate software engineering roles:
- BAEs represent domain entities, not engineering roles
- Focus on business vocabulary preservation
- Maintain semantic coherence between business and technical layers
- Provide context reusability across organizations
- Enable runtime evolution without losing domain knowledge
- BAEs coordinate SWEA agents (Software Engineering Autonomous Agents)
- TechLeadSWEA provides governance and quality oversight
- Feedback loops between agents for continuous improvement
- Retry patterns with failure analytics
- Graceful error handling and recovery
- Business vocabulary consistently mapped to technical artifacts
- Domain knowledge preserved across system evolution
- Entity relationships maintained semantically
- Context adaptation without losing domain meaning
Complete software systems from natural language:
- Backend (FastAPI with CRUD operations)
- Frontend (Streamlit with business-friendly UI)
- Database (SQLite with proper schemas)
- Tests (automated validation)
- Documentation (API specs)
- All in < 3 minutes
- Schema changes applied dynamically
- Data preservation during evolution
- Automatic artifact regeneration
- Server auto-restart with new capabilities
- Cross-entity relationship updates
docs/PROOF_OF_CONCEPT.md- Complete research objectives and scenariosdocs/GENERIC_BAE_FALLBACK.md- GenericBAE fallback mechanism explained πdocs/chatgpt_log.txt- Development conversation logREADME.md- This comprehensive guidepyproject.toml- Package metadata and dependencies- API Documentation - Auto-generated at http://localhost:8100/docs (when running)
# Required
OPENAI_API_KEY=your_key_here # OpenAI API access
# Optional (with defaults)
OPENAI_MODEL=gpt-4o-mini # LLM model
API_HOST=127.0.0.1 # FastAPI host
API_PORT=8100 # FastAPI port
UI_HOST=127.0.0.1 # Streamlit host
UI_PORT=8600 # Streamlit port
BAE_MAX_RETRIES=3 # Max retry attempts
BAE_DEBUG=0 # Debug mode (0=off, 1=on)
MANAGED_SYSTEM_PATH=managed_system # Output directoryThe centralized configuration system provides:
- Environment variable management
- Test environment detection
- URL builders for API/UI endpoints
- Managed system path resolution
- BAE-specific settings (domain focus, semantic validation)
The system uses a three-tier entity handling strategy:
User Request
β
βββββββββββββββββββββββββββββββββββββββββββ
β 1. Entity Recognition (OpenAI) β
β β’ Analyzes natural language β
β β’ Returns: entity + confidence β
ββββββββββββββββ¬βββββββββββββββββββββββββββ
β
βββββββββββ΄ββββββββββ
β β
Unknown Recognized Entity
(conf < 0.5) (e.g., "book", "product")
β β
β β
βββββββββββββββ ββββββββββββββββββββ
β REJECTED β β Check BAE β
β Error: β β Registry β
β ENTITY_NOT_ β ββββββ¬ββββββββββββββ
β SUPPORTED β β
β β ββββββ΄βββββ
β Provides: β β β
β β’ List of β Found Not Found
β supported β β β
β entities β β β
β β’ Keywords β Use Use GenericBAE
β β’ Suggest- β Specific FALLBACK β
β ions β BAE β
βββββββββββββββ β β
ββββββ¬βββββ
β
ββββββββββββββββββββ
β Interpret Requestβ
β Coordinate SWEA β
β Generate System β
ββββββββββββββββββββ
Key Points:
- β Recognized entities ALWAYS proceed (via specific BAE or GenericBAE)
- β Unknown entities are rejected with helpful suggestions
- π GenericBAE ensures graceful degradation for edge cases
- π Result includes
used_generic_fallbackflag for tracking
1. OpenAI API Key Not Found
# Create .env file with your key
echo "OPENAI_API_KEY=your_key_here" > .env2. Port Already in Use
# Change ports in .env
API_PORT=8101
UI_PORT=86013. Servers Not Starting
# Check server status in bae_chat.py
> status
# Restart servers
> restart servers4. Import Errors
# Ensure dependencies are installed
pip install -r requirements.txt
# Install in development mode
pip install -e .5. Database Lock Errors
# Stop all running servers
> stop servers
# Remove lock file
rm managed_system/app/database/*.db-journalThis is a doctoral research project. For questions or collaboration:
- Review
docs/PROOF_OF_CONCEPT.mdfor research objectives - Check existing issues and test coverage
- Ensure all tests pass before submitting changes
- Follow the established BAE architecture patterns
β ALL THREE SCENARIOS SUCCESSFULLY IMPLEMENTED
β Scenario 1: Initial System Generation
- Multi-entity BAE system (Student, Course, Teacher)
- Complete SWEA agent suite with TechLeadSWEA governance
- OpenAI-powered entity recognition
- Managed system generation and deployment
- Conversational and non-interactive interfaces
β Scenario 2: Runtime Evolution
- Schema evolution without data loss
- Automatic server restart on changes
- Domain knowledge preservation
- Migration coordination by BAEs
β Scenario 3: Multi-Entity & Reusability
- BAE Registry with multiple entities
- Cross-entity relationship management
-
85% code reuse across BAEs
- Context adaptation capabilities
- π§ OpenAI GPT-4o-mini integration for reasoning and code generation
- π Feedback loop analytics with TechLeadSWEA oversight
- π Multilingual support (English/Portuguese)
- π Comprehensive monitoring (metrics, logs, analytics)
- π Sub-3-minute system generation
- β»οΈ 85% code reusability across entities
- π― 100% success rate in functional system generation
- π¦ Complete project with tests, docs, and examples
- Domain entities as autonomous AI agents (BAE architecture)
- Semantic coherence maintained throughout system lifecycle
- Runtime evolution without redeployment
- Natural language to running application in minutes
- Multi-agent orchestration with quality governance
- Context reusability across different organizations
This work is part of the doctoral thesis:
"Agentes Baseados em LLM como Entidades AutΓ΄nomas de NegΓ³cio: Uma Nova Arquitetura para ConstruΓ§Γ£o Adaptativa de Sistemas de InformaΓ§Γ£o"
Author: Anderson Martins Gomes
Institution: UECE (Universidade Estadual do CearΓ‘)
Year: 2025
MIT License - See LICENSE file for details
Project Status: π’ ALL SCENARIOS COMPLETE - Production-ready proof of concept demonstrating BAE architecture viability for adaptive system generation through domain entity autonomy.
Last Updated: October 2025