socrates-ai-api 1.3.0__py3-none-any.whl

socrates_ai_api-1.3.0.dist-info/METADATA

@@ -0,0 +1,446 @@
+Metadata-Version: 2.4
+Name: socrates-ai-api
+Version: 1.3.0
+Summary: REST API server for Socrates AI with GitHub-ready project generation, export, and publishing capabilities
+Author: Socrates AI Contributors
+License: MIT
+Project-URL: Homepage, 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: Source Code, https://github.com/Nireus79/Socrates/tree/main/socrates-api
+Keywords: api,rest,fastapi,socrates,ai,tutoring,github,export,git,ci-cd
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+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: Environment :: Web Environment
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: socrates-ai>=1.3.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn[standard]>=0.23.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: python-multipart>=0.0.5
+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: httpx>=0.24.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# Socrates API
+
+REST API server for the Socrates AI tutoring system. Built with FastAPI, this server provides endpoints for project management, Socratic questioning, code generation, and more.
+
+## Installation
+
+```bash
+pip install socrates-api
+```
+
+## Quick Start
+
+### 1. Set Environment Variables
+
+```bash
+export ANTHROPIC_API_KEY="your-api-key-here"
+export SOCRATES_DATA_DIR="~/.socrates"  # Optional
+export SOCRATES_API_HOST="0.0.0.0"      # Optional, default: 127.0.0.1
+export SOCRATES_API_PORT="8000"         # Optional, default: 8000
+```
+
+### 2. Run the Server
+
+```bash
+socrates-api
+```
+
+Or use Python directly:
+
+```bash
+python -m socrates_api.main
+```
+
+### 3. Access the API
+
+- **Swagger Documentation**: http://localhost:8000/docs
+- **ReDoc Documentation**: http://localhost:8000/redoc
+- **Health Check**: http://localhost:8000/health
+
+## API Endpoints
+
+### System Management
+
+- `GET /health` - Health check
+- `POST /initialize` - Initialize API with configuration
+- `GET /info` - Get system information
+
+### Projects
+
+- `POST /projects` - Create a new project
+- `GET /projects` - List projects (optionally filtered by owner)
+
+### Socratic Questions
+
+- `POST /projects/{project_id}/question` - Get a Socratic question
+- `POST /projects/{project_id}/response` - Process user response
+
+### Code Generation
+
+- `POST /code/generate` - Generate code for a project
+
+## Usage Examples
+
+### Initialize the API
+
+```bash
+curl -X POST http://localhost:8000/initialize \
+  -H "Content-Type: application/json" \
+  -d '{"api_key": "sk-ant-..."}'
+```
+
+### Create a Project
+
+```bash
+curl -X POST http://localhost:8000/projects \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Python API Development",
+    "owner": "alice",
+    "description": "Building REST APIs with FastAPI"
+  }'
+```
+
+### List Projects
+
+```bash
+curl http://localhost:8000/projects
+```
+
+### Ask a Socratic Question
+
+```bash
+curl -X POST http://localhost:8000/projects/proj_abc123/question \
+  -H "Content-Type: application/json" \
+  -d '{
+    "topic": "REST API design",
+    "difficulty_level": "intermediate"
+  }'
+```
+
+### Process a Response
+
+```bash
+curl -X POST http://localhost:8000/projects/proj_abc123/response \
+  -H "Content-Type: application/json" \
+  -d '{
+    "question_id": "q_xyz789",
+    "user_response": "REST APIs should follow resource-oriented design principles...",
+    "project_id": "proj_abc123"
+  }'
+```
+
+### Generate Code
+
+```bash
+curl -X POST http://localhost:8000/code/generate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "project_id": "proj_abc123",
+    "specification": "Create a FastAPI endpoint for user registration",
+    "language": "python"
+  }'
+```
+
+## Python Client Example
+
+```python
+import requests
+import json
+
+BASE_URL = "http://localhost:8000"
+
+# Initialize
+resp = requests.post(f"{BASE_URL}/initialize", json={
+    "api_key": "sk-ant-..."
+})
+print(resp.json())
+
+# Create project
+resp = requests.post(f"{BASE_URL}/projects", json={
+    "name": "My Project",
+    "owner": "alice",
+    "description": "Learning FastAPI"
+})
+project = resp.json()
+project_id = project["project_id"]
+
+# Get a question
+resp = requests.post(f"{BASE_URL}/projects/{project_id}/question", json={
+    "topic": "FastAPI basics",
+    "difficulty_level": "beginner"
+})
+question = resp.json()
+print(f"Question: {question['question']}")
+
+# Process response
+resp = requests.post(f"{BASE_URL}/projects/{project_id}/response", json={
+    "question_id": question["question_id"],
+    "user_response": "FastAPI is a modern Python web framework...",
+    "project_id": project_id
+})
+feedback = resp.json()
+print(f"Feedback: {feedback['feedback']}")
+```
+
+## Async Integration Example
+
+The API is built with FastAPI and uses asyncio internally. For high-throughput scenarios:
+
+```python
+import asyncio
+import httpx
+
+async def main():
+    async with httpx.AsyncClient() as client:
+        # Initialize
+        resp = await client.post("http://localhost:8000/initialize", json={
+            "api_key": "sk-ant-..."
+        })
+        print(resp.json())
+
+        # Create multiple projects concurrently
+        tasks = [
+            client.post("http://localhost:8000/projects", json={
+                "name": f"Project {i}",
+                "owner": "alice"
+            })
+            for i in range(5)
+        ]
+
+        results = await asyncio.gather(*tasks)
+        for r in results:
+            print(r.json())
+
+asyncio.run(main())
+```
+
+## Event Integration
+
+The API automatically registers event listeners with the Socrates library. Events are logged and can be monitored via the logging system:
+
+```python
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("socrates_api.main")
+
+# API will log events like:
+# [Event] PROJECT_CREATED: {'project_id': 'proj_abc123', ...}
+# [Event] CODE_GENERATED: {'lines': 150, ...}
+# [Event] AGENT_ERROR: {'agent_name': 'code_generator', ...}
+```
+
+## Configuration
+
+The API respects these environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ANTHROPIC_API_KEY` | None | Claude API key (required) |
+| `SOCRATES_DATA_DIR` | `~/.socrates` | Directory for storing data |
+| `SOCRATES_API_HOST` | `127.0.0.1` | Server host |
+| `SOCRATES_API_PORT` | `8000` | Server port |
+| `SOCRATES_API_RELOAD` | `false` | Enable auto-reload in development |
+
+## Error Handling
+
+The API returns structured error responses:
+
+```json
+{
+  "error": "ProjectNotFoundError",
+  "message": "Project 'proj_abc123' not found",
+  "error_code": "PROJECT_NOT_FOUND",
+  "details": {"project_id": "proj_abc123"}
+}
+```
+
+All Socrates library errors are caught and returned with appropriate HTTP status codes.
+
+## Deployment
+
+### Using Gunicorn (Production)
+
+```bash
+pip install gunicorn
+gunicorn -w 4 -k uvicorn.workers.UvicornWorker socrates_api.main:app
+```
+
+### Using Docker
+
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+
+RUN pip install socrates-api
+
+ENV SOCRATES_API_HOST=0.0.0.0
+
+CMD ["socrates-api"]
+```
+
+```bash
+docker build -t socrates-api .
+docker run -e ANTHROPIC_API_KEY="sk-ant-..." -p 8000:8000 socrates-api
+```
+
+### Using Docker Compose
+
+```yaml
+version: '3.8'
+
+services:
+  socrates-api:
+    build: .
+    ports:
+      - "8000:8000"
+    environment:
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
+      SOCRATES_DATA_DIR: /data
+    volumes:
+      - socrates_data:/data
+
+volumes:
+  socrates_data:
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/Nireus79/Socrates
+cd socrates-api
+pip install -e ".[dev]"
+```
+
+### Run Tests
+
+```bash
+pytest tests/ -v --cov=socrates_api
+```
+
+### Run in Development Mode
+
+```bash
+export SOCRATES_API_RELOAD=true
+socrates-api
+```
+
+## API Response Examples
+
+### Successful Project Creation
+
+```json
+{
+  "project_id": "proj_abc123",
+  "name": "Python API Development",
+  "owner": "alice",
+  "description": "Building REST APIs with FastAPI",
+  "phase": "active",
+  "created_at": "2025-12-04T10:00:00Z",
+  "updated_at": "2025-12-04T10:30:00Z",
+  "is_archived": false
+}
+```
+
+### Successful Question Generation
+
+```json
+{
+  "question_id": "q_xyz789",
+  "question": "What are the main principles of RESTful API design?",
+  "context": "You are designing an API for a tutoring system",
+  "hints": [
+    "Think about resource-oriented design",
+    "Consider HTTP methods and status codes"
+  ]
+}
+```
+
+### Successful Code Generation
+
+```json
+{
+  "code": "@app.post('/api/users/register')\nasync def register_user(user: User):\n    # Implementation here",
+  "explanation": "This endpoint handles user registration using FastAPI...",
+  "language": "python",
+  "token_usage": {
+    "input_tokens": 150,
+    "output_tokens": 200,
+    "total_tokens": 350
+  }
+}
+```
+
+## Architecture
+
+The API is built on three layers:
+
+1. **FastAPI Application** (`main.py`) - HTTP request handling, routing, and middleware
+2. **Pydantic Models** (`models.py`) - Request/response validation and serialization
+3. **Socrates Library** - Business logic via `socrates` package
+
+Event flow:
+```
+HTTP Request → FastAPI Route → Socrates Library → Event Emission → HTTP Response
+                                      ↓
+                              Event Listeners (Logging)
+```
+
+## Monitoring
+
+The API emits events for all significant operations. Monitor them via logging:
+
+```python
+import logging
+logging.basicConfig(level=logging.INFO)
+
+# All events will be logged like:
+# [Event] PROJECT_CREATED: {...}
+# [Event] AGENT_COMPLETE: {...}
+# [Event] TOKEN_USAGE: {...}
+```
+
+Or set up custom event listeners by extending the API:
+
+```python
+def setup_monitoring(orchestrator):
+    def on_token_usage(event_type, data):
+        # Send to monitoring system
+        send_metrics(data)
+
+    orchestrator.event_emitter.on(socrates.EventType.TOKEN_USAGE, on_token_usage)
+```
+
+## Support
+
+For issues, feature requests, or contributions, visit:
+- GitHub: https://github.com/Nireus79/Socrates
+- Issues: https://github.com/Nireus79/Socrates/issues
+- Documentation: https://socrates-ai.readthedocs.io
+
+## License
+
+MIT

socrates_ai_api-1.3.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+socrates_api/__init__.py,sha256=tTlDYmdp0cBdwyuMhyejW1zoXwB6Rp-O2PM3bTTYGLg,350
+socrates_api/database.py,sha256=8iajRBwFYCERNFxKhR-j6O42v7TPOFUSps_MES82p0c,3524
+socrates_api/main.py,sha256=kZP2RLLJWd5DCLoCO4CRu9HUQjj2-EPK2CdKOnyDUQA,28762
+socrates_api/models.py,sha256=a65fxK4_AItW0BX7UTLJ7EjnOh2nnAeZdwKJLbZzttA,33098
+socrates_api/monitoring.py,sha256=ASHdvIY3cfxrjzR9c5TMyrrRNJxtx96damcAt0Py77E,7436
+socrates_api/testing_mode.py,sha256=2XOHoBQmddzbQqnP7NxlqsB5kIXZqeplyjIc5TJSpNo,2124
+socrates_ai_api-1.3.0.dist-info/METADATA,sha256=5ZgJBrBlCbE9wq_ONh78PVYLIyOnZKeiLqXXtn03y-Y,11185
+socrates_ai_api-1.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+socrates_ai_api-1.3.0.dist-info/entry_points.txt,sha256=NcpMmQfZl4AtovX68-rcj86nLeqgnHRt1_X1XL7qDeA,55
+socrates_ai_api-1.3.0.dist-info/top_level.txt,sha256=U_unXaqUsRAcq2XypQQrO6ZIjSsMw67BL2hD5c1L9bE,13
+socrates_ai_api-1.3.0.dist-info/RECORD,,

socrates_ai_api-1.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

socrates_ai_api-1.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+socrates-api = socrates_api.main:run

socrates_ai_api-1.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+socrates_api

socrates_api/__init__.py

@@ -0,0 +1,12 @@
+"""
+Socrates API - REST API server for Socrates AI
+
+A FastAPI-based REST API that provides access to the Socrates AI tutoring system.
+Enables integration with web frontends, mobile apps, and custom clients.
+"""
+
+__version__ = "0.5.0"
+__author__ = "Socrates AI Contributors"
+__license__ = "MIT"
+
+__all__ = ["__version__", "__author__", "__license__"]

socrates_api/database.py

@@ -0,0 +1,118 @@
+"""
+Unified database singleton for both CLI and API.
+
+This module provides the DatabaseSingleton class that ensures both CLI
+(orchestrator) and API use the same database instance, preventing data
+corruption from dual database access.
+
+All components should use DatabaseSingleton.get_instance() to access the database.
+"""
+
+import logging
+import os
+from pathlib import Path
+
+from socratic_system.database import ProjectDatabase
+
+logger = logging.getLogger(__name__)
+
+
+class DatabaseSingleton:
+    """
+    Unified database singleton for CLI + API.
+
+    Ensures both the orchestrator and API use the same database instance,
+    preventing data inconsistencies from accessing different databases.
+    """
+
+    _instance: ProjectDatabase = None
+    _db_path: str = None
+
+    @classmethod
+    def initialize(cls, db_path: str = None) -> None:
+        """
+        Initialize the database singleton with a specific path.
+
+        Should be called once at application startup (before get_instance is used).
+
+        Args:
+            db_path: Path to projects.db. If None, uses environment or default.
+        """
+        if db_path:
+            cls._db_path = db_path
+        else:
+            # Get from environment or use default
+            data_dir = os.getenv("SOCRATES_DATA_DIR", str(Path.home() / ".socrates"))
+            Path(data_dir).mkdir(parents=True, exist_ok=True)
+            cls._db_path = os.path.join(data_dir, "projects.db")
+
+        # Reset instance so next get_instance() call creates new one with new path
+        cls._instance = None
+
+    @classmethod
+    def get_instance(cls) -> ProjectDatabase:
+        """
+        Get or create the global database instance.
+
+        This is used by both CLI (orchestrator) and API to ensure
+        they access the same database.
+
+        Returns:
+            ProjectDatabase: The shared database instance
+        """
+        if cls._instance is None:
+            # Initialize path if not already done
+            if cls._db_path is None:
+                cls.initialize()
+
+            # Create database instance
+            try:
+                cls._instance = ProjectDatabase(cls._db_path)
+                logger.info(f"Database singleton initialized at {cls._db_path}")
+            except Exception as e:
+                logger.error(f"Failed to initialize database: {e}")
+                raise
+
+        return cls._instance
+
+    @classmethod
+    def reset(cls) -> None:
+        """Reset the singleton (for testing purposes)"""
+        cls._instance = None
+        cls._db_path = None
+
+
+# FastAPI dependency that uses the singleton
+def get_database() -> ProjectDatabase:
+    """
+    FastAPI dependency that gets the shared database instance.
+
+    Returns:
+        ProjectDatabase: The shared database instance from DatabaseSingleton
+    """
+    return DatabaseSingleton.get_instance()
+
+
+def close_database() -> None:
+    """
+    Close the global database connection.
+
+    This should be called during application shutdown to properly clean up
+    database connections.
+    """
+    # DatabaseSingleton.reset() clears the cached instance
+    try:
+        DatabaseSingleton.reset()
+        logger.info("Database connection closed")
+    except Exception as e:
+        logger.error(f"Error closing database: {e}")
+
+
+def reset_database() -> None:
+    """
+    Reset the database instance (mainly for testing).
+
+    This closes the current connection and clears the cached instance,
+    forcing a new connection to be created on the next request.
+    """
+    close_database()