Socratic Agents - Independent multi-agent framework designed for standalone use with optional Constitutional AI governance integration.
Socratic Agents is a collection of 19+ specialized agents that handle complex tasks like Socratic questioning, code generation, project management, quality control, learning, and conflict resolution.
The library uses service-based architecture with dependency injection - agents are decoupled from any monolithic system, enabling flexible use in diverse deployment scenarios.
Key Features:
- Service-based architecture with dependency injection
- Multi-agent orchestration with event-driven messaging via AgentBus
- Optional Constitutional AI governance (socratic-morality integration)
- Comprehensive agent implementations ready to use
- REST API for external access
- Clean service interfaces for custom implementations
- Python 3.10+ (recommended 3.11 or 3.12)
- pydantic>=2.0 - Data validation and modeling
- FastAPI - For REST API support (
pip install socratic-agents[api]) - socratic-morality - For Constitutional AI governance features (governance module)
- Anthropic SDK - For Claude LLM integration
Install the latest version from PyPI:
pip install socratic-agentsFor REST API support, install with the api extra:
pip install socratic-agents[api]For governance features, install with the governance extra:
pip install socratic-agents[governance]For development or local testing:
cd Socratic-agents
pip install -e ".[dev]" # Includes all dev dependencies- SocraticCounselorAgent - Guides users through Socratic questioning with full dialogue orchestration
- QuestionQueueAgent - Manages and prioritizes question queues
- ProjectManagerAgent - Manages project lifecycle (creation, loading, collaboration)
- QualityControllerAgent - Orchestrates maturity tracking and quality assurance
- WorkflowOptimizationAgent - Optimizes workflow paths and decision strategies
- CodeGeneratorAgent - Generates code based on project context
- CodeValidationAgent - Validates and tests code
- DocumentProcessorAgent - Processes and imports project documents
- GitHubSyncHandler - Handles GitHub repository synchronization
- UserLearningAgent - Tracks user behavior and learning patterns
- KnowledgeManagerAgent - Manages knowledge base enrichment
- KnowledgeAnalysisAgent - Analyzes and extracts knowledge insights
- ConflictDetectorAgent - Detects and resolves conflicts in specifications
- UserManagerAgent - Manages user accounts and preferences
- SystemMonitorAgent - Monitors system health and token usage
- ContextAnalyzerAgent - Analyzes and manages project context
- MultiLLMAgent - Coordinates multiple LLM providers
- NoteManagerAgent - Manages project notes and documentation
- DocumentContextAnalyzer - Analyzes semantic content of documents
Agents are organized by function and work together through the AgentOrchestrator:
┌─────────────────────────────────────┐
│ AgentOrchestrator │
│ ├─ Event System │
│ ├─ LLM Client (Multi-provider) │
│ └─ Message Routing (AgentBus) │
├─────────────────────────────────────┤
│ Socratic Agents (19+) │
│ ├─ Dialogue Agents │
│ ├─ Project Agents │
│ ├─ Code Agents │
│ ├─ Learning Agents │
│ └─ System Agents │
├─────────────────────────────────────┤
│ Constitutional AI Governance │
│ └─ Via socratic-morality library │
└─────────────────────────────────────┘
- Agent Orchestration - Coordinated agent workflows through AgentOrchestrator
- Async Support - Full async/await support for non-blocking operations
- Event System - Real-time event emission for status tracking
- Database Integration - Direct access to Socrates database
- Vector DB Access - Knowledge and context retrieval
- Multi-Provider LLM - Via Socratic Nexus integration
- Type Hints - Full Python type annotations
- Comprehensive Logging - Detailed operation logging
- GovernedAgent - Wraps agents with constitutional governance checks
- Agent Bus - Inter-agent message routing with history tracking (1000 message buffer)
- Governance Integration - Uses socratic-morality for ethical decision making
- REST API - FastAPI endpoints for governance, agents, and precedent lookup
- YAML Configuration - Constitutional governance rules and agent configuration
from socratic_agents import AgentOrchestrator, SocraticCounselorAgent
# Create orchestrator (within Socrates context)
orchestrator = AgentOrchestrator(
database=socrates_db,
vector_db=socrates_vector_db,
claude_client=socrates_llm_client
)
# Create and use specific agent
counselor = SocraticCounselorAgent(orchestrator)
result = counselor.process({
"action": "generate_question",
"project": project_context,
"current_user": user_id
})Each agent has specific actions. See individual agent documentation for details.
# Install development dependencies
pip install -e ".[dev]"
# Run all tests
pytest tests/ -v --cov=src/socratic_agents
# Run with coverage report
pytest tests/ --cov=src/socratic_agents --cov-report=html
# Run specific test category
pytest -m unit
pytest -m integrationCurrent test coverage: 81%+ across all agent implementations.
After the Socrates architecture is redesigned and optimized, the following changes are planned:
- Independent Agents - Some agents will be refactored as independent packages
- Decoupled Dependencies - Reduced reliance on Socrates internals
- Modular Publishing - Agent libraries published separately to PyPI
- Standalone Mode - Core agents usable without full Socrates installation
Current independent Socratic libraries:
- socratic-analyzer - Code analysis (standalone)
- socratic-learning - Learning algorithms (standalone)
- Socratic-workflow - Workflow definitions (standalone)
- Socratic-maturity - Maturity tracking (standalone)
- And 4+ others...
Status: Currently in integration phase within Socrates monolith.
For detailed agent documentation, see the docs/ directory (available after Socrates publication).
This library is maintained as part of the Socrates monolith. Contributions should follow Socrates contribution guidelines.
MIT License - See LICENSE for details.
This library is part of the Socrates AI platform
Made by @Nireus79
This package is a component of Socrates AI, a production-ready platform for building intelligent multi-agent systems with constitutional governance.
pip install socratic-agentspip install socrates-ai # Includes 37+ modules + all 11 packagesSee the Socrates ECOSYSTEM.md for detailed integration examples showing how to use socratic-agents with other Socratic packages.
Related packages you might use together: