# sokrates

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Version: 0.4.1](https://img.shields.io/badge/Version-0.4.1-brightgreen.svg)](https://github.com/Kubementat/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](#description)
- [Installation](#installation)
- [Usage](#usage)
  - [Available Commands](#available-commands)
  - [Task Queuing System](#task-queuing-system)
- [Features](#features)
- [Contributing](#contributing)
- [License](#license)
- [Contact](#contact)
- [Changelog](#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

```bash
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

```bash
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

```bash
brew install ffmpeg
brew install whisper-cpp
```

## Usage

### Basic Command Structure

Most commands follow this structure:
```bash
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:

```bash
# 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

```bash
# 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](CONTRIBUTING.md) for more details.

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

## Contact

- [julianweberdev@gmail.com](mailto:julianweberdev@gmail.com)
- GitHub: [@julweber](https://github.com/julweber)
- Linked.in : [Julian Weber](https://www.linkedin.com/in/julianweberdev/)

## Changelog

View our [CHANGELOG.md](CHANGELOG.md) for a detailed changelog.
