This project has been archived by its maintainers, and is no longer receiving any updates.
Socratic OpenClaw Skill - Modern Architecture
Socratic method discovery skill for OpenClaw using modern modular architecture
This is the modernized replacement for the deprecated socrates-ai-openclaw package. It uses the latest socratic-core library instead of the monolithic socrates-ai package.
Features
🎓 Socratic Discovery - Claude-guided questioning for project discovery 📚 RAG Knowledge Base - Vector embeddings with ChromaDB for context-aware responses 📊 Specification Generation - Auto-generate requirements, architecture, and project specs 💾 Session Persistence - Resume discoveries anytime 🔄 Multi-turn Conversations - Natural dialogue flow with context tracking ⚡ Production Ready - Built on battle-tested socratic-core library
Installation
pip install socratic-openclaw-skill
Quick Start
from socratic_openclaw_skill import SocraticDiscoverySkill
# Initialize the skill
skill = SocraticDiscoverySkill()
# Start a discovery session
result = await skill.start_discovery("AI-powered SaaS application")
print(result["question"])
# Output: "What problem does this solve for your target users?"
# Respond to the question
result = await skill.respond(result["session_id"], "Helps teams manage projects efficiently")
print(result["question"])
# Generate a specification
result = await skill.generate(result["session_id"])
print(result["spec"])
With OpenClaw
# Install OpenClaw
pip install openclaw
# Socratic discovery is automatically available
# Users can start a discovery session in their preferred channel
In OpenClaw chat:
User: "Help me plan a new project"
OpenClaw: "I'll guide you through Socratic discovery. Question 1: What problem does this solve?"
User: "Tracks team time efficiently"
OpenClaw: "Question 2: Who are your target users?"
... (continues for 5-8 turns)
User: "Generate a spec"
OpenClaw: "Here's your project specification..."
Architecture
User Input (OpenClaw)
↓
SocraticDiscoverySkill (Modern)
↓
├─ SessionManager (track sessions)
├─ QuestionEngine (generate questions)
├─ ResponseProcessor (handle answers)
├─ SpecGenerator (create specs)
└─ StorageHandler (persist data)
↓
socratic-core Library (Foundation)
↓
├─ SocratesConfig
├─ EventEmitter
├─ Exception hierarchy
└─ Logging infrastructure
↓
Claude API (LLM)
ChromaDB (RAG)
Configuration
Environment Variables
# Required
export ANTHROPIC_API_KEY="sk-ant-..."
# Optional
export SOCRATIC_MODEL="claude-opus-4-5"
export SOCRATIC_TEMPERATURE="0.7"
export SOCRATIC_WORKSPACE_ROOT="~/.openclaw/workspace"
Programmatic Configuration
from socratic_openclaw_skill import SocraticDiscoverySkill
from pathlib import Path
skill = SocraticDiscoverySkill(
workspace_root=Path.home() / ".openclaw" / "workspace",
model="claude-opus-4-5",
temperature=0.7
)
API Reference
SocraticDiscoverySkill
start_discovery(topic: str) -> Dict
Start a new Socratic discovery session.
Parameters:
topic(str): The project or concept to discover
Returns:
{
"status": "started",
"session_id": "discover_1234567890_abc",
"topic": "AI-powered expense tracker",
"question": "What problem does this solve?",
"progress": {"step": 1}
}
respond(session_id: str, response: str) -> Dict
Record user response and get next question.
Parameters:
session_id(str): Session ID from start_discoveryresponse(str): User's response to previous question
Returns:
{
"status": "question_asked",
"session_id": "discover_...",
"question": "Who is your target user?",
"progress": {"questions_asked": 2, "responses_recorded": 1}
}
generate(session_id: str) -> Dict
Generate project specification from discovery.
Parameters:
session_id(str): Session ID from start_discovery
Returns:
{
"status": "spec_generated",
"session_id": "discover_...",
"spec": "# Project Name\n\n## Overview\n...",
"saved_to": "~/.openclaw/workspace/projects/project-name/PROJECT.md",
"artifacts": ["PROJECT.md", "REQUIREMENTS.md", "ARCHITECTURE.md"]
}
Migration from socrates-ai-openclaw
The old socrates-ai-openclaw package is deprecated and broken. Use this package instead:
Before (Broken):
# ❌ BROKEN - depends on non-existent socrates-ai>=1.3.0
pip install socrates-ai-openclaw
Now (Works):
# ✅ WORKS - uses modern modular architecture
pip install socratic-openclaw-skill
Code Changes
# Old (broken)
from socrates_openclaw import SocraticDiscoverySkill
# New (works)
from socratic_openclaw_skill import SocraticDiscoverySkill
Storage
Projects are stored in your workspace directory:
~/.openclaw/workspace/
├── projects/
│ ├── project-name-1/
│ │ ├── PROJECT.md
│ │ ├── REQUIREMENTS.md
│ │ ├── ARCHITECTURE.md
│ │ └── .session-*.json
│ └── project-name-2/
├── .socrates-vectors/ (ChromaDB embeddings)
├── .socrates-kb/ (Knowledge base)
└── .socratic-sessions.json (Session tracking)
All data is stored locally - no cloud upload.
Troubleshooting
API Key Issues
# Error: Anthropic key not found
# Solution:
export ANTHROPIC_API_KEY="sk-ant-..."
# Or in code:
import os
os.environ["ANTHROPIC_API_KEY"] = "your-key"
Missing Dependencies
# If you get import errors:
pip install socratic-openclaw-skill[dev]
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
- Documentation: Full docs
- Email: support@socrates-ai.dev
License
MIT License - see LICENSE file
Acknowledgments
Built with:
- socratic-core - Foundation library
- Anthropic Claude - LLM
- ChromaDB - Vector storage
- OpenClaw - AI assistant platform
Made with ❤️ for the Socrates and OpenClaw communities
Metadata
Release files for socrates-ai-openclaw 0.1.1
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_openclaw-0.1.1.tar.gz | 9.1 kB | Without provenance | Details for socrates_ai_openclaw-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| socrates_ai_openclaw-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for socrates_ai_openclaw-0.1.1-py3-none-any.whl |
Total release size: 18.2 kB
Release files / socrates_ai_openclaw-0.1.1.tar.gz
| Download URL | socrates_ai_openclaw-0.1.1.tar.gz |
|---|---|
| Size | 9.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b83a811d63785bad2c4b43982796d84046010fd18d05ca2db6e926024203568b
|
|
BLAKE2b-256 checksum How to use checksums |
2cd0fa57c8bbed990caf10f4f5dd0382c5ddf6dd88dec46706a980ea6790809d
|
| 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_openclaw-0.1.1-py3-none-any.whl
| Download URL | socrates_ai_openclaw-0.1.1-py3-none-any.whl |
|---|---|
| Size | 9.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d2d34dbdf269d5374ab4c4f01cfa2763574f41e201977db309246b61dfddf737
|
|
BLAKE2b-256 checksum How to use checksums |
4a5b46c84023b3f1e982f042060d98e18907cd0b0f488ca83116bbe48657a508
|
| 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-openclaw 0.1.1
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.