Metadata-Version: 2.4
Name: socratic-agents
Version: 0.3.3
Summary: Constitutional AI Agents for Socrates - Published library requiring Socrates v2.0.0+ runtime
Author-email: Anthropic <support@anthropic.com>
License: MIT
Project-URL: Homepage, https://github.com/Nireus79/Socratic-agents
Project-URL: Documentation, https://github.com/Nireus79/Socratic-agents#readme
Project-URL: Repository, https://github.com/Nireus79/Socratic-agents.git
Project-URL: Issues, https://github.com/Nireus79/Socratic-agents/issues
Keywords: constitutional-ai,agents,governance,multi-agent,llm,socratic
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: socratic-morality>=0.0.3
Provides-Extra: api
Requires-Dist: fastapi>=0.100; extra == "api"
Requires-Dist: uvicorn>=0.23; extra == "api"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

# Socratic Agents

⚠️ **REQUIRES SOCRATES MONOLITH** - While this library is published on PyPI, all agents require the Socrates monolith to be installed and functioning. Standalone use is not supported.

---

## Overview

**Socratic Agents** is a collection of 19+ specialized agents that power the Socrates AI platform. These agents handle complex tasks like Socratic questioning, code generation, project management, quality control, learning, and conflict resolution.

**Key Point**: This library is published on PyPI for use with Socrates v2.0.0+, but all agents require the Socrates monolith to be installed locally. They depend on `socratic_system` internals and cannot function independently.

## Requirements

- **Socrates Monolith** - Must be installed locally (REQUIRED)
- **socratic_system** - Must be available in Python path (REQUIRED)
- **Python 3.10+** (minimum, recommended 3.11+)

### Why Socrates-Only?

The agents in this library are tightly integrated with Socrates internals:
- Access to centralized database
- Vector database integration
- Unified LLM client orchestration
- Shared user and project context
- Maturity tracking and workflow optimization

**After the Socrates architecture redesign**, many of these agents will be refactored for independence.

---

## Installation

### Via PyPI (Recommended)

Socratic-agents v0.3.1 is published to PyPI for use with Socrates v2.0.0+:

```bash
pip install socratic-agents==0.3.1
```

This requires Socrates v2.0.0+ to be installed, as the library depends on the Socrates monolith.

### Within Socrates Monolith (Development)

For development work within the Socrates monolith:

```bash
cd Socratic-agents
pip install -e .
```

---

## 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

### Socrates-Dependent Design

All agents are designed to work within the Socrates orchestration framework and require Socrates v2.0.0+ to function:

```
┌─────────────────────────────────────┐
│     Socrates Monolith               │
├─────────────────────────────────────┤
│  AgentOrchestrator                  │
│  ├─ Database Connection             │
│  ├─ Vector Database                 │
│  ├─ LLM Client (Multi-provider)     │
│  └─ Event System                    │
├─────────────────────────────────────┤
│  Socratic Agents (19+)              │
│  ├─ Dialogue Agents                 │
│  ├─ Project Agents                  │
│  ├─ Code Agents                     │
│  ├─ Learning Agents                 │
│  └─ System Agents                   │
└─────────────────────────────────────┘
```

### 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
- **Comprehensive 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

```python
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

⚠️ **IMPORTANT TESTING NOTES:**

- Pytest tests **require the Socrates monolith to be installed**
- Tests can **only be run within the Socrates development environment**
- Tests will fail in isolation without the `socratic_system` module
- This library requires Socrates v2.0.0+ to function

### Running Tests

```bash
cd Socratic-agents

# Run all tests (requires Socrates environment)
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
```

**Note:** If running tests outside the full Socrates environment, you'll see import errors related to missing `socratic_system` module. This is expected and indicates the tests require the full Socrates monolith.

---

## Future: Post-Architecture Redesign

After the Socrates architecture is redesigned and optimized, the following changes are planned:

1. **Independent Agents** - Some agents will be refactored as independent packages
2. **Decoupled Dependencies** - Reduced reliance on Socrates internals
3. **Modular Publishing** - Agent libraries published separately to PyPI
4. **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](LICENSE) for details.

---

**This library is part of the Socrates AI platform**

Made by [@Nireus79](https://github.com/Nireus79)
