Skip to main content

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.

License Python 3.9+

Features

  • Multi-Provider Support: Works with Anthropic (Claude), OpenAI (GPT-4), Google (Gemini), Ollama, and HuggingFace
  • Unified Interface: Consistent API across all providers
  • Async/Sync Support: Full async/await support with optional synchronous API
  • Token Tracking: Built-in token usage monitoring and cost estimation
  • Caching: Intelligent response caching with optional Redis support
  • Type Safe: Full type hints with mypy support
  • 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
insights = client.extract_insights(
    "Why is photosynthesis important for Earth's ecosystem?",
    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
client = OllamaClient(base_url="http://localhost:11434")

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 generation
  • generate_code() - Code generation
  • extract_insights() - Extract key insights
  • generate_documentation() - Create documentation
  • generate_business_plan() - Business planning
  • generate_curriculum() - Learning curriculum design
  • generate_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:

# Generate a response to a prompt
response = client.generate_response(
    prompt: str,
    max_tokens: int = 1024,
    temperature: float = 0.7
) -> str

# Generate code from specifications
code = client.generate_code(
    specification: str,
    language: str = "python"
) -> str

# Extract key insights from text
insights = client.extract_insights(
    text: str,
    project: Optional[ProjectContext] = None
) -> str

# Async variants
response = await client.generate_response_async(...)
code = await client.generate_code_async(...)
insights = await client.extract_insights_async(...)

Token Usage Tracking

Each response includes token usage information:

from socratic_nexus.clients import ClaudeClient

client = ClaudeClient(api_key="sk-ant-...")
response = client.generate_response("Your prompt here")

# Token information available in response metadata
print(f"Input tokens: {response.metadata.input_tokens}")
print(f"Output tokens: {response.metadata.output_tokens}")
print(f"Estimated cost: ${response.metadata.cost_usd}")

See docs/API_REFERENCE.md for complete API documentation.

Configuration

Environment Variables

Set provider API keys via environment variables:

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="..."

Then initialize clients without explicit keys:

from socratic_nexus.clients import ClaudeClient

# Reads from ANTHROPIC_API_KEY
client = ClaudeClient()

Client Configuration

from socratic_nexus.clients import ClaudeClient

client = ClaudeClient(
    api_key="sk-ant-...",
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    temperature=0.7,
    timeout=30
)

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

Performance

  • Response Caching: Configurable in-memory caching
  • Async Support: Non-blocking API calls for high concurrency
  • Connection Pooling: Efficient HTTP connection management
  • Retry Logic: Automatic retry with exponential backoff

Typical response times (with caching disabled):

  • Claude: 1-5s per request
  • GPT-4: 1-3s per request
  • Gemini: 500ms-2s per request
  • Ollama (local): 100ms-1s per request

Security

  • API Key Protection: Never logged or cached
  • HTTPS Only: All communication encrypted
  • No Request Logging: Sensitive data not persisted
  • Input Validation: All requests validated before sending

For security issues, please see SECURITY.md.

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass and coverage remains above 70%
  5. Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

License

MIT License - See LICENSE file for details.

Support

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.


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

Integration Example:

More Information:


Metadata

Release files for socratic-nexus 0.4.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for socratic-nexus 0.4.5
File Size Uploaded Provenance Actions
socratic_nexus-0.4.5.tar.gz 143.5 kB Without provenance Details for socratic_nexus-0.4.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for socratic-nexus 0.4.5
File Interpreter ABI Platform Actions
socratic_nexus-0.4.5-py3-none-any.whl Python 3 none any Details for socratic_nexus-0.4.5-py3-none-any.whl

Total release size: 202.5 kB

Release files / socratic_nexus-0.4.5.tar.gz

Download URL socratic_nexus-0.4.5.tar.gz
Size 143.5 kB
Tags Source
SHA-256 checksum
How to use checksums
d84a9e8689307c26658146c1705761efcea99192f538d95bb3e9818c348f5c89
BLAKE2b-256 checksum
How to use checksums
62bb7ad698f3d265eecca5dc4fec8173f8c09604040b6ff0c16ffaa96fbe97fd
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.5-py3-none-any.whl

Download URL socratic_nexus-0.4.5-py3-none-any.whl
Size 59.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
47fc676ab84df2ff76e392882d640f321ce78db9405682322e396e4913397628
BLAKE2b-256 checksum
How to use checksums
c1b9d30a87623cd78f72ebb9a84d5b93845f4824e88b9d72e30c0a3636e61925
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.5

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page