Metadata-Version: 2.4
Name: socratic-learning
Version: 0.1.2
Summary: Continuous learning system that tracks agent interactions, detects patterns, and provides improvement recommendations.
Author: Socratic Learning Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/Nireus79/Socratic-learning
Project-URL: Repository, https://github.com/Nireus79/Socratic-learning
Project-URL: Documentation, https://github.com/Nireus79/Socratic-learning#readme
Project-URL: Issues, https://github.com/Nireus79/Socratic-learning/issues
Keywords: learning,tracking,agent,pattern-detection,recommendations,fine-tuning,analytics,socratic
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Provides-Extra: agents
Requires-Dist: socratic-agents>=0.1.3; extra == "agents"
Provides-Extra: rag
Requires-Dist: socratic-rag>=0.1.0; extra == "rag"
Provides-Extra: workflow
Requires-Dist: socratic-workflow>=0.1.1; extra == "workflow"
Provides-Extra: nexus
Requires-Dist: socrates-nexus>=0.3.0; extra == "nexus"
Provides-Extra: openclaw
Provides-Extra: langchain
Requires-Dist: langchain>=0.1.0; extra == "langchain"
Provides-Extra: all
Requires-Dist: socratic-agents>=0.1.3; extra == "all"
Requires-Dist: socratic-rag>=0.1.0; extra == "all"
Requires-Dist: socratic-workflow>=0.1.1; extra == "all"
Requires-Dist: socrates-nexus>=0.3.0; extra == "all"
Requires-Dist: langchain>=0.1.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

# Socratic Learning

[![PyPI version](https://badge.fury.io/py/socratic-learning.svg)](https://badge.fury.io/py/socratic-learning)
[![Tests](https://github.com/Nireus79/Socratic-learning/workflows/Tests/badge.svg)](https://github.com/Nireus79/Socratic-learning/actions)
[![Code Quality](https://github.com/Nireus79/Socratic-learning/workflows/Code%20Quality/badge.svg)](https://github.com/Nireus79/Socratic-learning/actions)

## Why Socratic Learning?

Most AI platforms treat learning as an afterthought. Socratic Learning makes continuous improvement built-in:

- **Interaction Tracking** - Capture and store all agent interactions with full context for analysis
- **Pattern Detection** - Automatically identify recurring patterns in agent behaviors and model outputs
- **Performance Monitoring** - Track success rates, response times, and costs across all interactions
- **Data-Driven Recommendations** - Get actionable improvement suggestions based on detected patterns
- **Fine-Tuning Ready** - Export interaction data in industry-standard formats for model fine-tuning

A continuous learning system for AI agents that tracks interactions, detects patterns, and provides data-driven improvement recommendations.

## Features

- **Interaction Tracking** - Capture and store all agent interactions with context
- **Pattern Detection** - Identify recurring patterns in agent behaviors and LLM outputs
- **Performance Metrics** - Monitor agent effectiveness with success rates, response times, costs
- **User Feedback Integration** - Collect and analyze user feedback on agent responses
- **Learning Recommendations** - Generate actionable improvement suggestions
- **Fine-Tuning Export** - Export interaction data for model fine-tuning
- **Analytics & Reporting** - JSON-based insights and metrics
- **Framework Integration** - Works with Openclaw and LangChain

## Installation

```bash
# Core package
pip install socratic-learning

# With Socratic Agents integration
pip install socratic-learning[agents]

# With all optional dependencies
pip install socratic-learning[all]

# For development
pip install socratic-learning[dev]
```

## Quick Start

```python
from socratic_learning import LearningManager
from socratic_agents import SocraticCounselor

# Initialize learning manager
learning = LearningManager(storage="sqlite", db_path="learning.db")

# Create a tracking session
session_id = learning.create_session(
    user_id="user123",
    context={"environment": "production"}
)

# Track agent interactions
counselor = SocraticCounselor()
result = counselor.guide("recursion", level="beginner")

learning.track_interaction(
    session_id=session_id,
    agent_name="SocraticCounselor",
    input_data={"topic": "recursion", "level": "beginner"},
    output_data=result,
    model_name="claude-opus-4",
    provider="anthropic",
    input_tokens=150,
    output_tokens=500,
    duration_ms=1200.0,
)

# Add user feedback
learning.add_feedback(
    interaction_id=interaction.interaction_id,
    rating=5,
    feedback="Very helpful explanation!"
)

# Get metrics
metrics = learning.get_metrics(agent_name="SocraticCounselor")
print(f"Success rate: {metrics.success_rate}%")
print(f"Avg rating: {metrics.avg_rating}/5")

# Detect patterns
patterns = learning.detect_patterns(agent_name="SocraticCounselor")
for pattern in patterns:
    print(f"Pattern: {pattern.name} (confidence: {pattern.confidence})")

# Get recommendations
recommendations = learning.get_recommendations(agent_name="SocraticCounselor")
for rec in recommendations:
    print(f"Recommendation: {rec.title}")

# Export for fine-tuning
learning.export_for_finetuning(
    output_path="finetuning_data.jsonl",
    agent_name="SocraticCounselor",
    min_rating=4,
    format="openai"
)
```

## Core Concepts

### Interaction
Represents a single agent interaction with input, output, performance metrics, and optional user feedback.

### Pattern
A detected recurring pattern in agent behaviors (e.g., error patterns, topic-specific behaviors).

### Metric
Aggregated performance metrics (success rate, average response time, user satisfaction, costs).

### Recommendation
An actionable improvement suggestion based on detected patterns and metrics.

## Architecture

- **Core Models** - Dataclass-based models with serialization
- **Storage Layer** - Abstract interface with SQLite backend
- **Tracking** - Interaction logger with session management
- **Analytics** - Pattern detection and metrics collection
- **Integrations** - Openclaw skills and LangChain tools

## Documentation

- **[Maturity Calculation System](docs/MATURITY_CALCULATION_SYSTEM.md)** - Complete guide to the confidence-weighted maturity scoring system, including core algorithms, category definitions, and API reference
- See [examples/](examples/) for complete working examples

## Testing

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=src/socratic_learning --cov-report=html

# Run specific test file
pytest tests/unit/test_models.py -v
```

## Code Quality

```bash
# Format with Black
black src/ tests/

# Lint with Ruff
ruff check src/ tests/

# Type check with MyPy
mypy src/
```

## License

MIT

## Contributing

Contributions welcome! Please open an issue or submit a PR.

## Support Development

If you find this package useful, consider supporting development:

- [Become a Sponsor](https://github.com/sponsors/Nireus79) - Get early access to new features
- [Star on GitHub](https://github.com/Nireus79/Socratic-learning) - Shows your appreciation
- [Report Issues](https://github.com/Nireus79/Socratic-learning/issues) - Help improve the package

Your support helps fund development of the entire Socratic ecosystem.

## Status

**Phase 1** - Core foundation complete (v0.1.0 development)
- ✅ Core data models
- ✅ SQLite storage
- ✅ Unit tests
- 🚀 Phase 2-6 planned
