sokrates 0.4.1

A collection of tools for LLM interactions like prompt refinement and idea generation. It also provides a console chat client with speech to text feature.

sokrates

A collection of tools for LLM interactions and system monitoring, designed to facilitate working with Large Language Models (LLMs) through modular components, well-documented APIs, and production-ready utilities.

Table of Contents

• Description
• Installation
• Usage
  • Available Commands
  • Task Queuing System
• Features
• Contributing
• License
• Contact
• Changelog

Description

sokrates is a comprehensive framework for working with Large Language Models (LLMs). It provides:

• Advanced prompt refinement tools
• System monitoring for resource tracking during LLM operations
• An extensive CLI interface for rapid experimentation
• Modular components and well-documented APIs
• A task queue system for managing LLM processing tasks

The project includes utilities for:

• Managing configuration settings
• Interacting with OpenAI-compatible LLM APIs
• Processing and cleaning LLM-generated text
• Monitoring system resources in real-time
• Executing complex workflows for idea generation and prompt refinement
• Queuing and processing tasks reliably with persistence and error handling

Installation via pip

pip install sokrates

# or via uv
uv pip install sokrates

# test the installation
list-models --api-endpoint http://localhost:1234/v1

# or via uv
uv run list-models --api-endpoint http://localhost:1234/v1

Installation for development purposes

Prerequisites: Python 3.9 or higher

git clone https://github.com/Kubementat/sokrates.git
cd sokrates
uv sync

Configuration

You can configure the library via a configuration file in $HOME/.sokrates/.env

# Copy
cp .env.example $HOME/.sokrates/.env

# adjust to your needs
vim $HOME/.sokrates/.env

Whisper dependencies

brew install ffmpeg
brew install whisper-cpp

Usage

Basic Command Structure

Most commands follow this structure:

command --option1 value1 --option2 value2

You can always display the help via:

command --help

e.g.

uv run list-models --help

Available Commands

• sokrates-benchmark-model: Benchmark LLM models
• sokrates-benchmark-results-merger: Merge benchmark results
• sokrates-benchmark-results-to-markdown: Convert benchmark results to markdown
• sokrates-execute-tasks: Executes a list of tasks sequentially from a given task list in JSON format (generated by breakdown_task)
• sokrates-fetch-to-md: Fetch content and convert to markdown
• sokrates-generate-mantra: Generate mantras or affirmations
• sokrates-list-models: List available LLM models
• sokrates-idea-generator: Generate ideas using a multi-stage workflow
• sokrates-refine-and-send-prompt: Refine and send prompts to an LLM
• sokrates-refine-prompt: Refine prompts for better LLM performance
• sokrates-breakdown-task: Break down complex tasks into manageable steps
• sokrates-send-prompt: Send a prompt to an LLM API
• sokrates-chat: Chat with LLMs via the command line

Task Queuing System

The task queue system allows you to queue LLM processing tasks in JSON format for reliable execution:

# Add a new task to the queue
sokrates-task-add tasks/new_task.json --priority high

# List all queued tasks
sokrates-task-list --status pending --priority high

# Get detailed status of specific task
sokrates-task-status task-123 --verbose

# Remove a task from the queue
sokrates-task-remove task-789 --force

# Start the daemon to process queued tasks
sokrates-daemon start

# Restart the daemon
sokrates-daemon restart

# Stop the daemon
sokrates-daemon stop

Example Usage

# Getting help for a command and usage instructions
uv run sokrates-refine-prompt --help

# List available models
uv run sokrates-list-models --api-endpoint http://localhost:1234/v1

# Generate ideas
uv run sokrates-idea-generator --output-directory tmp/ideas --verbose

# Benchmark a model
uv run sokrates-benchmark-model --model qwen/qwen3-8b --iterations 5

# Start the task queue daemon
sokrates-daemon start

Features

• Prompt Refinement: Optimize LLM input/output with advanced refinement tools
• System Monitoring: Real-time tracking of resource usage during LLM operations
• CLI Interface: Extensive command-line tools for rapid experimentation
• Modular Architecture: Easily extendable and customizable components
• Task Queue System: Reliable task management with persistence, error handling, and retry mechanisms
• Testing Infrastructure: Built-in test framework with pytest integration

Contributing

1. Fork the repository and create a new branch
2. Make your changes and add tests if necessary
3. Submit a pull request with a clear description of your changes

Please read CONTRIBUTING.md for more details.

License

This project is licensed under the MIT License. See LICENSE for details.

Contact

• [e-mail]
• GitHub: @julweber
• Linked.in : Julian Weber

Changelog

View our CHANGELOG.md for a detailed changelog.