socrates-core-api 0.1.0__tar.gz

socrates_core_api-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Socrates Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

socrates_core_api-0.1.0/PKG-INFO

@@ -0,0 +1,453 @@
+Metadata-Version: 2.4
+Name: socrates-core-api
+Version: 0.1.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
+License-File: LICENSE
+Requires-Dist: socratic-core>=0.1.1
+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: full
+Requires-Dist: socratic-analyzer>=0.1.0; extra == "full"
+Requires-Dist: socratic-knowledge>=0.1.0; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.1.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"
+Dynamic: license-file
+
+# socrates-api
+
+REST API server for the Socrates AI platform. Provides a complete API for programmatic access to Socrates functionality.
+
+## 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