aitomics 0.1.0

A Python port of the Aitomics library for interacting with local LLMs

Aitomics Python Port Strategy

Overview

This document outlines the strategy for creating and maintaining a Python port of the Aitomics library while keeping it synchronized with the JavaScript version. The python port script is for now purely llm generated.

Quick Start

Manual Sync

To sync the Python port with JavaScript changes, run:

cd python-port
python sync_manual.py

This will:

1. Extract function signatures from JavaScript
2. Generate Python stub files
3. Convert examples
4. Clean up temporary files

Development Setup

cd python-port
pip install -e .[dev]
pytest  # Run tests

Architecture

Core Components to Port

1. Core Classes

   • Response - Linked list structure for transformations
   • Caller - LLM interaction wrapper
   • ComparisonModel - Base class for comparisons
   • EqualComparisonModel, DistanceComparisonModel, KrippendorffsComparisonModel, CohensComparisonModel

2. Utility Functions

   • $ - Caller creation function (becomes caller() in Python)
   • _ - Utility namespace
   • createUtilityAnalysisCaller - Custom utility creation

3. Configuration

   • YAML config parsing
   • LLM settings management

4. Visualization

   • Mermaid diagram generation
   • Flow diagram creation

Implementation Strategy

Phase 1: Core Infrastructure ✅

• Set up Python project structure
• Create base classes with type hints
• Implement async/await patterns
• Add comprehensive testing

Phase 2: LLM Integration

• HTTP client for LM Studio API
• Configuration management
• Error handling and retries

Phase 3: Comparison Models

• Implement all comparison models
• Add statistical calculations
• Performance optimization

Phase 4: Utilities & Visualization

• Standard library utilities
• Mermaid diagram generation
• Flow visualization

Phase 5: Synchronization ✅

• Manual sync scripts
• Version management
• Documentation updates

File Structure

python-port/
├── aitomics/                    # Generated Python package
│   ├── __init__.py
│   ├── core/
│   │   ├── __init__.py
│   │   ├── response.py
│   │   ├── caller.py
│   │   └── comparison.py
│   ├── models/
│   │   ├── __init__.py
│   │   ├── equal.py
│   │   ├── distance.py
│   │   ├── krippendorff.py
│   │   └── cohen.py
│   ├── utils/
│   │   ├── __init__.py
│   │   ├── basic.py
│   │   ├── analysis.py
│   │   └── custom.py
│   ├── config/
│   │   ├── __init__.py
│   │   ├── yaml_parser.py
│   │   └── llm_config.py
│   ├── visualization/
│   │   ├── __init__.py
│   │   ├── mermaid.py
│   │   └── flow_diagram.py
│   └── http/
│       ├── __init__.py
│       └── client.py
├── tests/                       # Test files
├── examples/                    # Converted examples
├── sync/                        # Sync utilities
│   ├── js_to_py.py             # Core sync logic
│   └── update_docs.py          # Documentation sync
├── sync_manual.py              # Manual sync script
├── setup.py
├── pyproject.toml
├── requirements.txt
└── README.md

Synchronization Strategy

Manual Sync Process

1. Run sync script: python sync_manual.py
2. Review changes: Check generated files for accuracy
3. Add implementations: Fill in missing functionality
4. Test: Run tests to ensure compatibility
5. Document: Update documentation if needed

Version Management

• Use semantic versioning for both packages
• Keep major versions synchronized
• Allow minor version differences for language-specific features

Python-Specific Enhancements

Type Hints

from typing import Union, List, Dict, Any, Optional
from dataclasses import dataclass

@dataclass
class Response:
    output: Union[str, Dict[str, Any]]
    caller: 'Caller'
    input: Union[str, 'Response']
    generator: str
    root: bool
    level: int

Async/Await Support

import asyncio
import aiohttp

class Caller:
    async def run(self, input_data: Union[str, Response]) -> Response:
        # Async implementation
        pass

Context Managers

class AitomicsContext:
    def __init__(self, config_path: str):
        self.config_path = config_path
    
    async def __aenter__(self):
        await self.load_config()
        return self
    
    async def __aexit__(self, exc_type, exc_val, exc_tb):
        await self.cleanup()

Dependencies

Core Dependencies

• aiohttp - Async HTTP client
• pyyaml - YAML parsing
• pydantic - Data validation
• typing-extensions - Advanced type hints

Development Dependencies

• pytest - Testing framework
• pytest-asyncio - Async testing
• black - Code formatting
• mypy - Type checking
• pre-commit - Git hooks

Migration Guide

JavaScript to Python Mapping

JavaScript	Python
$("prompt", "id")	caller("prompt", "id")
_.lowerCase	utils.lower_case
await caller.run()	await caller.run()
Response.create()	Response.create()

Example Conversion

JavaScript:

const caller = $("Transform text", "my-caller")
const result = await caller.run("input")

Python:

caller = caller("Transform text", "my-caller")
result = await caller.run("input")

Testing Strategy

Unit Tests

• Core class functionality
• Comparison model accuracy
• Utility function behavior

Integration Tests

• LLM API interaction
• Configuration loading
• Visualization generation

Performance Tests

• Large dataset processing
• Memory usage optimization
• Async operation efficiency

Distribution

PyPI Package

• Package name: aitomics
• Version synchronization with npm package
• Comprehensive documentation

Documentation

• Sphinx-based documentation
• API reference
• Migration guides
• Example gallery

Maintenance

Manual Sync Process

• Run sync script when JavaScript changes
• Review and test generated code
• Update documentation as needed
• Release synchronized versions

Quality Assurance

• Code coverage requirements
• Type checking in CI
• Performance benchmarks

Timeline

• Week 1-2: Core infrastructure and basic classes ✅
• Week 3-4: LLM integration and comparison models
• Week 5-6: Utilities and visualization
• Week 7-8: Testing and documentation
• Week 9-10: Manual sync process and distribution ✅

Success Metrics

• 100% API compatibility with JavaScript version
• 90%+ test coverage
• Performance within 10% of JavaScript version
• Manual sync process working
• PyPI package published
• Documentation complete

Usage Examples

Basic Usage

from aitomics import caller, Response

# Create a caller
my_caller = caller("Transform this text to uppercase", "uppercase-transformer")

# Run the caller
result = await my_caller.run("hello world")
print(result.output)  # "HELLO WORLD"

# Create from external data
external_response = Response.create("External data", "original input")

Comparison Example

from aitomics import EqualComparisonModel

# Compare two responses
comparison = result1.compare(result2).run(EqualComparisonModel())
print(f"Agreement: {comparison}")

Utility Functions

from aitomics.utils import lower_case, upper_case

# Use utility functions
lower_result = lower_case("HELLO WORLD")
upper_result = upper_case("hello world")