Skip to main content

Progressive algorithmization toolchain — from LLM to deterministic code, from proxy to tickets

Project description

algitex

Progressive algorithmization toolchain — from LLM to deterministic code, from proxy to tickets.

The only framework that automates the path from "LLM handles everything" to "most traffic runs deterministically, LLM only for edge cases."

pip install algitex
algitex init ./my-app
algitex go

Why "algitex"?

The name reflects the core cycle: analyze → plan → execute → validate → repeat. Each iteration makes your codebase healthier and your LLM usage cheaper. The progressive algorithmization loop gradually replaces LLM calls with deterministic rules.

Algitex = Algorithmic + Intelligence + Execution + Engine

Semantically:

  • Alg- → algorithms, logic, determinism
  • -i- → intelligence layer
  • -tex → texture / system / framework / execution layer

Algitex is the intelligence compilation engine that transforms LLM-driven behavior into deterministic, cost-efficient algorithmic systems. It enables progressive algorithmization from probabilistic AI reasoning to structured, deterministic logic.

Progressive Algorithmization

The 5-stage transition from LLM to deterministic:

Stage 1: Discovery    → LLM performs tasks, collect traces
Stage 2: Extraction   → Identify recurring patterns
Stage 3: Rules        → Generate deterministic replacements
Stage 4: Hybrid       → Route by confidence: rules vs LLM
Stage 5: Optimization → Minimize LLM dependency, reduce costs

Result: Systems that start with LLM flexibility but evolve into efficient, deterministic engines—maintaining AI reasoning benefits with traditional software performance.

Name alternatives considered

Name Why it works Why we picked algitex
algitex Core concept: the continuous improvement loop Clear, memorable, tech-neutral
prollama "progressive" + llama vibes Ties too much to one model family
codefact Code + factory/fact Sounds like a trivia app
algopact Algorithm + Propact Hard to pronounce
loopcode Loop + code Reverse reads awkward
prodev Progressive + dev Too generic, SEO nightmare

Three layers, one command

Layer 1: Code Quality Loop

from algitex import Project

p = Project("./my-app")
p.analyze()    # code2llm + vallm + redup → health report
p.plan()       # auto-generate tickets from analysis
p.execute()    # LLM handles tasks via proxym
p.status()     # health + tickets + budget + cost ledger

Layer 2: Progressive Algorithmization

from algitex import Loop

loop = Loop("./my-app")
loop.discover()        # Stage 1: collect all LLM traces
loop.extract()         # Stage 2: find repeating patterns
loop.generate_rules()  # Stage 3: AI writes its own replacement
loop.route()           # Stage 4: rules vs LLM by confidence
loop.optimize()        # Stage 5: monitor, minimize LLM usage
print(loop.report())   # "42% deterministic, $12.50 saved"

Layer 3: Propact Workflows

from algitex import Workflow

wf = Workflow("./refactor-v1.md")
wf.execute()   # runs propact:shell, propact:rest, propact:llm blocks

CLI

# Core loop
algitex init ./my-app         # initialize project
algitex analyze               # health check
algitex plan --sprints 3      # generate sprint strategy + tickets
algitex go                    # full pipeline
algitex status                # dashboard

# Progressive algorithmization
algitex algo discover         # start trace collection
algitex algo extract          # find patterns in traces
algitex algo rules            # generate deterministic replacements
algitex algo report           # show % deterministic vs LLM

# Propact workflows
algitex workflow run fix.md   # execute Markdown workflow
algitex workflow validate f.md

# Tickets
algitex ticket add "Fix auth" --priority high
algitex ticket list
algitex ticket board
algitex sync                  # push to GitHub/Jira

# Quick queries
algitex ask "Explain this race condition" --tier premium
algitex tools                 # show installed tools

Parallel TODO Task Processing

Execute TODO tasks from prefact analysis in parallel with automatic categorization and fix strategies:

# Verify which TODO tasks are still valid vs already fixed
algitex todo verify-prefact

# Remove outdated tasks from TODO.md
algitex todo verify-prefact --prune

# BatchFix: grupowanie i optymalizacja podobnych zadań
algitex todo batch --dry-run              # Symulacja
algitex todo batch --execute              # Wykonaj fixy
algitex todo batch --limit 10 --parallel 2  # Limit i równoległość
algitex todo batch --execute --prune      # Wykonaj + wyczyść nieaktualne
algitex todo batch --execute --no-log    # Wyłącz logowanie markdown
algitex todo batch --model qwen2.5-coder:7b  # Wybór modelu Ollama

# Auto-fix mechanical issues in parallel (dry-run)
algitex todo fix-auto --workers 8

# Actually apply fixes
algitex todo fix-auto --execute

Three-Tier Micro-Fixing System

Algitex implements an intelligent three-tier classification system that routes tasks to the most cost-effective fix strategy:

┌─────────────────────────────────────────────────────────────┐
│              Three-Tier Micro-Fixing System                 │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Tier 0: Algorithm (90%)    → Deterministic, no LLM         │
│  Tier 1: Small LLM (9%)     → Ollama 7B, minimal context    │
│  Tier 2: Big LLM (1%)       → Claude/GPT-4o, complex only   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Tier Classification

Tier Categories Fix Method Example
0 - Algorithm unused_import, return_type, fstring, magic_known, module_block Regex/AST manipulation import os → remove
1 - Small LLM magic (unknown), docstring, rename, guard_clause, dispatch Ollama 7B, function snippet 42MAX_RETRIES = 42
2 - Big LLM split_function, dependency_cycle, architecture, other Claude/GPT-4o Refactor 200-line function

Three-Tier CLI Commands

# Show tier and category statistics
algitex todo stats TODO.md

# Tier 0: Algorithmic fixes only (deterministic, fastest)
algitex todo fix --algo --dry-run
algitex todo fix --algo --execute --workers 8

# Tier 1: Small LLM fixes (Ollama, local)
algitex todo fix --micro --dry-run
algitex todo fix --micro --execute --model qwen2.5-coder:7b --micro-workers 4

# All tiers: Complete workflow
algitex todo fix --all --dry-run
algitex todo fix --all --execute --workers 4 --micro-workers 2

# With rate limiting and custom backend
algitex todo fix --all --execute \
  --backend litellm-proxy \
  --proxy-url http://localhost:4000 \
  --rate-limit 10 \
  --workers 4

Task Routing Examples

Magic Numbers (Intelligent Routing):

  • Known constants (200 → HTTP_OK): Tier 0, algorithmic
  • Unknown constants (42 → ?): Tier 1, small LLM suggests name
# Tier 0 (known): Immediate replacement
response.status_code == 200    response.status_code == HTTP_OK

# Tier 1 (unknown): LLM suggests constant name
timeout = 42    timeout = MAX_TIMEOUT  # suggested by 7B model

MicroTask — Atomic Tasks for Small LLMs

Pipeline for breaking down and executing atomic micro-tasks optimized for small LLMs:

# Classify tasks by complexity
algitex microtask classify

# Generate execution plan
algitex microtask plan

# Execute micro-tasks
algitex microtask run --workers 4

NLP — Deterministic Refactor Helpers

Deterministic NLP-based refactoring without LLM calls:

# Fix docstrings
algitex nlp docstrings --dry-run
algitex nlp docstrings --execute

# Optimize imports
algitex nlp imports --execute

# Remove dead code
algitex nlp dead-code --execute

# Find and refactor duplicates
algitex nlp duplicates --execute

Python API

from algitex.todo import verify_todos, fix_todos, benchmark_fix, compare_modes

# Verify task validity
result = verify_todos("TODO.md")
print(f"Still open: {result.still_open}, Fixed: {result.already_fixed}")

# Parallel auto-fix (mechanical tasks only)
stats = fix_todos("TODO.md", workers=8, dry_run=False)
print(f"Fixed: {stats['fixed']}, Skipped: {stats['skipped']}")

# Three-tier micro-fixing API
from algitex.todo import (
    classify_task,
    partition_tasks,
    MicroFixer,
    HybridAutofix,
    parallel_fix_and_update,
    BIG_CATEGORIES,
)

# Classify and partition tasks
tasks = parse_todo("TODO.md")
buckets = partition_tasks(tasks)
print(f"Algorithm: {len(buckets['algorithm'])}")
print(f"Micro: {len(buckets['micro'])}")
print(f"Big: {len(buckets['big'])}")

# Tier 0: Algorithmic fixes
result = parallel_fix_and_update("TODO.md", workers=8, dry_run=False)

# Tier 1: Small LLM fixes (Ollama)
micro_fixer = MicroFixer(
    ollama_url="http://localhost:11434",
    model="qwen2.5-coder:7b",
    workers=4,
    dry_run=False,
)
result = micro_fixer.fix_tasks(micro_tasks)

# Tier 2: Big LLM fixes (Claude/GPT-4o)
fixer = HybridAutofix(
    backend="litellm-proxy",
    workers=4,
    rate_limit=10,
    dry_run=False,
)
result = fixer.fix_complex("TODO.md", include_categories=BIG_CATEGORIES)

# Benchmark performance
result = benchmark_fix("TODO.md", limit=100, workers=8, mode="parallel")
result.print_report()

# Compare modes
comparison = compare_modes("TODO.md", limit=50, workers=8)
# Shows: sequential vs parallel speedup, throughput, efficiency

Auto-fix Categories

Category Tier Auto-fixable Description
unused_import 0 - Algorithm ✅ Yes Remove unused imports (import X, from Y import X)
return_type 0 - Algorithm ✅ Yes Add missing return type annotations
fstring 0 - Algorithm ⚠️ Partial Convert concatenations to f-strings
magic_known 0 - Algorithm ✅ Yes Replace known magic numbers (200 → HTTP_OK)
module_block 0 - Algorithm ✅ Yes Add if __name__ == "__main__": guards
magic 1 - Small LLM ✅ Yes Suggest names for unknown magic numbers (Ollama 7B)
docstring 1 - Small LLM ✅ Yes Rewrite verbose docstrings (Ollama 7B)
rename 1 - Small LLM ✅ Yes Improve variable names (Ollama 7B)
guard_clause 1 - Small LLM ✅ Yes Flatten nested ifs (Ollama 7B)
dispatch 1 - Small LLM ✅ Yes Convert if-elif chains to dict dispatch
split_function 2 - Big LLM ✅ Yes Extract methods from large functions (Claude/GPT-4o)
dependency_cycle 2 - Big LLM ✅ Yes Break import cycles (Claude/GPT-4o)
architecture 2 - Big LLM ✅ Yes Reorganize module structure (Claude/GPT-4o)
other 2 - Big LLM ⚠️ Varies Complex issues requiring reasoning (Claude/GPT-4o)

How Parallel Processing Works

┌─────────────────────────────────────────────────────────┐
│              Parallel TODO Processing                    │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  1. Parse TODO.md → filter worktree duplicates          │
│  2. Categorize tasks (unused_import, return_type...)    │
│  3. Group by file (1 worker per file, zero conflicts)   │
│  4. Sort tasks bottom-up (line DESC) → preserve numbers│
│  5. Execute in ThreadPoolExecutor (8 workers default)  │
│  6. Collect results: fixed, skipped, errors            │
│                                                         │
│  Safety: Each worker touches different file.           │
│  Within file: bottom-up prevents line number shifts.   │
│                                                         │
└─────────────────────────────────────────────────────────┘

Three Execution Paths

Path LLM? Parallel? Throughput Use Case
todo fix --algo ❌ No ✅ Yes (8 workers) ~1500 tickets/sec Tier 0: Mechanical fixes
todo fix --micro ✅ Small (7B) ✅ Yes (4 workers) ~50-100 tickets/sec Tier 1: Ollama local fixes
todo fix --all ✅ Hybrid ✅ Yes (multi-phase) Varies by tier All 3 tiers in sequence
todo fix-auto ❌ No ✅ Yes (8 workers) ~1500 tickets/sec Mechanical fixes: unused imports, return types
todo run --tool ollama-mcp ✅ Yes ❌ Sequential (queue) ~1-10 tickets/sec Complex fixes requiring reasoning
autofix via proxy ✅ Yes ⚠️ Batch ~5-50 tickets/sec Intelligent fixes via litellm-proxy

When to use which:

Path 1: Mechanical Fixes (todo fix-auto)

  • No LLM calls — pure regex/text manipulation
  • 8 parallel workers, thread-safe per-file isolation
  • Handles: unused_import, return_type, fstring (via flynt)
  • Best for: bulk cleanup of 100+ simple issues
from algitex.todo import fix_todos
stats = fix_todos("TODO.md", workers=8, dry_run=False)
# 2679 tasks → ~1.8 seconds total

Path 2: LLM-based Fixes (todo run)

  • Uses Ollama/aider via Docker MCP
  • Sequential execution (respects LLM rate limits)
  • Handles: complex refactoring, architectural changes
  • Best for: issues requiring code understanding
algitex todo run --tool ollama-mcp --limit 10

Path 3: Hybrid via Proxy (autofix)

  • Routes through litellm-proxy with cost tracking
  • Batch processing with retry logic
  • Handles: smart fixes with context awareness
  • Best for: production workflows with budget constraints
from algitex.tools.autofix import AutoFix
autofix = AutoFix(backend="litellm-proxy", proxy_url="http://localhost:4000")
autofix.fix_all(limit=5)  # $0.12 per batch avg

Path 4: Hybrid CLI (todo hybrid) — Fast + Parallel + LLM

  • Phase 1: Parallel mechanical fixes (no LLM)
  • Phase 2: Rate-limited parallel LLM fixes
  • Handles: complete TODO workflow in one command
# Dry run (preview)
algitex todo hybrid --workers 4 --rate-limit 10

# Execute with rate limiting
algitex todo hybrid --execute --backend litellm-proxy --workers 4 --rate-limit 10

# Local Ollama (100% offline)
algitex todo hybrid --execute --backend ollama --workers 2 --rate-limit 5

The Missing Piece: Fast + Parallel + LLM

To achieve szybkie + równoległe + LLM, you need to combine ThreadPoolExecutor with ProxyBackend:

from algitex.todo import HybridAutofix

# Combines parallel task distribution with LLM backend
fixer = HybridAutofix(
    backend="litellm-proxy",
    workers=4,              # Parallel workers
    rate_limit=10,          # Requests per second
    retry_attempts=3,
    timeout=30
)

# Mechanical fixes: parallel, no LLM
fixer.fix_mechanical("TODO.md")  # 1000+ tickets/sec

# Complex fixes: parallel LLM with rate limiting
fixer.fix_complex("TODO.md")     # 10-50 tickets/sec, cost-tracked

Requirements for parallel LLM:

  • Rate limiting (prevent 429 errors)
  • Retry logic with exponential backoff
  • Cost tracking per batch
  • Circuit breaker for failed requests

The 5-Stage Progressive Algorithmization

Stage 1: Discovery     → LLM handles 100%, collect traces
Stage 2: Extraction    → identify hot paths + repeating patterns
Stage 3: Rules         → AI generates deterministic replacements
Stage 4: Hybrid        → confidence-based: known patterns → rules, unknown → LLM
Stage 5: Optimization  → most traffic deterministic, LLM for edge cases only

No existing framework automates this path. DSPy goes LLM→smaller LLM. algitex goes LLM→algorithm.

Propact: Markdown as Workflow

# Fix Authentication Module

Analyze current state:

```propact:shell
code2llm ./src/auth -f toon --json

Ask LLM for a fix plan:

POST http://localhost:4000/v1/chat/completions
{"model": "balanced", "messages": [{"role": "user", "content": "Fix auth"}]}

Validate the result:

vallm batch ./src/auth --recursive

## Planfile-Aware Proxy Headers

Every LLM request through algitex carries context:

X-Planfile-Ref: my-project/current/DLP-0042 X-Workflow-Ref: refactor-v1.md X-Task-Tier: complex X-Inject-Context: true


Proxym logs cost/model/latency **per ticket**. The cost ledger shows exactly what each task costs.

## Installation

```bash
pip install algitex                # core
pip install algitex[all]           # + all tools
pip install algitex[proxy]         # + proxym
pip install algitex[analysis]      # + code2llm, vallm, redup
pip install algitex[tickets]       # + planfile
pip install algitex[routing]       # + llx

Examples

# Quickstart — three main objects (Project, Loop, Workflow)
cd examples/01-quickstart
make run

# Progressive Algorithmization — 5-stage loop
cd examples/02-algo-loop
make run

# Composable Pipeline — fluent API
cd examples/03-pipeline
make run

# IDE Integration — generate configs for Roo Code, Cline, etc.
cd examples/04-ide-integration
make setup && make run

# Cost Tracking — per-ticket cost ledger
cd examples/05-cost-tracking
make run

# Local LLM with Ollama — 100% offline, zero API costs
cd examples/18-ollama-local
make setup && make run

# Local MCP Tools — self-hosted code analysis & validation
cd examples/19-local-mcp-tools
make up && make run

# Self-Hosted Pipeline — complete local CI/CD stack
cd examples/20-self-hosted-pipeline
make build && make up && make run

# Aider CLI + Ollama — local refactoring with prefact TODO workflow
cd examples/21-aider-cli-ollama
make setup && make run

# Claude Code + Ollama — AI assistant with local LLM
cd examples/22-claude-code-ollama
make setup && make run

# Continue.dev + Ollama — VS Code extension setup
cd examples/23-continue-dev-ollama
make setup

# Ollama Batch Processing — parallel code analysis
cd examples/24-ollama-batch
python batch_analyze.py --dir ./src

# Local Model Comparison — benchmark Ollama models
cd examples/25-local-model-comparison
make benchmark

# LiteLLM Proxy + Ollama — native algitex integration (better than aider)
cd examples/26-litellm-proxy-ollama
make setup && make proxy  # Terminal 1
make fix                  # Terminal 2

# Hybrid AutoFix — fast parallel + LLM with rate limiting
cd examples/33-hybrid-autofix
make dry-run              # Preview
make hybrid               # Execute with LiteLLM proxy
make ollama               # Execute with Ollama (100% offline)

# BatchFix — grupowanie i optymalizacja podobnych zadań
cd examples/34-batch-fix
algitex todo batch --dry-run   # Symulacja
algitex todo batch --execute   # Wykonaj fixy

Each example has:

All 34 examples tested and verified working (2026-03-28). Examples 01-34 (except 29) execute without errors.

Additional Documentation

  • README2.md — Detailed conceptual overview of Algitex as intelligence compilation engine

Architecture

src/algitex/
├── __init__.py           # Project, Loop, Workflow, Config, Pipeline
├── config.py             # Unified config (env + YAML)
├── project.py            # Main Project class (expanded)
├── cli.py                # Typer CLI backward compatibility shim
├── cli/                  # Modular CLI commands
│   ├── __init__.py       # Main app with all subcommands
│   ├── core.py           # init, analyze, plan, go, status
│   ├── ticket.py         # Ticket management
│   ├── algo.py           # Progressive algorithmization
│   ├── workflow.py       # Propact workflows
│   ├── docker.py         # Docker MCP tools
│   ├── todo.py           # TODO processing (three-tier fixes)
│   ├── microtask.py      # Atomic micro-task pipeline
│   └── nlp.py            # Deterministic NLP helpers
├── algo/                 # Progressive algorithmization
│   ├── __init__.py       # Loop, TraceEntry, Pattern, Rule, LoopState
│   └── loop.py           # Re-export
├── propact/              # Markdown workflow engine
│   ├── __init__.py       # Workflow, WorkflowStep, WorkflowResult
│   └── workflow.py       # Re-export
├── todo/                 # Three-tier TODO fixing system
│   ├── __init__.py       # Public API exports
│   ├── fixer.py          # Tier 0: Algorithmic fixes
│   ├── micro.py          # Tier 1: Small LLM fixes
│   ├── hybrid.py         # Tier 2: Big LLM fixes
│   ├── tiering.py        # Task classification
│   └── benchmark.py      # Performance benchmarking
├── microtask/            # Atomic tasks for small LLMs
│   ├── __init__.py       # MicroTask, TaskType, MicroTaskBatch
│   ├── classifier.py     # Task classification
│   ├── executor.py       # Three-phase execution
│   └── slicer.py         # Context extraction
├── nlp/                  # Deterministic NLP refactors
│   └── __init__.py       # DocstringShortener, DeadCodeDetector, etc.
├── tools/
│   ├── __init__.py       # Tool discovery
│   ├── proxy.py          # proxym wrapper + planfile headers
│   ├── analysis.py       # code2llm + vallm + redup
│   └── tickets.py        # planfile wrapper + cost ledger
└── workflows/
    ├── __init__.py        # Pipeline (composable steps)
    └── pipeline.py        # Re-export

How it connects to the ecosystem

┌─────────────────────────────────────────────────────┐
│                     algitex                         │
│            (orchestration layer)                    │
├─────────────────────────────────────────────────────┤
│                                                     │
│  analyze()   plan()   execute()   algo.discover()   │
│     │          │         │            │             │
│  code2llm   planfile   proxym      trace →          │
│  vallm      tickets    llx         patterns →       │
│  redup      strategy   models      rules →          │
│                                    hybrid routing   │
│                                                     │
│  Three-Tier TODO Fixing:                            │
│    todo fix --algo     → Tier 0: Deterministic      │
│    todo fix --micro    → Tier 1: Ollama 7B          │
│    todo fix --all      → All tiers in sequence      │
│                                                     │
│  MicroTask Pipeline:                                │
│    microtask classify → atomic task decomposition   │
│    microtask plan     → execution strategy          │
│    microtask run      → three-phase execution       │
│                                                     │
│  NLP Helpers (deterministic):                       │
│    nlp docstrings     → shorten verbose docs        │
│    nlp imports        → sort and organize           │
│    nlp dead-code      → detect unused functions     │
│    nlp duplicates     → find repeated blocks        │
│                                                     │
│  run_workflow("fix.md")                             │
│     │                                               │
│  propact:shell → subprocess                         │
│  propact:rest  → httpx                              │
│  propact:llm   → proxym                             │
│  propact:mcp   → MCP tool call                      │
│                                                     │
└─────────────────────────────────────────────────────┘

Tool Roles

Tool What Install
proxym LLM gateway, 10 providers, routing, budget pip install proxym
planfile Sprint planning, tickets, GitHub/Jira sync pip install planfile
llx Metric-driven model selection, MCP server pip install llx
code2llm Static analysis → .toon diagnostics pip install code2llm
vallm 4-tier code validation pip install vallm
redup Duplication detection pip install redup

License

Licensed under Apache-2.0.

Licensed under Apache-2.0.

Author

Tom Sapletta

Tom Sapletta

Created by Tom Saplettatom@sapletta.com.

Part of the semcod / wronai ecosystem.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

algitex-0.1.46.tar.gz (192.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

algitex-0.1.46-py3-none-any.whl (195.2 kB view details)

Uploaded Python 3

File details

Details for the file algitex-0.1.46.tar.gz.

File metadata

  • Download URL: algitex-0.1.46.tar.gz
  • Upload date:
  • Size: 192.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.13.7

File hashes

Hashes for algitex-0.1.46.tar.gz
Algorithm Hash digest
SHA256 c9421d4f57abbba2835652eb00201e9cbca6e32366399f053106061872f44f27
MD5 111bad596b29b4aa1c1f8f1112ee3860
BLAKE2b-256 17026327b5618bef3809f8d3a1257f31401937b52c08b3b0f783527f2aae3057

See more details on using hashes here.

File details

Details for the file algitex-0.1.46-py3-none-any.whl.

File metadata

  • Download URL: algitex-0.1.46-py3-none-any.whl
  • Upload date:
  • Size: 195.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.13.7

File hashes

Hashes for algitex-0.1.46-py3-none-any.whl
Algorithm Hash digest
SHA256 f9df78fa1510349c3006e571ccdb65b2dd4869ca1d1485d5d0b5c5a07b31c6c7
MD5 504f287f1dc695f55cf27b3f021b290b
BLAKE2b-256 81e3d14f0f749945eccbc255e02bfe2508f6295745099361cf2e43f705d76f6c

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page