uglychain

UglyChain

⚡ UglyChain: A Better LLM Application Development Framework ⚡
中文版本说明 »

Report Bug · Request Feature

🤔 What is UglyChain?

UglyChain is a Python framework designed to simplify LLM application development. It provides a more intuitive and developer-friendly interface compared to traditional LLM frameworks.

Key Problems Addressed:

Non-intuitive API Design: Many existing frameworks have complex and non-intuitive interfaces
Over-encapsulation: Excessive abstraction makes customization difficult
Chat-centric Design: Most frameworks are designed around chat interfaces, which are not ideal for structured application development

Why Choose UglyChain?

🚀 Developer-friendly API: Intuitive decorator-based interface
🧩 Modular Design: Easy to extend and customize
⚡ High Performance: Built-in support for parallel processing
📦 Production-ready: Well-documented and thoroughly tested

✨ Features

Decorator-based API: Simplify LLM interactions with intuitive decorators

@llm(model="openai:gpt-4o")
def generate_text(prompt: str) -> str:
    return prompt

Structured Output: Easily parse LLM responses into structured data

class User(BaseModel):
    name: str
    age: int

@llm(model="openai:gpt-4o", response_format=User)
def parse_user(text: str) -> User:
    return text

Parallel Processing: Process multiple inputs concurrently

@llm(model="openai:gpt-4", map_keys=["input"])
def batch_process(inputs: list[str]) -> list[str]:
    return inputs

ReAct Support: Built-in support for reasoning and acting

@react(model="openai:gpt-4", tools=[web_search])
def research(topic: str) -> str:
    return f"Research about {topic}"

Extensible Architecture: Easily add custom models and tools

🚀 Getting Started

Prerequisites

Python 3.10+
pip 20.0+

Installation

# Install from PyPI
pip install uglychain

# Install from source
git clone https://github.com/uglyboy-tl/UglyChain.git
cd UglyChain
pip install -e .

Project Structure

uglychain/
├── src/uglychain         # Source code
│   ├── client.py         # Client supported by aisuite
│   ├── config.py         # Configuration management
│   ├── console.py        # Console interface
│   ├── llm.py            # Core LLM functionality
│   ├── react.py          # ReAct implementation
│   ├── structured.py     # Structured output
│   └── tools.py          # Built-in tools
├── tests/                # Unit tests
├── examples/             # Usage examples
├── pyproject.toml        # Build configuration
└── README.md             # Project documentation

Usage

llm

A basic decorator that makes it easy to decorate LLM calls for more convenient invocation.

Quick start:

from uglychain import llm

@llm(model="openai:gpt-4o-mini", temperature=0.1)
def hello(world : str):
    """You are a helpful assistant that writes in lower case.""" # System Message
    return f"Say hello to {world[::-1]} with a poem."    # User Message

hello("sama")

Structured output example:

class UserDetail(BaseModel):
    name: str
    age: int

@llm("openai:gpt-4o-mini", response_format=UserDetail)
def test(name: str):
    return f"{name} is a boy"

test("Bob")

MapChain

Allows batch processing of models through map_keys, returning multiple results. If config.use_parallel_processing is set to True, it will use multiprocessing for parallel execution.

Quick start:

@llm("openai:gpt-4o-mini", map_keys=["input"])
def map(input: list[str]):
    return input

input = [
    "How old are you?",
    "What is the meaning of life?",
    "What is the hottest day of the year?",
]
for item in map(input):
    print(item)

Similar to LLM, MapChain can also be used for more advanced scenarios:

class AUTHOR(BaseModel):
    name: str = Field(..., description="Name")
    introduction: str = Field(..., description="Introduction")

@llm("openai:gpt-4o-mini", map_keys=["book"], response_format=AUTHOR)
def map(book: list[str], position: str):
    return f"Who is the {position} of {book}?"

input = [
    "Dream of the Red Chamber",
    "Journey to the West",
    "Romance of the Three Kingdoms",
    "Water Margin",
]
map(book=input, position="author") # Returns a list of AUTHOR objects

ReActChain

ReActChain is a method for tool invocation using ReAct capability, which performs better than traditional Function Call approaches.

from uglychain import react
from examples.utils import execute_command

@react("openai:gpt-4o-mini", tools = [execute_command])
def update():
    return "Update my computer system"

update() # Automatically runs shell commands to update the system

🧪 Testing

Run the test suite:

pytest tests/

We maintain 100% test coverage for all core functionality.

🤝 Contributing

We welcome contributions! Please follow these steps:

Read our Contribution Guidelines
Fork the repository
Create a feature branch (git checkout -b feature/YourFeature)
Commit your changes (git commit -m 'Add some feature')
Push to the branch (git push origin feature/YourFeature)
Open a Pull Request

Development Setup

Install development dependencies:
```
pdm install -G dev
```
Set up pre-commit hooks:
```
pre-commit install
```
Run tests before committing:
```
pytest
```

Please ensure your code:

Follows PEP 8 style guidelines
Includes type hints
Has corresponding unit tests
Includes documentation

License

Distributed under the MIT License. See LICENSE.txt for more information.

Metadata

Release files for uglychain 1.6.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for uglychain 1.6.6
File	Size	Uploaded
uglychain-1.6.6.tar.gz	60.0 kB	Sep 15, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for uglychain 1.6.6
File	Interpreter	ABI	Platform	Reset
uglychain-1.6.6-py3-none-any.whl 79.6 kB Sep 15, 2025	Python 3	none	any	Details

Total release size: 139.6 kB

Release files / uglychain-1.6.6.tar.gz

Download URL	uglychain-1.6.6.tar.gz
Size	60.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`775f768164ff33965583e1a650e868111cdca163715cd8186c07280b33adc9fa`
BLAKE2b-256 checksum How to use checksums	`d710fece2a6a5518b6d534db2abd2828ab6527b29df9edf3125a2187787c4874`
Upload date	Sep 15, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.8.17`

Release files / uglychain-1.6.6-py3-none-any.whl

Download URL	uglychain-1.6.6-py3-none-any.whl
Size	79.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`14f381ae80760079805f565f32bdd5acebe86759d7f47ebb700f713efe432ab6`
BLAKE2b-256 checksum How to use checksums	`6bb7961c9c152058bf310aacdd08a6e09ca48087a0ad6143b99a2895349dffd8`
Upload date	Sep 15, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.8.17`