A comprehensive educational framework for building intelligent agent systems for scientific applications, designed for hackathon participants learning AI and collaborative development.
This codebase demonstrates all key concepts from Session 2A: Agentic Systems Deep Dive:
- Agent Architecture Patterns - Modular, role-based agent design
- Tool Integration Strategies - Extending agent capabilities with external tools
- Memory and State Management - Persistent context and learning systems
- Multi-Agent Coordination - Collaborative workflows and task decomposition
- Evaluation Frameworks - Metrics for assessing agent performance
- Python 3.8 or higher
- Ollama installed and running locally
# macOS
brew install ollama
# Linux
curl -fsSL https://ollama.ai/install.sh | sh
# Windows
# Download from https://ollama.ai/download/windowsollama serve# Recommended models for the hackathon
ollama pull llama3.1:8b # Best balance of speed/capability
ollama pull mistral:7b # Fast and efficient
ollama pull codellama:7b # Good for code-related tasks
ollama pull phi3:mini # Lightweight option# Clone or download the hackathon code
git clone <repository-url>
cd scientific-agentic-system
# Install requirements (minimal dependencies)
pip install requests
# Verify environment
python environment_check.py
# Run automated setup
python setup_ollama.pypython main.pyStart with the tutorial to learn concepts step by step:
# Interactive tutorial - all exercises
python tutorial.py
# Or run specific exercises
python tutorial.py --exercise 1 # Basic LLM interaction
python tutorial.py --exercise 2 # Agent creation
python tutorial.py --exercise 3 # Tool integrationLearning Progression:
- Exercise 1: Basic LLM interaction with Ollama
- Exercise 2: Creating agents with different roles
- Exercise 3: Adding tools to extend capabilities
- Exercise 4: Memory systems for context
- Exercise 5: Multi-agent workflows
- Exercise 6: Performance evaluation
- Exercise 7: Complete scientific application
Jump directly to specific concepts:
# Study the main system
python main.py
# Explore individual components
python -c "from main import BaseAgent, AgentRole; agent = BaseAgent('test', AgentRole.RESEARCHER); print(agent.system_prompt)"
# Run workflow examples
python -c "import asyncio; from main import create_research_workflow; asyncio.run(create_research_workflow())"scientific-agentic-system/
├── main.py # Complete agentic system implementation
├── tutorial.py # Step-by-step learning exercises
├── setup_ollama.py # Automated setup and verification
├── environment_check.py # Python environment validation
└── README.md # This documentation
# Basic agent structure
agent = BaseAgent(
agent_id="researcher_01",
role=AgentRole.RESEARCHER,
model="llama3.1:8b"
)
# Agents have:
# - Role-specific system prompts
# - Built-in tool integration
# - Persistent memory systems
# - Message-based communication- RESEARCHER - Literature search and analysis
- ANALYST - Data processing and statistical analysis
- SYNTHESIZER - Information integration and summarization
- VALIDATOR - Quality control and fact-checking
- COORDINATOR - Workflow management and task allocation
- WebSearchTool - Scientific literature and information retrieval
- CalculatorTool - Mathematical and statistical calculations
- FileAnalysisTool - Scientific data file processing
- Episodic Memory - Specific interactions and events
- Semantic Memory - Learned concepts and knowledge
- Working Memory - Current context and active goals
-
Literature Review
Researcher → Analyst → Synthesizer → Validator -
Hypothesis Testing
Researcher → Analyst → Validator -
Data Analysis Pipeline
Analyst → Synthesizer → Validator
Try these with the system:
- "What are the current limitations of CRISPR gene editing technology?"
- "Analyze the relationship between climate change and coral reef biodiversity"
- "Compare machine learning approaches for protein structure prediction"
- "Investigate microplastic pollution impacts on marine food chains"
class CustomTool(Tool):
def name(self) -> str:
return "custom_tool"
def description(self) -> str:
return "Description of what this tool does"
async def execute(self, **kwargs) -> Dict[str, Any]:
# Your tool implementation
return {"success": True, "result": "..."}
# Register with agent
agent.tools["custom_tool"] = CustomTool()# Add to AgentRole enum
class AgentRole(Enum):
# ... existing roles ...
DOMAIN_EXPERT = "domain_expert"
# Add corresponding system prompt in BaseAgent._get_system_prompt()coordinator = AgentCoordinator()
# Register your agents
coordinator.register_agent(agent1)
coordinator.register_agent(agent2)
# Define workflow
coordinator.define_workflow(
"custom_workflow",
["agent1_id", "agent2_id"]
)
# Execute
results = await coordinator.execute_workflow("custom_workflow", "Your query")- Research Assistant - Build a literature review bot for your scientific field
- Data Analyzer - Create an agent that processes and explains experimental data
- Study Planner - Design a system that helps plan scientific experiments
- Citation Finder - Build a tool that finds and formats scientific references
- Multi-Modal Research System - Integrate image, text, and data analysis
- Collaborative Lab Assistant - Coordinate multiple scientific workflows
- Hypothesis Generator - AI system that proposes testable hypotheses
- Research Quality Evaluator - Assess and improve scientific writing
- Cross-Domain Knowledge Bridge - Connect insights across scientific fields
- Biology: Gene analysis, protein folding, ecological modeling
- Chemistry: Molecular design, reaction optimization, materials science
- Physics: Data analysis, theoretical modeling, experimental design
- Environmental Science: Climate modeling, pollution analysis, sustainability
- Medicine: Drug discovery, diagnostic assistance, treatment optimization
The system is designed for collaborative development:
# Fork the repository
git fork <original-repo>
# Create feature branch
git checkout -b feature/my-scientific-tool
# Make changes and commit
git add .
git commit -m "Add custom scientific analysis tool"
# Push and create pull request
git push origin feature/my-scientific-tool- Modular Design - Easy to divide work among team members
- Clear Interfaces - Well-defined APIs for tools and agents
- Documentation - Comprehensive examples and tutorials
- Testing Framework - Built-in evaluation and validation
- Response Quality - Content relevance and completeness
- Workflow Efficiency - Speed and resource usage
- Scientific Rigor - Accuracy and methodology
# Create custom metrics for your domain
def domain_specific_metric(text: str) -> float:
# Your evaluation logic
return score
# Apply to agent responses
score = domain_specific_metric(agent_response)Ollama Connection Failed
# Check if Ollama is running
curl http://localhost:11434/api/tags
# Start Ollama if needed
ollama serveNo Models Available
# Pull a basic model
ollama pull llama3.1:8b
# List available models
ollama listPython Environment Issues
# Run environment check
python environment_check.py
# Install missing dependencies
pip install requestsMemory Database Issues
# Delete and recreate database
rm agent_memory.db
python -c "from main import MemoryManager; MemoryManager()"- Model Selection - Choose appropriate model size for your hardware
- Batch Processing - Process multiple queries together
- Memory Management - Regularly clean old memories
- Tool Caching - Cache expensive tool operations
- Documentation - Maintain clear README and API docs
- Testing - Add unit tests for reliability
- Community - Engage with other developers
- Publishing - Share your work on GitHub
- Production Deployment - Move from local to cloud infrastructure
- API Integration - Connect to real scientific databases
- User Interface - Build web or desktop interfaces
- Model Training - Fine-tune models for your domain
- Academic Grants - Apply for research funding
- Industry Partnerships - Collaborate with scientific organizations
- Open Source - Contribute to the scientific software community
- PubMed API - Medical literature
- arXiv API - Scientific preprints
- NASA APIs - Space and Earth science data
- NCBI Datasets - Biological data
- GitHub Discussions - Ask questions and share ideas
- Scientific Python Community - Connect with domain experts
- AI/ML Communities - Learn about latest developments
- Minimum: 8GB RAM for 7B parameter models
- Recommended: 16GB RAM for 13B parameter models
- Optimal: 32GB+ RAM for multiple concurrent models
The system is designed to be model-agnostic:
# Easy to swap between local and cloud models
# Just change the OllamaClient to OpenAIClient, etc.- Local Execution - All models run locally for data privacy
- Safe Evaluation - Mathematical expressions are sanitized
- Memory Isolation - Each agent maintains separate memory space
- Check this README for common solutions
- Run the diagnostic scripts (
environment_check.py,setup_ollama.py) - Review tutorial exercises for learning concepts
- Ask questions in GitHub Issues
We welcome contributions! Please:
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Update documentation
- Submit a pull request
This project is designed for educational use in scientific research. Please respect any licensing terms of dependencies and cite appropriately in academic work.
- Complete the setup - Follow the Quick Start guide
- Run the tutorial - Learn concepts step by step
- Try the examples - Experiment with scientific queries
- Build your project - Apply concepts to your research domain
- Collaborate and share - Work with others and contribute back
Happy hacking! 🚀