Socratic Analyzer

Status: Independent library extracted from Socrates monolith (v0.1.5)

Code analysis and workflow optimization library for project development, quality assessment, and architectural insights. Part of the Socratic Ecosystem.

Overview

Socratic Analyzer provides tools for analyzing project workflows, assessing code complexity, tracking maturity, and identifying optimization opportunities.

Key Capabilities

• Workflow Analysis - Analyze project workflows and process paths
• Complexity Metrics - Calculate workflow costs and identify bottlenecks
• Code Validation - Validate dependencies, syntax, and test execution
• Project Context - Model projects with phases, team structure, and maturity tracking
• Quality Assessment - Track project maturity across phases and categories
• Insight Categorization - Categorize insights and recommendations by workflow phase

Architecture

Core Modules

Workflow Analysis:

• WorkflowCostCalculator - Calculate execution costs of workflow paths
• WorkflowPathFinder - Discover optimal workflow paths
• WorkflowRiskCalculator - Assess risks in workflow execution

Code Quality:

• InsightCategorizer - Categorize insights by phase and workflow
• DependencyValidator - Validate project dependencies
• SyntaxValidator - Validate code syntax
• TestExecutor - Execute and track test results

Data Models:

• ProjectContext - Complete project information and state
• TeamMemberRole - Team member roles and skills
• WorkflowDefinition - Workflow paths and execution states

Analytics:

• AnalyticsCalculator - Calculate metrics from project data
• MaturityCalculator - Assess project maturity
• TokenUsage - Track LLM usage and costs

Installation

# Basic installation
pip install socratic-analyzer

# With framework integrations
pip install socratic-analyzer[langchain]
pip install socratic-analyzer[nexus]

# Development
pip install socratic-analyzer[dev]

Dependencies

Core:

• socratic-maturity>=0.1.1 - Maturity tracking and assessment
• socratic-nexus>=0.3.6 - Multi-provider LLM integration

Optional:

• langchain>=0.1.0 - LangChain integration
• langgraph>=0.0.1 - Graph-based workflows

Quick Start

Analyze a Project

from socratic_analyzer.models import ProjectContext
from socratic_analyzer.core import WorkflowCostCalculator

# Create project context
project = ProjectContext(
    project_id="proj-123",
    name="MyProject",
    owner="user@example.com",
    phase="analysis",
    created_at=datetime.now(),
    updated_at=datetime.now()
)

# Analyze workflow costs
calculator = WorkflowCostCalculator()
costs = calculator.calculate_workflow_costs(project)
print(f"Estimated cost: {costs}")

Validate Code Dependencies

from socratic_analyzer.utils.validators import DependencyValidator

validator = DependencyValidator()

# Check dependency compatibility
issues = validator.validate_dependencies("./requirements.txt")
for issue in issues:
    print(f"Issue: {issue['type']} - {issue['message']}")

Track Project Maturity

from socratic_analyzer.maturity_calculator import MaturityCalculator

calculator = MaturityCalculator()

# Calculate overall maturity
maturity = calculator.calculate_maturity(project)
print(f"Project maturity: {maturity.overall_score}%")
print(f"Phase scores: {maturity.phase_maturity_scores}")

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=src/socratic_analyzer

# Run specific tests
pytest tests/test_module_imports.py -v

Current Coverage: 15.76% (import verification tests) Required Threshold: 5% ✅

Code Quality

All checks passing:

• ✅ Black formatting
• ✅ Ruff linting
• ✅ Mypy type checking (pragmatic for extracted library)

Configuration Examples

Workflow Analysis

from socratic_analyzer.models import WorkflowDefinition, WorkflowNode, WorkflowEdge

# Define workflow
workflow = WorkflowDefinition(
    workflow_id="wf-123",
    name="Analysis Workflow",
    description="Project analysis process",
    nodes=[
        WorkflowNode(id="start", name="Start", node_type="start"),
        WorkflowNode(id="analysis", name="Analysis", node_type="process"),
        WorkflowNode(id="review", name="Review", node_type="process"),
        WorkflowNode(id="end", name="End", node_type="end"),
    ],
    edges=[
        WorkflowEdge(source="start", target="analysis", cost=10),
        WorkflowEdge(source="analysis", target="review", cost=15),
        WorkflowEdge(source="review", target="end", cost=5),
    ]
)

Documentation

• ARCHITECTURE.md - System design and component overview
• API Reference - Complete API documentation (when available)
• Integration Guide - How to integrate with other systems

Part of the Socratic Ecosystem

Socratic Analyzer integrates with:

• Socratic Nexus - Multi-provider LLM client
• Socratic Maturity - Maturity tracking (dependency)
• Socratic Agents - Agent orchestration (optional)
• Socratic Learning - Learning patterns (optional)

See Socratic Ecosystem for complete overview.

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - See LICENSE for details.

Support

• Issues: https://github.com/Nireus79/Socratic-analyzer/issues
• Documentation: https://github.com/Nireus79/Socratic-analyzer/tree/main/docs

---

Built as part of the Socratic ecosystem

Made by @Nireus79

---

Part of Socrates AI Ecosystem

This package is a component of Socrates AI, a production-ready platform for building intelligent multi-agent systems with constitutional governance.

Use This Package Standalone:

pip install socratic-analyzer

Or As Part of Socrates Platform:

pip install socrates-ai  # Includes 37+ modules + all 11 packages

Integration Example:

See the Socrates ECOSYSTEM.md for detailed integration examples showing how to use socratic-analyzer with other Socratic packages.

Related packages you might use together:

• See Complete Package Map

More Information:

• 📖 Full Socrates Documentation
• 🏗️ Complete Architecture Guide
• 💬 Socrates Discussions

---