Metadata-Version: 2.3
Name: hellig
Version: 0.0.1
Summary: Multi-agent natural language orchestration programming framework.
Keywords: agents,llm,orchestration,natural-language,framework
Author: HSPK
Author-email: HSPK <whxway@whu.edu.cn>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: click>=8.1.7
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/HSPK/hellig
Project-URL: Repository, https://github.com/HSPK/hellig
Project-URL: Issues, https://github.com/HSPK/hellig/issues
Description-Content-Type: text/markdown

# Hellig

> Multi-agent **natural language orchestration programming** framework.

Hellig lets you compose programs out of natural language steps that are dispatched
to specialized agents. Treat prompts as instructions, agents as functions, and an
orchestrator as the runtime that wires them together.

[![PyPI](https://img.shields.io/pypi/v/hellig.svg)](https://pypi.org/project/hellig/)
[![Python](https://img.shields.io/pypi/pyversions/hellig.svg)](https://pypi.org/project/hellig/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](#license)

## Why Hellig

Modern LLM applications quickly outgrow a single prompt. Hellig provides a tiny,
opinionated core so you can:

- **Describe work in natural language** and let agents do the heavy lifting.
- **Compose programs** as ordered steps, with named outputs feeding later prompts.
- **Swap agent runtimes** (any LLM client, a local model, or a stub for tests)
  without rewriting your orchestration.
- **Operate from the terminal** with the `hg` CLI for quick experiments.

## Install

```bash
pip install hellig
# or
uv add hellig
```

## Quick start

```python
from hellig import Agent, Orchestrator, Program

def echo_runtime(prompt: str, **_: object) -> str:
    return prompt.upper()

researcher = Agent(name="researcher", instructions="You research topics.", runtime=echo_runtime)
writer = Agent(name="writer", instructions="You write summaries.", runtime=echo_runtime)

program = (
    Program(name="brief")
    .add("researcher", "Collect facts about {topic}", output="facts")
    .add("writer", "Write a 3-bullet summary of:\n{facts}", output="summary")
)

orchestrator = Orchestrator().register(researcher).register(writer)
result = orchestrator.run(program, topic="agentic programming")
print(result["summary"])
```

## Core concepts

| Concept | Description |
| --- | --- |
| `Agent` | A named worker with optional instructions, runtime, and tools. |
| `Program` | An ordered sequence of natural language `Step`s with named outputs. |
| `Orchestrator` | Registers agents and executes programs, threading outputs into later prompts. |

Steps use `str.format` substitution, so any prior step's `output` (and any
context kwargs passed to `run`) is available as a placeholder.

## CLI

The package installs an `hg` command powered by [Click](https://click.palletsprojects.com/):

```bash
hg --help
hg version
hg hello HSPK
hg run --agent researcher --agent writer \
       --step researcher "Find facts about Hellig" \
       --step writer "Summarize the facts"
```

## Development

```bash
uv sync
uv run hg --help
uv build
```

## Roadmap

- Pluggable LLM runtimes (OpenAI, Anthropic, local).
- Tool calling and structured outputs.
- Parallel and conditional steps.
- Persistent traces for debugging.

## License

MIT © HSPK
