Metadata-Version: 2.4
Name: socrates-ai
Version: 0.6.6
Summary: A Socratic method tutoring system powered by Claude AI with multi-agent orchestration
Author: Socrates AI Contributors
Maintainer: Socrates AI Contributors
License: MIT
Project-URL: Homepage, https://github.com/Nireus79/Socrates
Project-URL: Documentation, https://github.com/Nireus79/Socrates
Project-URL: Repository, https://github.com/Nireus79/Socrates
Project-URL: Bug Tracker, https://github.com/Nireus79/Socrates/issues
Project-URL: Changelog, https://github.com/Nireus79/Socrates/releases
Keywords: ai,claude,socratic-method,tutoring,rag,retrieval-augmented-generation,multi-agent,education,software-engineering
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.7.0
Requires-Dist: chromadb>=0.3.0
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: PyPDF2>=3.0.0
Requires-Dist: python-dateutil>=2.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; 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"
Requires-Dist: isort>=5.12.0; extra == "dev"
Provides-Extra: async
Requires-Dist: asyncio>=3.4.3; extra == "async"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.19; extra == "docs"
Dynamic: license-file

# Socrates AI

A Socratic method tutoring system powered by Claude AI with multi-agent orchestration, RAG (Retrieval-Augmented Generation), and event-driven architecture.
Helps users and collaborators, design and develop projects of various domains.
Ideal for vibe coding

> **Status**: Beta (v0.5.0)
> **License**: MIT
> **Python**: 3.8+

## Features

🎓 **Socratic Learning**: Guide users through structured questioning to help them think through complex problems

🤖 **Multi-Agent System**: Specialized agents for projects, code generation, dialogue, conflict resolution, and more

📚 **RAG Integration**: Retrieval-Augmented Generation with vector embeddings for intelligent knowledge retrieval

⚡ **Async/Await Support**: Non-blocking async operations for integrating with async frameworks

📡 **Event-Driven Architecture**: Decoupled components via event emission for plugin integration

🔧 **Flexible Configuration**: Environment variables, config files, or code-based configuration

📦 **Cross-Platform**: Works on Windows, Linux, and macOS

## Installation

```bash
pip install socrates-ai
```

## Quick Start

### Basic Usage

```python
import socrates

# Initialize with minimal configuration
orchestrator = socrates.quick_start(api_key="sk-ant-...")

# Create a project
result = orchestrator.process_request('project_manager', {
    'action': 'create_project',
    'project_name': 'My API',
    'owner': 'alice'
})

# Generate code
code_result = orchestrator.process_request('code_generator', {
    'action': 'generate_code',
    'project': result['project']
})

print(code_result['script'])
```

### Advanced Configuration

```python
import socrates
from pathlib import Path

# Create configuration with custom settings
config = socrates.ConfigBuilder("sk-ant-...") \
    .with_data_dir(Path("/path/to/data")) \
    .with_model("claude-opus-4-1-20250805") \
    .with_log_level("DEBUG") \
    .build()

# Initialize orchestrator
orchestrator = socrates.create_orchestrator(config)

# Use it
result = orchestrator.process_request('project_manager', {...})
```

### Event-Driven Integration

```python
import socrates

orchestrator = socrates.quick_start(api_key="sk-ant-...")

# Listen to events
def on_code_generated(data):
    print(f"Generated {data['lines']} lines of code")
    print(f"Token usage: {data.get('total_tokens', 'unknown')}")

def on_error(data):
    print(f"Error: {data['message']}")

orchestrator.event_emitter.on(
    socrates.EventType.CODE_GENERATED,
    on_code_generated
)

orchestrator.event_emitter.on(
    socrates.EventType.LOG_ERROR,
    on_error
)

# Process requests - events will be emitted automatically
result = orchestrator.process_request('code_generator', {...})
```

### Async Operations

```python
import asyncio
import socrates

async def main():
    config = socrates.SocratesConfig.from_env()
    orchestrator = socrates.create_orchestrator(config)

    # Run multiple operations concurrently
    results = await asyncio.gather(
        orchestrator.process_request_async('code_generator', code_req),
        orchestrator.process_request_async('socratic_counselor', socratic_req),
        orchestrator.process_request_async('context_analyzer', context_req)
    )

    return results

# Run async operations
results = asyncio.run(main())
```

## Environment Variables

Configure Socrates using environment variables:

```bash
# Required
export ANTHROPIC_API_KEY="sk-ant-..."  # or API_KEY_CLAUDE

# Optional
export CLAUDE_MODEL="claude-opus-4-1-20250805"
export SOCRATES_DATA_DIR="/path/to/data"  # Defaults to ~/.socrates
export SOCRATES_LOG_LEVEL="INFO"          # DEBUG, INFO, WARNING, ERROR
export SOCRATES_LOG_FILE="/path/to/logs/socrates.log"
```

Then use:

```python
import socrates

config = socrates.SocratesConfig.from_env()
orchestrator = socrates.create_orchestrator(config)
```

## Core Concepts

### Agents

Socrates uses specialized agents to handle different operations:

- **ProjectManager**: Create, load, and manage projects
- **SocraticCounselor**: Generate Socratic questions and process responses
- **CodeGenerator**: Generate code based on project context
- **ContextAnalyzer**: Analyze and summarize project context
- **DocumentAgent**: Import and manage project documentation
- **NoteManager**: Manage notes and annotations
- **ConflictDetector**: Detect and help resolve specification conflicts
- **UserManager**: Manage users and authentication
- **SystemMonitor**: Track token usage and system metrics

### Event Types

Subscribe to system events for real-time updates:

```python
socrates.EventType.PROJECT_CREATED
socrates.EventType.CODE_GENERATED
socrates.EventType.QUESTION_GENERATED
socrates.EventType.TOKEN_USAGE
socrates.EventType.LOG_INFO
socrates.EventType.LOG_ERROR
socrates.EventType.AGENT_START
socrates.EventType.AGENT_COMPLETE
# ... and many more
```

### Configuration Options

All configuration options:

```python
config = socrates.SocratesConfig(
    api_key="sk-ant-...",
    claude_model="claude-opus-4-1-20250805",
    embedding_model="all-MiniLM-L6-v2",
    data_dir="/path/to/data",
    log_level="INFO",
    log_file="/path/to/logs/socrates.log",
    max_context_length=8000,
    max_retries=3,
    retry_delay=1.0,
    token_warning_threshold=0.8,
    session_timeout=3600,
    custom_knowledge=[...]
)
```

## Plugin Integration

### PyCharm Plugin

```python
import socrates
from pathlib import Path

class SocratesBridge:
    def __init__(self, api_key: str, project_dir: str):
        config = socrates.ConfigBuilder(api_key) \
            .with_data_dir(Path(project_dir) / '.socrates') \
            .build()

        self.orchestrator = socrates.create_orchestrator(config)

        # Forward events to PyCharm
        self.orchestrator.event_emitter.on(
            socrates.EventType.LOG_INFO,
            self._on_log
        )

    def _on_log(self, data):
        # Send to PyCharm IDE
        pass
```

### VS Code Extension

```python
import json
import sys
import socrates

class VSCodeServer:
    def handle_request(self, method: str, params: dict):
        if method == "initialize":
            config = socrates.SocratesConfig.from_dict(params['config'])
            self.orchestrator = socrates.create_orchestrator(config)
            return {"status": "initialized"}

        elif method == "generateCode":
            result = self.orchestrator.process_request(
                'code_generator',
                params
            )
            return {"code": result['script']}
```

## Error Handling

Socrates uses structured exceptions:

```python
from socrates import (
    SocratesError,
    ConfigurationError,
    AgentError,
    DatabaseError,
    APIError,
)

try:
    result = orchestrator.process_request('code_generator', {...})
except APIError as e:
    print(f"API error: {e.message}")
    print(f"Error code: {e.error_code}")
    print(f"Context: {e.context}")
except SocratesError as e:
    print(f"Socrates error: {e}")
```

## Development

### Install Development Dependencies

```bash
pip install socrates-ai[dev]
```

### Running Tests

```bash
pytest tests/
pytest --cov=socratic_system tests/  # With coverage
```

### Code Quality

```bash
# Format code
black socratic_system/

# Lint
ruff check socratic_system/

# Type checking
mypy socratic_system/
```

## Architecture

```
Socrates Library (socrates-ai)
├── Core
│   ├── AgentOrchestrator (main coordinator)
│   ├── Configuration System
│   ├── Event Emitter
│   └── Exception Hierarchy
├── Agents (specialized workers)
│   ├── ProjectManager
│   ├── CodeGenerator
│   ├── SocraticCounselor
│   └── ... (8 total)
├── Data Layer
│   ├── ProjectDatabase (SQLite)
│   └── VectorDatabase (ChromaDB)
├── Clients
│   └── ClaudeClient (API integration)
└── Models (data structures)
    ├── User
    ├── ProjectContext
    ├── KnowledgeEntry
    └── ... (more)
```

## Production Considerations

- **Data Storage**: Projects, users, and vectors are stored in `~/.socrates/` by default
- **API Keys**: Use environment variables or secure configuration management
- **Token Limits**: Monitor token usage via `TOKEN_USAGE` events
- **Logging**: Enable file logging for production deployments
- **Async**: Use async methods for concurrent operations in high-load scenarios

## Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

## Support

- **Issues**: [GitHub Issues](https://github.com/Nireus79/Socrates/issues)
- **Documentation**: [GitHub Repository](https://github.com/Nireus79/Socrates)

## Roadmap

- [ ] REST API wrapper (FastAPI)
- [ ] React UI frontend
- [ ] PyCharm plugin
- [ ] VS Code extension
- [ ] Enhanced async support
- [ ] Custom agent creation API
- [ ] Multi-user session management
- [ ] Advanced knowledge base features

## License

MIT License - see LICENSE file for details

## Acknowledgments

Built with:
- [Claude AI](https://anthropic.com) by Anthropic
- [ChromaDB](https://www.trychroma.com/) for vector storage
- [Sentence Transformers](https://www.sbert.net/) for embeddings

---

**Made with ❤️ for developers who think deeply about their code**
