Socratic Agents
Socratic Agents - Independent multi-agent framework designed for standalone use with optional Constitutional AI governance integration.
Overview
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)
- Agent implementations ready to use
- REST API for external access
- Clean service interfaces for custom implementations
Requirements
- Python 3.10+ (recommended 3.11 or 3.12)
- pydantic>=2.0 - Data validation and modeling
Optional Dependencies
- 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
Installation
Via PyPI (Recommended)
Install the latest version from PyPI:
pip install socratic-agents
For 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]
Development Installation
For development or local testing:
cd Socratic-agents
pip install -e ".[dev]" # Includes all dev dependencies
The 19+ Agents
Core Dialogue Agents
- SocraticCounselorAgent - Guides users through Socratic questioning with full dialogue orchestration
- QuestionQueueAgent - Manages and prioritizes question queues
Project & Workflow Agents
- ProjectManagerAgent - Manages project lifecycle (creation, loading, collaboration)
- QualityControllerAgent - Orchestrates maturity tracking and quality assurance
- WorkflowOptimizationAgent - Optimizes workflow paths and decision strategies
Code & Technical Agents
- CodeGeneratorAgent - Generates code based on project context
- CodeValidationAgent - Validates and tests code
- DocumentProcessorAgent - Processes and imports project documents
- GitHubSyncHandler - Handles GitHub repository synchronization
Learning & Knowledge Agents
- 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
User & System Agents
- UserManagerAgent - Manages user accounts and preferences
- SystemMonitorAgent - Monitors system health and token usage
- ContextAnalyzerAgent - Analyzes and manages project context
- MultiLLMAgent - Coordinates multiple LLM providers
Note & Data Agents
- NoteManagerAgent - Manages project notes and documentation
- DocumentContextAnalyzer - Analyzes semantic content of documents
Architecture
Architecture
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 │
└─────────────────────────────────────┘
Key Features
- 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
- Logging - Detailed operation logging
Phase 3 Features - Constitutional AI & Governance
- 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
Quick Reference
Initialize Agents Within Socrates
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
})
Available Actions Vary by Agent
Each agent has specific actions. See individual agent documentation for details.
Testing
# 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 integration
Test Coverage
Current test coverage: 81%+ across all agent implementations.
Future: Post-Architecture Redesign
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...
Architecture Documentation
Status: Currently in integration phase within Socrates monolith.
For detailed agent documentation, see the docs/ directory (available after Socrates publication).
Contributing
This library is maintained as part of the Socrates monolith. Contributions should follow Socrates contribution guidelines.
License
MIT License - See LICENSE for details.
This library is part of the Socrates AI platform
Made by @Nireus79
Origin
This package comes from the Socrates research prototype, which is not maintained as a product. Status: alpha. Written by Efthimios Angelopoulos with AI coding assistants (Claude Code); I design, review and test it. Contact: Hermes_creative@proton.me.
Use This Package Standalone:
pip install socratic-agents
Or As Part of Socrates Platform:
pip install socrates-ai # Includes 37+ modules + all 11 packages
Integration Example:
See the Socrates ECOSYSTEM.md for detailed integration examples showing how to use socratic-agents with other Socratic packages.
Related packages you might use together:
More Information:
Metadata
Release files for socratic-agents 0.4.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| socratic_agents-0.4.9.tar.gz | 247.0 kB | Without provenance | Details for socratic_agents-0.4.9.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| socratic_agents-0.4.9-py3-none-any.whl | Python 3 | none | any | Details for socratic_agents-0.4.9-py3-none-any.whl |
Total release size: 538.7 kB
Release files / socratic_agents-0.4.9.tar.gz
| Download URL | socratic_agents-0.4.9.tar.gz |
|---|---|
| Size | 247.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
14cf1e698570d8213bf5a0cbe8745f56fed077b732519aedc39bc2954f508aa4
|
|
BLAKE2b-256 checksum How to use checksums |
dbf3aad44d2b2d63be48d5cfaa3ca91e5436c367a7bb37880f40649ec4d5372d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.17
|
Release files / socratic_agents-0.4.9-py3-none-any.whl
| Download URL | socratic_agents-0.4.9-py3-none-any.whl |
|---|---|
| Size | 291.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2366852324f4771e1361ef15bde80151b83844494d7c286fdb2cf18d2cfafdde
|
|
BLAKE2b-256 checksum How to use checksums |
998092cb38260f2b51b0f73e0ce12681463e2b8aee6d1735dc056ddb56fd89c1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.17
|
Security for socratic-agents 0.4.9
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.