agentic-research-framework/
│
├── 📚 DOCUMENTATION
│ ├── README.md # 🏠 Main entry point with navigation
│ ├── COMPREHENSIVE_BUILD_SUMMARY.md # 📖 Complete technical guide (1,240 lines)
│ ├── docs/USE_CASE_EXTENSION_GUIDE.md # 🔧 Beginner development guide (2,000+ lines)
│ ├── docs/PORT_ALLOCATION.md # 🌐 Service organization strategy
│ ├── Iterative Reflection vs.txt # 📊 Research methodology
│ └── Chapter 4_ Reflection.txt # 🧠 Producer-Critic pattern theory
│
├── 🧠 CORE FRAMEWORK
│ ├── framework/
│ │ ├── base_agent.py # 🤖 Agent abstraction + ADK integration
│ │ ├── base_orchestrator.py # 🔄 Reflection workflow management
│ │ └── base_evaluator.py # 📊 Multi-dimensional quality assessment
│ │
│ ├── config/
│ │ ├── settings.py # ⚙️ Global configuration
│ │ └── experiments/ # 🧪 Research experiment definitions
│ │
│ └── api/
│ ├── main.py # 🎛️ Main orchestrator (Port 8000)
│ └── use_case_server.py # 🎯 Use case server (Port 8001+)
│
├── 🎯 USE CASES (Pluggable Domains)
│ └── system_design/ # ✅ WORKING - GCP Architecture
│ ├── agents.py # 🏗️ GCP Producer + Technical Critic
│ ├── orchestrator.py # 🔄 System design workflow
│ ├── evaluator.py # 📊 6-dimensional quality evaluation
│ ├── config.py # ⚙️ Quality dimensions + test scenarios
│ ├── tools/
│ │ └── cloud_pricing.py # 💰 GCP/AWS/Azure pricing tools
│ └── docker/ # 🐳 Independent deployment
│ ├── Dockerfile # Container definition
│ └── docker-compose.yml # Standalone service
│
├── 🧪 RESEARCH INFRASTRUCTURE
│ ├── research/
│ │ ├── experiment_orchestrator.py # 🔬 Automated experiment runner
│ │ ├── data/ # 📈 Experiment results
│ │ └── notebooks/ # 📓 Jupyter analysis environment
│ │
│ └── main.py # 🖥️ CLI interface for experiments
│
├── 🐳 DEPLOYMENT
│ ├── docker-compose.yml # 🚀 Multi-service orchestration
│ ├── docker/ # 🏗️ Main framework containers
│ ├── .dockerignore # 📦 Build optimization
│ └── scripts/ # 🔧 Deployment scripts
│
└── ⚙️ CONFIGURATION
├── pyproject.toml # 📦 Dependencies & build config
├── env.example # 🔑 Environment template
└── .env # 🔒 Your secrets (not in git)
- README.md - Main entry point
- env.example - Setup your environment
- Quick Start section - 5-minute setup
- Iterative Reflection vs.txt - Research methodology
- Chapter 4_ Reflection.txt - Reflection pattern theory
- Research Results - Validated findings
- COMPREHENSIVE_BUILD_SUMMARY.md - Complete technical guide
- framework/ - Core implementation
- api/ - API layer and endpoints
- use_cases/system_design/ - Complete reference implementation
- agents.py - Producer-Critic agents
- tools/cloud_pricing.py - Domain tools
- docs/USE_CASE_EXTENSION_GUIDE.md - Complete development guide
- Content Generation Tutorial - Step-by-step example
- Learning Resources - Beginner-friendly links
- docker-compose.yml - Multi-service deployment
- docs/PORT_ALLOCATION.md - Service organization
- Docker configurations - Container setup
- config/experiments/ - Experiment templates
- research/ - Analysis tools and notebooks
- main.py - CLI experiment runner
- Learning Resources - AI agents, ADK, Docker basics
- Chapter 4_ Reflection.txt - Understand the pattern
- Quick Start - Get it running
- Beginner Tutorial - Build your first use case
- COMPREHENSIVE_BUILD_SUMMARY.md - Technical architecture
- framework/base_agent.py - ADK integration patterns
- use_cases/system_design/ - Reference implementation
- Extension Guide - Build new domains
- Iterative Reflection vs.txt - Research design
- Research Results - Validated findings
- Quality Evaluation - Assessment methodology
- Experiment Runner - Systematic testing
- System Design Use Case - GCP specialization
- Cloud Pricing Tools - Multi-cloud comparison
- API Examples - Test real scenarios
- Quality Dimensions - Professional assessment
- Getting Started: README.md
- Complete Guide: COMPREHENSIVE_BUILD_SUMMARY.md
- Extension Guide: docs/USE_CASE_EXTENSION_GUIDE.md
- Research Method: Iterative Reflection vs.txt
- Base Classes: framework/
- Working Example: use_cases/system_design/agents.py
- ADK Integration: framework/base_agent.py
- Reflection Pattern: Chapter 4_ Reflection.txt
- Main API: api/main.py (Port 8000)
- Use Case API: api/use_case_server.py (Port 8001+)
- Endpoints: README.md#api-usage
- Health Checks: All services have
/healthendpoints
- Docker Compose: docker-compose.yml
- Containers: use_cases/system_design/docker/
- Port Strategy: docs/PORT_ALLOCATION.md
- Environment: env.example
- Experiment Runner: research/experiment_orchestrator.py
- Quality Evaluation: framework/base_evaluator.py
- Config Templates: config/experiments/
- Analysis Tools: research/notebooks/
- Cloud Pricing: use_cases/system_design/tools/cloud_pricing.py
- CLI Interface: main.py
- Configuration: config/settings.py
- Scripts: scripts/
docker-compose up -d system_design
curl http://localhost:8001/health# Baseline test
curl -X POST http://localhost:8001/chat -d '{"message":"Design a web app","mode":"baseline"}'
# Reflection test
curl -X POST http://localhost:8001/chat -d '{"message":"Design a web app","mode":"reflection"}'- Follow Extension Guide
- Copy system_design as template
- Customize agents and quality dimensions
- Deploy on new port (8002, 8003, etc.)
python main.py run-experiment config/experiments/system_design_pilot.json# Start Jupyter environment
docker-compose --profile research up -d
# Open http://localhost:8891- ✅ 40 files, 8,190+ lines of code
- ✅ Working Producer-Critic reflection pattern
- ✅ Complete ADK integration
- ✅ Multi-dimensional quality evaluation
- ✅ Docker containerization
- ✅ Research results validation
- ✅ Professional documentation
- ✅ Beginner-friendly guides
- ✅ Extensible architecture
- ✅ Production-ready deployment
Ready for research, deployment, and community validation! 🚀✨