Metadata-Version: 2.4
Name: fabricatio
Version: 0.26.0.dev6
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Framework :: AsyncIO
Classifier: Framework :: Pydantic :: 2
Classifier: Typing :: Typed
Requires-Dist: fabricatio-core
Requires-Dist: fabricatio-actions ; extra == 'actions'
Requires-Dist: fabricatio-agent ; extra == 'agent'
Requires-Dist: fabricatio-anki ; extra == 'anki'
Requires-Dist: fabricatio-capabilities ; extra == 'capabilities'
Requires-Dist: fabricatio-capable ; extra == 'capable'
Requires-Dist: fabricatio-character ; extra == 'character'
Requires-Dist: fabricatio-checkpoint ; extra == 'checkpoint'
Requires-Dist: fabricatio-diff ; extra == 'diff'
Requires-Dist: fabricatio-digest ; extra == 'digest'
Requires-Dist: fabricatio[rag,typst,rule,judge,capabilities,actions,improve,digest,memory,anki,question,tagging,yue,tool,plot,translate,locale,diff,thinking,agent,team,capable,novel,character,checkpoint,webui,milvus] ; extra == 'full'
Requires-Dist: fabricatio-improve ; extra == 'improve'
Requires-Dist: fabricatio-judge ; extra == 'judge'
Requires-Dist: fabricatio-locale ; extra == 'locale'
Requires-Dist: fabricatio-memory ; extra == 'memory'
Requires-Dist: fabricatio-milvus ; extra == 'milvus'
Requires-Dist: fabricatio-novel ; extra == 'novel'
Requires-Dist: fabricatio-plot ; extra == 'plot'
Requires-Dist: fabricatio-question ; extra == 'question'
Requires-Dist: fabricatio-rag ; extra == 'rag'
Requires-Dist: fabricatio-rule ; extra == 'rule'
Requires-Dist: fabricatio-tagging ; extra == 'tagging'
Requires-Dist: fabricatio-team ; extra == 'team'
Requires-Dist: fabricatio-thinking ; extra == 'thinking'
Requires-Dist: fabricatio-tool ; extra == 'tool'
Requires-Dist: fabricatio-translate ; extra == 'translate'
Requires-Dist: fabricatio-typst ; extra == 'typst'
Requires-Dist: fabricatio-webui ; extra == 'webui'
Requires-Dist: fabricatio-yue ; extra == 'yue'
Provides-Extra: actions
Provides-Extra: agent
Provides-Extra: anki
Provides-Extra: capabilities
Provides-Extra: capable
Provides-Extra: character
Provides-Extra: checkpoint
Provides-Extra: diff
Provides-Extra: digest
Provides-Extra: full
Provides-Extra: improve
Provides-Extra: judge
Provides-Extra: locale
Provides-Extra: memory
Provides-Extra: milvus
Provides-Extra: novel
Provides-Extra: plot
Provides-Extra: question
Provides-Extra: rag
Provides-Extra: rule
Provides-Extra: tagging
Provides-Extra: team
Provides-Extra: thinking
Provides-Extra: tool
Provides-Extra: translate
Provides-Extra: typst
Provides-Extra: webui
Provides-Extra: yue
License-File: LICENSE
Summary: A LLM multi-agent framework.
Keywords: ai,agents,multi-agent,llm,pyo3
Author-email: Whth <zettainspector@foxmail.com>
Requires-Python: >=3.12, <3.15
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/Whth/fabricatio
Project-URL: Issues, https://github.com/Whth/fabricatio/issues
Project-URL: Repository, https://github.com/Whth/fabricatio

<p align="center">   
<picture>
        <img src="./assets/band.png" width="80%" alt="Fabricatio Logo" loading="lazy">
</picture>
</p>



<p align="center">
  <a href="LICENSE">
    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License">
  </a>
  <a href="https://pypi.org/project/fabricatio/">
    <img src="https://img.shields.io/pypi/pyversions/fabricatio" alt="Python Versions">
  </a>
  <a href="https://pypi.org/project/fabricatio/">
    <img src="https://img.shields.io/pypi/v/fabricatio" alt="PyPI Version">
  </a>
  <a href="https://deepwiki.com/Whth/fabricatio">
    <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki">
  </a>
  <a href="https://pepy.tech/projects/fabricatio">
    <img src="https://static.pepy.tech/badge/fabricatio/week" alt="PyPI Downloads (Week)">
  </a>
  <a href="https://pepy.tech/projects/fabricatio">
    <img src="https://static.pepy.tech/badge/fabricatio" alt="PyPI Downloads">
  </a>
  <a href="https://github.com/PyO3/pyo3">
    <img src="https://img.shields.io/badge/bindings-pyo3-green" alt="Bindings: PyO3">
  </a>

  <a href="https://github.com/astral-sh/uv">
    <img src="https://img.shields.io/badge/built%20with-uv%20%2B%20maturin-orange" alt="Build Tool: uv + maturin">
  </a>

</p>


<p align="center">


  <a href="https://github.com/Whth/fabricatio/actions/workflows/build-package.yaml">
    <img src="https://github.com/Whth/fabricatio/actions/workflows/build-package.yaml/badge.svg" alt="Build Package">
  </a>
  <a href="https://github.com/Whth/fabricatio/actions/workflows/ruff.yaml">
    <img src="https://github.com/Whth/fabricatio/actions/workflows/ruff.yaml/badge.svg" alt="Ruff Lint">
  </a>
  <a href="https://github.com/Whth/fabricatio/actions/workflows/tests.yaml">
    <img src="https://github.com/Whth/fabricatio/actions/workflows/tests.yaml/badge.svg" alt="Tests">
  </a>
  <a href="https://coveralls.io/github/Whth/fabricatio?branch=master">
    <img src="https://coveralls.io/repos/github/Whth/fabricatio/badge.svg?branch=master" alt="Coverage Status">
  </a>
  <a href="https://fabricatio.readthedocs.io/en/latest/?badge=fabricatio">
    <img src="https://readthedocs.org/projects/fabricatio/badge/?version=latest" alt="Documentation Status">
  </a>
  <a href="https://github.com/Whth/fabricatio/issues">
    <img src="https://img.shields.io/github/issues/Whth/fabricatio" alt="GitHub Issues">
  </a>
  <a href="https://github.com/Whth/fabricatio/pulls">
    <img src="https://img.shields.io/github/issues-pr/Whth/fabricatio" alt="GitHub Pull Requests">
  </a>
  <a href="https://github.com/Whth/fabricatio/stargazers">
    <img src="https://img.shields.io/github/stars/Whth/fabricatio" alt="GitHub Stars">
  </a>
</p>



---

## Overview

Fabricatio is a streamlined Python library for building LLM applications using an event-based agent structure. It
leverages Rust for performance-critical tasks, Handlebars for templating, and PyO3 for Python bindings.

## Features

- **Event-Driven Architecture**: Robust task management through an EventEmitter pattern.
- **LLM Integration & Templating**: Seamlessly interact with large language models and dynamic content generation.
- **Async & Extensible**: Fully asynchronous execution with easy extension via custom actions and workflows.

## TODO

- [ ] Add api support.
- [ ] Run as mcp server.
- [ ] Finalize the webui.
- [ ] Add Plugin system.
- [x] Replace litellm with native rust impl
    - [x] Port deprecated mock utils to thryd impl
    - [ ] Port tests to new mock utils
    - [ ] Sync documentations
- [ ] Add worktree-based isolated development subpackage
- [ ] Add level-based context compression subpackage
- [ ] TreeSetter-based ACE
- [ ] Self-Extensible Agent
- [ ] Add more examples
- [x] Port build workflow to `Justfile`

## Installation

```bash
# install fabricatio with full capabilities.
pip install fabricatio[full]

# or with uv

uv add fabricatio[full]


# install fabricatio with only rag and rule capabilities.
pip install fabricatio[rag,rule]

# or with uv

uv add fabricatio[rag,rule]

```

You can download the templates from the github release manually and extract them to the work directory.

```bash
curl -L https://github.com/Whth/fabricatio/releases/download/v0.19.1/templates.tar.gz | tar -xz
```

Or you can use the cli `tdown` bundled with `fabricatio` to achieve the same result.

```bash
tdown download --verbose -o ./
```

> Note: `fabricatio` performs template discovery across multiple sources with filename-based identification. Template
> resolution follows a priority hierarchy where working directory templates override templates located in
`<ROAMING>/fabricatio/templates`.

## Usage

### Basic Example

```python
"""Example of a simple hello world program using fabricatio."""

from typing import Any

# Import necessary classes from the namespace package.
from fabricatio import Action, Event, Role, Task, WorkFlow, logger


# Create an action.
class Hello(Action):
    """Action that says hello."""

    output_key: str = "task_output"

    async def _execute(self, **_) -> Any:
        ret = "Hello fabricatio!"
        logger.info("executing talk action")
        return ret


# Create the role and register the workflow.
(Role()
 .add_skill(Event.quick_instantiate("talk"), WorkFlow(name="talk", steps=(Hello,)))
 .dispatch())

# Make a task and delegate it to the workflow registered above.
assert Task(name="say hello").delegate_blocking("talk") == "Hello fabricatio!"

```

### Examples

For various usage scenarios, refer to the following examples:

- Simple Chat
- Retrieval-Augmented Generation (RAG)
- Article Extraction
- Propose Task
- Code Review
- Write Outline

_(For full example details, see [Examples](./examples))_

## Configuration

Fabricatio supports flexible configuration through multiple sources, with the following priority order:
`Call Arguments` > `./.env` > `Environment Variables` > `./fabricatio.toml` > `./pyproject.toml` >
`<ROMANING>/fabricatio/fabricatio.toml` > `Builtin Defaults`.

Below is a unified view of the same configuration expressed in different formats:

### Environment variables or dotenv file

```dotenv
FABRICATIO_LLM__API_ENDPOINT=https://api.openai.com
FABRICATIO_LLM__API_KEY=your_openai_api_key
FABRICATIO_LLM__TIMEOUT=300
FABRICATIO_LLM__MAX_RETRIES=3
FABRICATIO_LLM__MODEL=openai/gpt-3.5-turbo
FABRICATIO_LLM__TEMPERATURE=1.0
FABRICATIO_LLM__TOP_P=0.35
FABRICATIO_LLM__GENERATION_COUNT=1
FABRICATIO_LLM__STREAM=false
FABRICATIO_LLM__MAX_TOKENS=8192
FABRICATIO_DEBUG__LOG_LEVEL=INFO
```

### `fabricatio.toml` file

```toml
[llm]
api_endpoint = "https://api.openai.com"
api_key = "your_openai_api_key"
timeout = 300
max_retries = 3
model = "openai/gpt-3.5-turbo"
temperature = 1.0
top_p = 0.35
generation_count = 1
stream = false
max_tokens = 8192

[debug]
log_level = "INFO"
```

### `pyproject.toml` file

```toml
[tool.fabricatio.llm]
api_endpoint = "https://api.openai.com"
api_key = "your_openai_api_key"
timeout = 300
max_retries = 3
model = "openai/gpt-3.5-turbo"
temperature = 1.0
top_p = 0.35
generation_count = 1
stream = false
max_tokens = 8192

[tool.fabricatio.debug]
log_level = "INFO"
```

## Contributing

We welcome contributions from everyone! Before contributing, please read our [Contributing Guide](CONTRIBUTING.md)
and [Code of Conduct](CODE_OF_CONDUCT.md).

## License

Fabricatio is licensed under the MIT License. See [LICENSE](LICENSE) for details.

## Acknowledgments

Special thanks to the contributors and maintainers of:

- [PyO3](https://github.com/PyO3/pyo3)
- [Maturin](https://github.com/PyO3/maturin)
- [Handlebars.rs](https://github.com/sunng87/handlebars-rust)
- [LiteLLM](https://github.com/BerriAI/litellm)

