Proof of concept, not a product. This library belongs to the earlier Python research prototype (Socrates) and is not maintained as a product. The current products are listed at nireus79.github.io. Contact: Hermes_creative@proton.me.
Socratic Nexus
A universal LLM client library providing unified access to multiple AI providers with a consistent interface.
Features
- Multi-Provider Support: Works with Anthropic (Claude), OpenAI (GPT-4), Google (Gemini), and Ollama
- Unified Interface: Consistent API across all providers
- Async/Sync Support: Full async/await support with optional synchronous API
- Token Tracking: token usage is recorded per call and emitted as an event when an orchestrator is attached
- Caching: in-memory caching of insight extraction
- No Lock-in: Easy to switch between providers without code changes
Installation
Basic Installation
pip install socratic-nexus
With Specific Providers
# Claude/Anthropic
pip install socratic-nexus[anthropic]
# OpenAI
pip install socratic-nexus[openai]
# Google Gemini
pip install socratic-nexus[google]
# Ollama (local LLMs)
pip install socratic-nexus[ollama]
# All providers
pip install socratic-nexus[all]
With Integrations
# LangChain support
pip install socratic-nexus[langchain]
# Everything
pip install socratic-nexus[full]
Quick Start
Using Claude (Anthropic)
from socratic_nexus.clients import ClaudeClient
# Initialize with API key
client = ClaudeClient(api_key="sk-ant-...")
# Generate a response
response = client.generate_response(
"Explain quantum computing in simple terms"
)
print(response)
# Generate code
code = client.generate_code(
"Create a Python function to calculate fibonacci numbers"
)
print(code)
# Extract insights (needs a ProjectContext; returns a dict)
from socratic_nexus.models import ProjectContext
insights = client.extract_insights(
"Why is photosynthesis important for Earth's ecosystem?",
ProjectContext(project_name="biology_study"),
)
print(insights)
Using OpenAI (GPT-4)
from socratic_nexus.clients import OpenAIClient
client = OpenAIClient(api_key="sk-...")
response = client.generate_response(
"What are the key principles of machine learning?"
)
print(response)
Using Google Gemini
from socratic_nexus.clients import GoogleClient
client = GoogleClient(api_key="...")
response = client.generate_response(
"Explain blockchain technology"
)
print(response)
Using Ollama (Local Models)
from socratic_nexus.clients import OllamaClient
# Ollama runs locally, no API key needed. Without an orchestrator it uses
# the model "mistral" at http://localhost:11434.
client = OllamaClient()
response = client.generate_response(
"What is the capital of France?"
)
print(response)
Async Usage
import asyncio
from socratic_nexus.clients import ClaudeClient
async def main():
client = ClaudeClient(api_key="sk-ant-...")
response = await client.generate_response_async(
"Explain the theory of relativity"
)
print(response)
asyncio.run(main())
Core Clients
ClaudeClient
Anthropic's Claude model with specialized methods:
generate_response()- General text generationgenerate_code()- Code generationextract_insights()- Extract key insightsgenerate_documentation()- Create documentationgenerate_business_plan()- Business planninggenerate_curriculum()- Learning curriculum designgenerate_research_protocol()- Research methodology- And 10+ more specialized generators
OpenAIClient
OpenAI's GPT models with:
- Cost calculation based on token usage
- Support for GPT-4, GPT-4 Turbo, GPT-3.5
- Configurable temperature and parameters
GoogleClient
Google's Gemini models with:
- Multi-modal support
- Advanced safety settings
- Model variant selection (pro, pro-vision)
OllamaClient
Local LLM support for:
- Running models locally without API keys
- Custom model selection
- Development and testing without cloud costs
Architecture
Socratic-nexus follows a layered architecture:
Application Code
↓
Client Layer (ClaudeClient, OpenAIClient, etc.)
↓
Provider Abstraction Layer
↓
Provider-Specific Implementations
↓
External LLM APIs
Each client:
- Handles provider-specific authentication
- Normalizes request/response formats
- Manages async/sync variants
- Tracks token usage and costs
- Implements caching and retry logic
See ARCHITECTURE.md for detailed architecture documentation.
API Reference
Base Client Interface
All clients implement these core methods:
client.generate_response(prompt: str, max_tokens: int = 2000, temperature: float = 0.7) -> str
client.generate_code(context: str) -> str
client.extract_insights(user_response: str, project: ProjectContext) -> dict
# Async variants
await client.generate_response_async(...)
await client.extract_insights_async(...)
await client.generate_code_async(...) # ClaudeClient only
All four clients also take user_auth_method and user_id; the extra generators (generate_documentation, generate_business_plan and others) are on ClaudeClient.
Token Usage Tracking
generate_response returns the reply text as a string. Token usage is not part of the return value; the client records it and, when an orchestrator with an event emitter is attached, emits a TOKEN_USAGE event (socratic_nexus.EventType.TOKEN_USAGE) after each call.
Configuration
Environment Variables
The clients take the key as an argument and do not read it from the environment themselves. Read it yourself:
import os
from socratic_nexus.clients import ClaudeClient
client = ClaudeClient(api_key=os.environ["ANTHROPIC_API_KEY"])
Client Configuration
The constructors take only api_key, orchestrator and subscription_token. Without an orchestrator the Claude client uses the model claude-haiku-4-5-20251001 and the Ollama client uses mistral at http://localhost:11434; with an orchestrator the model comes from its config (claude_model, ollama_model, ollama_url). max_tokens and temperature are arguments of generate_response.
Error Handling
from socratic_nexus.clients import ClaudeClient
from anthropic import APIError
try:
client = ClaudeClient(api_key="invalid-key")
response = client.generate_response("Test prompt")
except APIError as e:
print(f"API Error: {e}")
except Exception as e:
print(f"Unexpected error: {e}")
Testing
Run the test suite:
pytest tests/
With coverage:
pytest --cov=socratic_nexus tests/
Run specific test categories:
# Unit tests only
pytest -m unit
# Integration tests (requires API keys)
pytest -m integration
Security
For security issues, see SECURITY.md.
Contributing
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Ensure all tests pass and coverage remains above 70%
- Submit a pull request
See CONTRIBUTING.md for detailed guidelines.
License
MIT License - See LICENSE file for details.
Support
- Documentation: docs/
- GitHub Issues: Report bugs
- Discussions: Ask questions
Roadmap
- Support for additional providers (Cohere, Together AI, etc.)
- Function calling for all providers
- Streaming response support
- Advanced RAG integration
- Cost optimization features
- Rate limiting and quota management
Changelog
See CHANGELOG.md for release notes and version history.
Related Projects
- Socratic Nexus Agents - Agent framework built on socratic-nexus
- Socratic RAG - Retrieval-augmented generation
- Socratic Analyzer - Quality analysis and evaluation
Made with ❤️ for the AI community
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-nexus
Or As Part of Socrates Platform:
pip install socrates-ai # the earlier research prototype that uses this package
More Information:
Metadata
Release files for socratic-nexus 0.4.7
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_nexus-0.4.7.tar.gz | 143.1 kB | Without provenance | Details for socratic_nexus-0.4.7.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| socratic_nexus-0.4.7-py3-none-any.whl | Python 3 | none | any | Details for socratic_nexus-0.4.7-py3-none-any.whl |
Total release size: 201.9 kB
Release files / socratic_nexus-0.4.7.tar.gz
| Download URL | socratic_nexus-0.4.7.tar.gz |
|---|---|
| Size | 143.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7142fa0002ab7d5000827b64d851785c2632934526f7c2bd3515c369bce146bf
|
|
BLAKE2b-256 checksum How to use checksums |
1c93e04e234df9d29cb6d3facaa14af00aad02bffbf596a20a9b7723ca6e13b5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / socratic_nexus-0.4.7-py3-none-any.whl
| Download URL | socratic_nexus-0.4.7-py3-none-any.whl |
|---|---|
| Size | 58.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9469fb8dc22d29914447c250359ee5aeb284d62577fbba5269a63e4b3d8ceaca
|
|
BLAKE2b-256 checksum How to use checksums |
e9c897fe0474549f1678c4a148af7aac6a5241114a616030b2478fbb5bdddbf3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for socratic-nexus 0.4.7
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.