llm-orchestra 0.1.2__tar.gz

llm_orchestra-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.11", "3.12"]
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - name: Install UV (Unix)
+      run: |
+        curl -LsSf https://astral.sh/uv/install.sh | sh
+        echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+    
+    - name: Install dependencies
+      run: |
+        uv sync --extra dev
+    
+    - name: Run tests
+      run: |
+        uv run pytest
+    
+    - name: Run linting
+      run: |
+        uv run ruff check .
+        uv run black --check .
+    
+    # TODO: Fix type checking errors and re-enable
+    # - name: Run type checking
+    #   run: |
+    #     uv run mypy src/llm_orc
+
+  security:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+    
+    - name: Install UV
+      run: |
+        curl -LsSf https://astral.sh/uv/install.sh | sh
+        echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+    
+    - name: Install dependencies
+      run: |
+        uv sync --extra dev
+    
+    - name: Run security checks
+      run: |
+        uv run pip-audit --desc

llm_orchestra-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,83 @@
+name: Publish to PyPI
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  get-version:
+    runs-on: ubuntu-latest
+    outputs:
+      current-version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Get current version
+        id: version
+        run: |
+          VERSION=$(grep -E '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+  build:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+    
+    - name: Install UV
+      run: |
+        curl -LsSf https://astral.sh/uv/install.sh | sh
+        echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+    
+    - name: Build package
+      run: |
+        uv build
+    
+    - name: Check build artifacts
+      run: |
+        ls -la dist/
+        uv add twine
+        uv run python -m twine check dist/*
+    
+    - name: Upload build artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist
+        path: dist/
+
+  publish-pypi:
+    needs: [get-version, build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/llm-orchestra/
+    
+    steps:
+    - name: Download build artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: dist
+        path: dist/
+    
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      continue-on-error: true
+      with:
+        password: ${{ secrets.PYPI_API_KEY }}
+        skip-existing: true
+        verbose: true
+
+  notify:
+    needs: [get-version, publish-pypi]
+    if: always() && needs.publish-pypi.result == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Notify success
+        run: |
+          echo "🎉 Successfully published llm-orchestra v${{ needs.get-version.outputs.current-version }} to PyPI!"

llm_orchestra-0.1.2/.gitignore

@@ -0,0 +1,58 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Testing
+.coverage
+.pytest_cache/
+.tox/
+.nox/
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+
+# Virtual environments
+.env
+.venv/
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db

llm_orchestra-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nathan Green
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

llm_orchestra-0.1.2/Makefile

@@ -0,0 +1,35 @@
+.PHONY: test lint format setup clean install
+
+# Development commands
+setup:
+	uv sync
+
+test:
+	uv run pytest
+
+lint:
+	uv run ruff check src tests
+	uv run mypy src tests
+
+format:
+	uv run black src tests
+	uv run ruff check --fix src tests
+
+clean:
+	rm -rf build/ dist/ *.egg-info/ .venv/
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+	uv clean
+
+install:
+	uv sync --no-dev
+
+# TDD cycle helpers
+red:
+	uv run pytest --tb=short -v
+
+green:
+	uv run pytest --tb=short
+
+refactor:
+	uv run pytest --tb=short && make lint

llm_orchestra-0.1.2/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: llm-orchestra
+Version: 0.1.2
+Summary: Multi-agent LLM communication system with ensemble orchestration
+Project-URL: Homepage, https://github.com/mrilikecoding/llm-orc
+Project-URL: Repository, https://github.com/mrilikecoding/llm-orc
+Project-URL: Bug Tracker, https://github.com/mrilikecoding/llm-orc/issues
+Project-URL: Documentation, https://github.com/mrilikecoding/llm-orc#readme
+Author-email: Nathan Green <contact@nate.green>
+License: MIT License
+        
+        Copyright (c) 2025 Nathan Green
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agents,ai,ensemble,llm,multi-agent,orchestration
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: aiohttp
+Requires-Dist: anthropic
+Requires-Dist: click
+Requires-Dist: google-generativeai
+Requires-Dist: ollama
+Requires-Dist: pydantic
+Requires-Dist: pyyaml
+Requires-Dist: websockets
+Provides-Extra: dev
+Requires-Dist: black>=23.7.0; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy>=1.5.0; extra == 'dev'
+Requires-Dist: pip-audit>=2.6.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.0.287; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# LLM Orchestra
+
+A multi-agent LLM communication system for ensemble orchestration and intelligent analysis.
+
+## Overview
+
+LLM Orchestra lets you coordinate multiple AI agents for complex analysis tasks. Run code reviews with security and performance specialists, analyze architecture decisions from multiple angles, or get systematic coverage of any multi-faceted problem.
+
+Mix expensive cloud models with free local models - use Claude for strategic insights while Llama3 handles systematic analysis tasks.
+
+## Key Features
+
+- **Multi-Agent Ensembles**: Coordinate specialized agents for different aspects of analysis
+- **Cost Optimization**: Mix expensive and free models based on what each task needs
+- **CLI Interface**: Simple commands with piping support (`cat code.py | llm-orc invoke code-review`)
+- **YAML Configuration**: Easy ensemble setup with readable config files
+- **Usage Tracking**: Token counting, cost estimation, and timing metrics
+
+## Installation
+
+### For End Users
+```bash
+pip install llm-orchestra
+```
+
+### For Development
+```bash
+# Clone the repository
+git clone https://github.com/mrilikecoding/llm-orc.git
+cd llm-orc
+
+# Install with development dependencies
+uv sync --dev
+```
+
+## Quick Start
+
+### 1. Create an Ensemble Configuration
+
+Create `~/.llm-orc/ensembles/code-review.yaml`:
+
+```yaml
+name: code-review
+description: Multi-perspective code review ensemble
+
+agents:
+  - name: security-reviewer
+    role: security-analyst
+    model: llama3
+    timeout_seconds: 60
+
+  - name: performance-reviewer
+    role: performance-analyst  
+    model: llama3
+    timeout_seconds: 60
+
+coordinator:
+  synthesis_prompt: |
+    You are a senior engineering lead. Synthesize the security and performance 
+    analysis into actionable recommendations.
+  output_format: json
+  timeout_seconds: 90
+```
+
+### 2. Invoke an Ensemble
+
+```bash
+# Analyze code from a file
+cat mycode.py | llm-orc invoke code-review
+
+# Or provide input directly
+llm-orc invoke code-review --input "Review this function: def add(a, b): return a + b"
+
+# JSON output for integration
+llm-orc invoke code-review --input "..." --output-format json
+
+# List available ensembles
+llm-orc list-ensembles
+```
+
+## Use Cases
+
+### Code Review
+Get systematic analysis across security, performance, and maintainability dimensions. Each agent focuses on their specialty while synthesis provides actionable recommendations.
+
+### Architecture Review  
+Analyze system designs from scalability, security, performance, and reliability perspectives. Identify bottlenecks and suggest architectural patterns.
+
+### Product Strategy
+Evaluate business decisions from market, financial, competitive, and user experience angles. Get comprehensive analysis for complex strategic choices.
+
+### Research Analysis
+Systematic literature review, methodology evaluation, or multi-dimensional analysis of research questions.
+
+## Model Support
+
+- **Claude** (Anthropic) - Strategic analysis and synthesis
+- **Gemini** (Google) - Multi-modal and reasoning tasks  
+- **Ollama** - Local deployment of open-source models (Llama3, etc.)
+- **Custom models** - Extensible interface for additional providers
+
+## Configuration
+
+Ensemble configurations support:
+
+- **Agent specialization** with role-specific prompts
+- **Timeout management** per agent and coordinator
+- **Model selection** with local and cloud options
+- **Synthesis strategies** for combining agent outputs
+- **Output formatting** (text, JSON) for integration
+
+## Cost Optimization
+
+- **Local models** (free) for systematic analysis tasks
+- **Cloud models** (paid) reserved for strategic insights
+- **Usage tracking** shows exactly what each analysis costs
+- **Intelligent routing** based on task complexity
+
+## Development
+
+```bash
+# Run tests
+uv run pytest
+
+# Run linting
+uv run ruff check .
+uv run black --check .
+
+# Type checking
+uv run mypy src/llm_orc
+```
+
+## Research
+
+This project includes comparative analysis of multi-agent vs single-agent approaches. See [docs/ensemble_vs_single_agent_analysis.md](docs/ensemble_vs_single_agent_analysis.md) for detailed findings.
+
+## Philosophy
+
+**Reduce toil, don't replace creativity.** Use AI to handle systematic, repetitive analysis while preserving human creativity and strategic thinking.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

llm_orchestra-0.1.2/README.md

@@ -0,0 +1,143 @@
+# LLM Orchestra
+
+A multi-agent LLM communication system for ensemble orchestration and intelligent analysis.
+
+## Overview
+
+LLM Orchestra lets you coordinate multiple AI agents for complex analysis tasks. Run code reviews with security and performance specialists, analyze architecture decisions from multiple angles, or get systematic coverage of any multi-faceted problem.
+
+Mix expensive cloud models with free local models - use Claude for strategic insights while Llama3 handles systematic analysis tasks.
+
+## Key Features
+
+- **Multi-Agent Ensembles**: Coordinate specialized agents for different aspects of analysis
+- **Cost Optimization**: Mix expensive and free models based on what each task needs
+- **CLI Interface**: Simple commands with piping support (`cat code.py | llm-orc invoke code-review`)
+- **YAML Configuration**: Easy ensemble setup with readable config files
+- **Usage Tracking**: Token counting, cost estimation, and timing metrics
+
+## Installation
+
+### For End Users
+```bash
+pip install llm-orchestra
+```
+
+### For Development
+```bash
+# Clone the repository
+git clone https://github.com/mrilikecoding/llm-orc.git
+cd llm-orc
+
+# Install with development dependencies
+uv sync --dev
+```
+
+## Quick Start
+
+### 1. Create an Ensemble Configuration
+
+Create `~/.llm-orc/ensembles/code-review.yaml`:
+
+```yaml
+name: code-review
+description: Multi-perspective code review ensemble
+
+agents:
+  - name: security-reviewer
+    role: security-analyst
+    model: llama3
+    timeout_seconds: 60
+
+  - name: performance-reviewer
+    role: performance-analyst  
+    model: llama3
+    timeout_seconds: 60
+
+coordinator:
+  synthesis_prompt: |
+    You are a senior engineering lead. Synthesize the security and performance 
+    analysis into actionable recommendations.
+  output_format: json
+  timeout_seconds: 90
+```
+
+### 2. Invoke an Ensemble
+
+```bash
+# Analyze code from a file
+cat mycode.py | llm-orc invoke code-review
+
+# Or provide input directly
+llm-orc invoke code-review --input "Review this function: def add(a, b): return a + b"
+
+# JSON output for integration
+llm-orc invoke code-review --input "..." --output-format json
+
+# List available ensembles
+llm-orc list-ensembles
+```
+
+## Use Cases
+
+### Code Review
+Get systematic analysis across security, performance, and maintainability dimensions. Each agent focuses on their specialty while synthesis provides actionable recommendations.
+
+### Architecture Review  
+Analyze system designs from scalability, security, performance, and reliability perspectives. Identify bottlenecks and suggest architectural patterns.
+
+### Product Strategy
+Evaluate business decisions from market, financial, competitive, and user experience angles. Get comprehensive analysis for complex strategic choices.
+
+### Research Analysis
+Systematic literature review, methodology evaluation, or multi-dimensional analysis of research questions.
+
+## Model Support
+
+- **Claude** (Anthropic) - Strategic analysis and synthesis
+- **Gemini** (Google) - Multi-modal and reasoning tasks  
+- **Ollama** - Local deployment of open-source models (Llama3, etc.)
+- **Custom models** - Extensible interface for additional providers
+
+## Configuration
+
+Ensemble configurations support:
+
+- **Agent specialization** with role-specific prompts
+- **Timeout management** per agent and coordinator
+- **Model selection** with local and cloud options
+- **Synthesis strategies** for combining agent outputs
+- **Output formatting** (text, JSON) for integration
+
+## Cost Optimization
+
+- **Local models** (free) for systematic analysis tasks
+- **Cloud models** (paid) reserved for strategic insights
+- **Usage tracking** shows exactly what each analysis costs
+- **Intelligent routing** based on task complexity
+
+## Development
+
+```bash
+# Run tests
+uv run pytest
+
+# Run linting
+uv run ruff check .
+uv run black --check .
+
+# Type checking
+uv run mypy src/llm_orc
+```
+
+## Research
+
+This project includes comparative analysis of multi-agent vs single-agent approaches. See [docs/ensemble_vs_single_agent_analysis.md](docs/ensemble_vs_single_agent_analysis.md) for detailed findings.
+
+## Philosophy
+
+**Reduce toil, don't replace creativity.** Use AI to handle systematic, repetitive analysis while preserving human creativity and strategic thinking.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.