This project has been archived by its maintainers, and is no longer receiving any updates.
Socrates AI LangGraph Integration
Framework-agnostic Socratic AI agent integration for LangGraph
This library provides seamless integration between Socrates AI components and LangGraph, enabling you to build sophisticated multi-agent workflows with Socratic method guidance, knowledge retrieval, and unified event management.
Features
🤖 LangGraph Integration - Build workflows with Socratic agents as LangGraph nodes 📚 Knowledge Retrieval - Integrated RAG capabilities (optional) 🎓 Socratic Guidance - Ask better questions, not just provide answers ⚡ Framework Agnostic - Swap LangGraph for other orchestrators easily 🔄 Event System - Unified event handling across all agents 💾 State Management - Pydantic-based state with type safety
Installation
# Core integration
pip install socrates-ai-langraph
# With agent support
pip install "socrates-ai-langraph[agents]"
# With RAG support
pip install "socrates-ai-langraph[rag]"
# Everything
pip install "socrates-ai-langraph[full]"
Quick Start
from langgraph.graph import StateGraph, START, END
from socrates_ai_langraph import create_socrates_langgraph_workflow, AgentState
# Create workflow
workflow = create_socrates_langgraph_workflow()
app = workflow.compile()
# Run
initial_state = AgentState(input="Help me design a REST API")
result = app.invoke(initial_state)
print(result.messages)
print(result.results)
Architecture
LangGraph StateGraph
↓
├─ analyze_node (uses CodeAnalysisAgent)
├─ retrieve_node (uses KnowledgeRetrievalAgent)
├─ generate_node (uses CodeGenerationAgent)
└─ synthesize_node (aggregates results)
↓
Socrates Components:
├─ SocraticConfig (unified configuration)
├─ EventEmitter (unified events)
└─ Socratic Libraries (optional):
├─ socratic-agents
├─ socratic-rag
└─ socratic-learning
API Reference
State Classes
AgentState(BaseModel)
from socrates_ai_langraph import AgentState
state = AgentState(
input="Your task here",
messages=["Message 1", "Message 2"],
results={"key": "value"},
errors=[]
)
Workflow Creation
create_socrates_langgraph_workflow(config: Optional[SocratesConfig] = None) -> StateGraph
Create a pre-configured LangGraph workflow with Socratic agents.
from socrates_ai_langraph import create_socrates_langgraph_workflow
workflow = create_socrates_langgraph_workflow()
app = workflow.compile()
result = app.invoke(initial_state)
Agent Classes
CodeAnalysisAgent
Analyzes code for complexity, issues, and improvements.
from socrates_ai_langraph import CodeAnalysisAgent
agent = CodeAnalysisAgent()
result = agent.analyze("def example(): pass")
# Returns: {"complexity": "low", "issues": [], "suggestions": [...]}
CodeGenerationAgent
Generates code based on prompts.
from socrates_ai_langraph import CodeGenerationAgent
agent = CodeGenerationAgent()
code = agent.generate("Create a Python function for data validation")
KnowledgeRetrievalAgent
Retrieves relevant knowledge (requires socratic-rag).
from socrates_ai_langraph import KnowledgeRetrievalAgent
agent = KnowledgeRetrievalAgent()
docs = agent.retrieve("How to implement authentication?")
Configuration
Environment Variables
# Required for LLM features
export ANTHROPIC_API_KEY="sk-ant-..."
# Optional
export SOCRATIC_MODEL="claude-opus-4-5"
export SOCRATIC_TEMPERATURE="0.7"
Programmatic Configuration
from socratic_core import SocratesConfig
from socrates_ai_langraph import create_socrates_langgraph_workflow
config = SocratesConfig(
model="claude-opus-4-5",
temperature=0.7
)
workflow = create_socrates_langgraph_workflow(config)
Advanced Usage
Custom Workflow
from langgraph.graph import StateGraph, START, END
from socrates_ai_langraph import AgentState, CodeAnalysisAgent
# Create custom workflow
workflow = StateGraph(AgentState)
# Add your nodes
def my_node(state: AgentState) -> AgentState:
analyzer = CodeAnalysisAgent()
state.results["analysis"] = analyzer.analyze(state.input)
return state
workflow.add_node("analyze", my_node)
workflow.add_edge(START, "analyze")
workflow.add_edge("analyze", END)
# Compile and run
app = workflow.compile()
result = app.invoke(AgentState(input="def example(): pass"))
Event Listening
from socrates_core import EventType
from socrates_ai_langraph import create_socrates_langgraph_workflow, get_config
config = get_config()
workflow = create_socrates_langgraph_workflow(config)
# Listen to events
@config.emitter.on(EventType.AGENT_START)
def on_agent_start(data):
print(f"Agent starting: {data}")
@config.emitter.on(EventType.AGENT_COMPLETE)
def on_agent_complete(data):
print(f"Agent complete: {data}")
# Run workflow
app = workflow.compile()
result = app.invoke(initial_state)
Examples
Example 1: Code Review Workflow
from socrates_ai_langraph import create_socrates_langgraph_workflow, AgentState
# Create workflow
workflow = create_socrates_langgraph_workflow()
app = workflow.compile()
# Review code
code = """
def process_data(data):
result = []
for item in data:
result.append(item * 2)
return result
"""
state = AgentState(input=code)
result = app.invoke(state)
print("Analysis:", result.results.get("analysis"))
print("Suggestions:", result.messages)
Example 2: Generate and Improve
from socrates_ai_langraph import CodeGenerationAgent, CodeAnalysisAgent, AgentState
# Generate code
generator = CodeGenerationAgent()
code = generator.generate("Create a fibonacci function")
# Analyze it
analyzer = CodeAnalysisAgent()
analysis = analyzer.analyze(code)
# Improve based on feedback
state = AgentState(
input=f"Improve this code based on: {analysis['suggestions']}",
results={"original_code": code, "analysis": analysis}
)
Comparison with Other Frameworks
| Feature | LangGraph | Openclaw | CrewAI | AutoGen |
|---|---|---|---|---|
| Socratic Method | ✅ Via socrates-ai-langraph | ✅ Built-in | ❌ | ❌ |
| RAG Support | ✅ Optional | ✅ Built-in | ✅ | ❌ |
| State Management | ✅ Pydantic | ⚠️ Custom | ⚠️ Custom | ❌ |
| Async Support | ✅ Full | ✅ Full | ✅ Full | ⚠️ Limited |
| Framework Agnostic | ✅ Yes | ❌ No | ❌ No | ❌ No |
| Type Safe | ✅ Yes | ⚠️ Partial | ❌ No | ❌ No |
Migration
From langgraph-socrates (if exists)
# Old import
from langgraph_socrates import create_workflow
# New import (if different)
from socrates_ai_langraph import create_socrates_langgraph_workflow
From Direct LangGraph (without Socratic)
# Before: Custom agent implementation
class MyAgent:
def run(self, input_data):
# Custom implementation
pass
# After: Use built-in Socratic agents
from socrates_ai_langraph import CodeAnalysisAgent
agent = CodeAnalysisAgent()
result = agent.analyze(input_data)
Testing
# Run all tests
pytest
# With coverage
pytest --cov=socrates_ai_langraph
# Specific test
pytest tests/test_agents.py -v
Troubleshooting
Import Errors
# Error: ModuleNotFoundError: No module named 'langgraph'
# Solution:
pip install langgraph
# Error: ModuleNotFoundError: No module named 'socratic_core'
# Solution:
pip install socratic-core
Agent Not Initialized
# Error: Agent has no attribute 'run'
# Solution: Make sure to initialize config first
from socrates_ai_langraph import create_socrates_langgraph_workflow
workflow = create_socrates_langgraph_workflow()
State Serialization
# Use Pydantic models for all state
from socrates_ai_langraph import AgentState
# ✅ Good
state = AgentState(input="...", results={"key": "value"})
# ❌ Bad
state = {"input": "...", "results": {"key": "value"}}
Contributing
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Write tests
- Submit a pull request
See CONTRIBUTING.md for details.
Support
- GitHub Issues: Report bugs
- Discussions: Ask questions
- Documentation: Full docs
- Email: support@socrates-ai.dev
License
MIT License - see LICENSE file
Acknowledgments
Built with:
- LangGraph - Graph-based orchestration
- socratic-core - Foundation framework
- Anthropic Claude - LLM
- Socratic method philosophy
Made with ❤️ for developers who believe in learning through questions
Metadata
Release files for socrates-ai-langraph 0.1.0
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 |
|---|---|---|---|---|
| socrates_ai_langraph-0.1.0.tar.gz | 11.6 kB | Without provenance | Details for socrates_ai_langraph-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| socrates_ai_langraph-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for socrates_ai_langraph-0.1.0-py3-none-any.whl |
Total release size: 20.7 kB
Release files / socrates_ai_langraph-0.1.0.tar.gz
| Download URL | socrates_ai_langraph-0.1.0.tar.gz |
|---|---|
| Size | 11.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ea003557f6e0536188e555c1b6a996bc00d09f33561dcd842e56439607d600c5
|
|
BLAKE2b-256 checksum How to use checksums |
3c34f76c6bca87c3a1df7e23b655cf29f0b5476f62a7678c5645c27a8a563695
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / socrates_ai_langraph-0.1.0-py3-none-any.whl
| Download URL | socrates_ai_langraph-0.1.0-py3-none-any.whl |
|---|---|
| Size | 9.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
69e108200405e8b42e8132e0ccfe323c06d10c251e79250d655bc07c47968a8e
|
|
BLAKE2b-256 checksum How to use checksums |
a5afdaaed448eebe7f9ae0ea8c335951b01d156196719556635bca66b7795224
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Security for socrates-ai-langraph 0.1.0
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.