Metadata-Version: 2.1
Name: kagura-ai
Version: 0.0.8
Summary: A flexible AI agent framework with YAML-based configuration
Author-email: JFK <fumikazu.kiyota@gmail.com>
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.10.2
Requires-Dist: click>=8.1.7
Requires-Dist: PyYAML==6.0.2
Requires-Dist: rich==13.9.4
Requires-Dist: litellm==1.53.1
Requires-Dist: redis==5.2.0
Requires-Dist: langgraph==0.2.53
Requires-Dist: langchain==0.3.9
Requires-Dist: prompt_toolkit==3.0.48
Requires-Dist: tzlocal==5.2
Requires-Dist: chardet==5.2.0
Requires-Dist: python-pptx==1.0.2
Requires-Dist: python-docx==1.1.2
Requires-Dist: beautifulsoup4>=4.12.3
Requires-Dist: pdfminer-six>=20240706
Requires-Dist: toml>=0.10.2
Requires-Dist: mcp>=1.1.0
Requires-Dist: pytest>=8.3.4
Provides-Extra: dev
Requires-Dist: pytest>=8.3.3; extra == "dev"
Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
Requires-Dist: black>=24.10.0; extra == "dev"
Requires-Dist: flake8>=7.1.1; extra == "dev"
Requires-Dist: mypy>=1.13.0; extra == "dev"
Requires-Dist: isort>=5.13.2; extra == "dev"
Requires-Dist: pre-commit>=4.0.1; extra == "dev"
Requires-Dist: mkdocs>=1.6.1; extra == "dev"
Requires-Dist: mkdocs-material>=9.5.46; extra == "dev"
Requires-Dist: mkdocs-i18n>=0.4.6; extra == "dev"
Requires-Dist: pymdown-extensions>=10.12; extra == "dev"
Requires-Dist: pyright>=1.1.389; extra == "dev"
Requires-Dist: pyfakefs>=5.7.2; extra == "dev"
Requires-Dist: ruff>=0.6.9; extra == "dev"
Requires-Dist: trio>=0.26.2; extra == "dev"

# Kagura AI

![Kagura AI Logo](https://www.kagura-ai.com/assets/kagura-logo.svg)

![Python versions](https://img.shields.io/pypi/pyversions/kagura-ai.svg)
![PyPI version](https://img.shields.io/pypi/v/kagura-ai.svg)
![PyPI - Downloads](https://img.shields.io/pypi/dm/kagura-ai)
![Codecov](https://img.shields.io/codecov/c/github/JFK/kagura-ai)
![Tests](https://img.shields.io/github/actions/workflow/status/JFK/kagura-ai/test.yml?label=tests)
![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)
![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)

Kagura AI is a lightweight open-source framework specialized in building and orchestrating AI Multi Agents. Named after the traditional Japanese performance art "Kagura (神楽)", it enables sophisticated AI agent systems through simple YAML-based configurations while embodying the principles of harmony, connection, and respect.

---

## Why Kagura AI?

The name **Kagura AI** reflects the principles of Kagura: harmony, connection, and balance. By adopting these values, Kagura AI seeks to create responsible AI systems that prioritize collaboration, innovation, and ethical design.

- **Harmony**: Integrates diverse technologies into cohesive workflows, just as Kagura weaves music, dance, and ritual into a unified performance.
- **Connection**: Facilitates seamless inter-agent communication, mirroring Kagura's role in linking humanity, nature, and the divine.
- **Creativity**: Combines innovative AI solutions with timeless principles, embodying Kagura's balance between tradition and artistic expression.

These principles form the foundation of Kagura AI's **Core Concepts**, ensuring a flexible, reliable, and ethical framework for building and orchestrating intelligent agents.

---

## Core Concepts

### Atomic Agent
- **Task-Specific Operations**: Atomic Agents are designed to handle high-granularity, specialized tasks efficiently and independently.
- **Modular and Decoupled**: Operates as standalone units or integrates with other agents via loose coupling, akin to microservices.
- **Flexibility**: Can interact with functions, tools, or external APIs, enabling seamless integration in larger workflows.

### Orchestration Framework
- **Multi-Agent Coordination**: Combines multiple Atomic Agents to execute complex, multi-step workflows.
- **Dynamic Routing**: Supports conditional branching and flow control for advanced task orchestration.
- **Collaborative Functionality**: Acts as a unified system while maintaining individual agent autonomy.

### State and Response Management
- **Type-Safe State Handling**: Uses Pydantic models to ensure data integrity and consistency across workflows.
- **Response Customization**: Modular responses allow rapid adaptation to changing requirements.
- **Debugging and Transparency**: Centralized state management simplifies error tracking and improves overall system reliability.

---

## Key Features

- **Atomic Agent Design**: High-granularity, task-specific agents that execute independently or as part of workflows
- **Workflow Orchestration**: Coordinate complex, multi-step processes with dynamic routing
- **State and Response Management**: Ensure data safety and modularity with type-safe states and customizable responses
- **YAML-Based Configuration**: Define agents and workflows in a human-readable format
- **Multi-LLM Support**: Seamlessly connect with OpenAI, Anthropic, Ollama, Google, and more via [LiteLLM](https://github.com/BerriAI/litellm)
- **Extensibility**: Add custom tools, hooks, and plugins for domain-specific tasks
- **Multilingual Support**: Native support for multiple languages
- **Redis Integration**: Optional persistent memory for agents

---

## Quick Start

[Kagura Quick Start](https://www.kagura-ai.com/en/quickstart/)

---

## Contributing to Kagura AI

We welcome all contributors! Whether you're a seasoned developer or new to open source, your input matters. Join us to shape the future of Kagura AI.

### Ways to Contribute
- Report issues or bugs
- Propose new features or improvements
- Submit code, documentation, or tests
- Help review Pull Requests

### Steps to Contribute
1. Read the [Contributing Guide](./CONTRIBUTING.md)
2. Fork the repository and clone it locally
3. Create a branch, make your changes, and submit a Pull Request

---

## Documentation and Resources

- [Full Documentation](https://www.kagura-ai.com/)
- [Quick Start Tutorial](https://www.kagura-ai.com/en/quickstart/)
- [Issues and Discussions](https://github.com/JFK/kagura-ai/issues)

---

Thank you for exploring Kagura AI! Let's build harmonious, innovative, and responsible AI solutions together.
