---
title: Liquid Logo
description: An advanced WebGL-based component that applies a dynamic, liquid effect to logos or images using custom shaders.
navBadges:
  - value: New
    type: lime
---

::ComponentLoader{label="Preview" componentName="LiquidLogoDemo" type="examples" id="liquid-logo"}
::

## API

| Prop Name      | Type     | Default | Description                                  |
| -------------- | -------- | ------- | -------------------------------------------- |
| `class`        | `string` | `""`    | Additional CSS classes for custom styling.   |
| `imageUrl`     | `string` | `""`    | URL of the image to apply the liquid effect. |
| `patternScale` | `number` | `2`     | Scale of the distortion pattern.             |
| `refraction`   | `number` | `0.015` | Amount of refraction applied to the image.   |
| `edge`         | `number` | `0.4`   | Sharpness of the edge effect.                |
| `patternBlur`  | `number` | `0.005` | Blur effect applied to the pattern.          |
| `liquid`       | `number` | `0.07`  | Intensity of the liquid animation.           |
| `speed`        | `number` | `0.3`   | Animation speed of the liquid effect.        |

## Component Code

You can copy and paste the following code to create this component:

::code-group

    ::CodeViewerTab{label="LiquidLogo.vue" language="vue" componentName="LiquidLogo" type="ui" id="liquid-logo"}
    ::

    ::CodeViewerTab{label="parseLogoImage.ts" language="typescript" componentName="parseLogoImage" type="ui" id="liquid-logo" extension="ts"}
    ::

    ::CodeViewerTab{label="shader.ts" language="typescript" componentName="shader" type="ui" id="liquid-logo" extension="ts"}
    ::

::

## Features

- **Dynamic Liquid Effect**: Transforms logos or images with a fluid, liquid-like motion.
- **Custom Shader Utilization**: Built with WebGL2 and GLSL shaders for real-time rendering.
- **Interactive Animations**: Smooth and configurable animation effects.
- **Responsive Scaling**: Automatically adjusts to different screen sizes and resolutions.
- **Configurable Parameters**: Offers a wide range of props to control effects like refraction, speed, and edge sharpness.

## Credits

- Inspired by the Apple Fluid Motion design.
- Ported and enhaced from [Paper Design Concept](https://github.com/paper-design/liquid-logo).


---
title: Animated Logo Cloud
description: Animated company cloud logs. Usually we can use to show company logos.
---

::ComponentLoader{label="Preview" componentName="StaticLogoCloudDemo" type="examples" id="logo-cloud"}
::

## Examples

### Animated logs

Animated company logos.

::ComponentLoader{label="Preview" componentName="AnimatedLogoCloudDemo" type="examples" id="logo-cloud"}
::

### Icon Logo

Company logo icons

::ComponentLoader{label="Preview" componentName="IconLogoCloudDemo" type="examples" id="logo-cloud"}
::

## API

| Prop Name | Type     | Default                     | Description                                                    |
| --------- | -------- | --------------------------- | -------------------------------------------------------------- |
| `class`   | `string` | `-`                         | The delay in milliseconds before adding each item to the list. |
| `title`   | `string` | `Trusted by Companies like` | Title of animated logs.                                        |
| `logos`   | `[]`     | `[{name: "", path: ""}]`    | Array of items(logos) with name & path fields.                 |

## Component Code

You can copy and paste the following code to create this component:

::CodeGroup
::CodeViewerTab{label="StaticLogoCloud.vue" language="vue" componentName="StaticLogoCloud" type="ui" id="logo-cloud"}
::

::CodeViewerTab{label="AnimatedLogoCloud.vue" language="vue" componentName="AnimatedLogoCloud" type="ui" id="logo-cloud"}
::

::CodeViewerTab{label="IconLogoCloud.vue" language="vue" componentName="IconLogoCloud" type="ui" id="logo-cloud"}
::

::CodeViewerTab{filename="index.ts" language="ts" componentName="index" type="ui" id="logo-cloud" extension="ts"}
::
::

## Credits

- Credits to [SivaReddy Uppathi](https://github.com/sivareddyuppathi) for this component.

Build beautiful website using Vue & Nuxt.


---
title: Logo Origami
description: Animated flipping logo with origami effect.
---

::ComponentLoader{label="Preview" componentName="LogoOrigamiDemo" type="examples"}
::

## API

| Prop Name  | Type     | Default | Description                                |
| ---------- | -------- | ------- | ------------------------------------------ |
| `class`    | `string` | `""`    | Additional CSS classes for custom styling. |
| `duration` | `number` | `1.5`   | Duration of the flip animation in seconds. |
| `delay`    | `number` | `2.5`   | Delay between flip animations in seconds.  |

## Component Code

You can copy and paste the following code to create this component:

::code-group

    ::CodeViewerTab{label="LogoOrigami.vue" language="vue" componentName="LogoOrigami" type="ui" id="logo-origami"}
    ::

    :CodeViewerTab{label="LogoOrigamiItem.vue" language="vue" componentName="LogoOrigamiItem" type="ui" id="logo-origami"}
    ::

::

## Features

- **Origami Flip Animation**: Animates flipping between multiple child components with an origami-style effect.

- **Customizable Timing**: Adjust the `duration` and `delay` props to control the animation speed and interval.

- **Slot-Based Content**: Accepts multiple child components or content via default slots.

- **Responsive Design**: Designed to adapt to various screen sizes and devices.

- **Easy Integration**: Simple to include in your Vue projects with minimal setup.

## Credits

- Inspired by origami animations and flip effects at [hover.dev](www.hover.dev/components/other#logo-origami)


---
title: Orbit
description: A component that animates content in a circular orbit, with customizable duration, delay, and radius. It also offers an optional orbit path display.
---

::ComponentLoader{label="Preview" componentName="OrbitDemo" type="examples"}
::

## Examples

Synchronized orbit

::ComponentLoader{label="Preview" componentName="OrbitDemoSynchronized" type="examples"}
::

## API

| Prop Name   | Type                  | Default  | Description                                                           |
| ----------- | --------------------- | -------- | --------------------------------------------------------------------- |
| `direction` | `normal` \| `reverse` | `normal` | The direction of the orbit. You can use the constant ORBIT_DIRECTION. |
| `duration`  | `?number`             | `20`     | The duration of the orbit animation in seconds.                       |
| `delay`     | `?number`             | `10`     | Delay in seconds before the animation starts.                         |
| `radius`    | `?number`             | `50`     | Radius of the orbit path in pixels.                                   |
| `path`      | `?boolean`            | `false`  | Displays a circle path for the orbit if `true`.                       |

## Component Code

You can copy and paste the following code to create this component:

::code-group

::CodeViewerTab{filename="Orbit.vue" language="vue" componentName="Orbit" type="ui" id="orbit"}
::

::CodeViewerTab{filename="index.ts" language="typescript" componentName="index" type="ui" id="orbit" extension="ts"}
::

::

## Features

- **Circular Orbit Animation**: The component animates its content in a smooth circular orbit around the center point.
- **Customizable Animation**: The orbit’s duration, delay, and radius are fully adjustable, providing flexibility in animation behavior.

- **Optional Orbit Path**: An optional visual representation of the orbit path can be toggled using the `path` prop.

- **Reversibility**: The orbit direction can be `reverse` by setting the `direction` prop.

- **Responsive and Efficient**: The component handles different container sizes and uses Vue’s reactivity to ensure efficient animation.

## Credits

- Inspired by [Magic UI](https://magicui.design/docs/components/orbiting-circles).
- Credits to [Nathan De Pachtere](https://nathandepachtere.com/) for updating this component.


---
title: Hero
description: Elevate website experience with unique hero blocks.
---

### Hero Section 1

::ComponentLoader{label="Preview" componentName="HeroSection1" type="blocks" id="hero"}
::

#### Components used:

- [Falling Stars Background](https://inspira-ui.com/components/backgrounds/falling-stars)
- [Blur Reveal](https://inspira-ui.com/components/text-animations/blur-reveal)
- [Flip Words](https://inspira-ui.com/components/text-animations/flip-words)
- [Border Beam](https://inspira-ui.com/components/special-effects/border-beam)

### Hero Section 2

::ComponentLoader{label="Preview" componentName="HeroSection2" type="blocks" id="hero"}
::

#### Components used:

- [Vortex Background](https://inspira-ui.com/components/backgrounds/vortex)
- [Animated Tooltip](https://inspira-ui.com/components/miscellaneous/animated-tooltip)
- [Text Highlight](https://inspira-ui.com/components/text-animations/text-highlight)
- [3D Card](https://inspira-ui.com/components/cards/3d-card)


---
title: Testimonials
description: Show testimonials in style
---

### With skewed marquee

::ComponentLoader{label="Preview" componentName="SkewedMarqueeTestimonials" type="blocks" id="testimonials"}
::

### With linear marquee

::ComponentLoader{label="Preview" componentName="LinearMarqueeTestimonials" type="blocks" id="testimonials"}
::

#### Components used

- [Marquee & Review](https://inspira-ui.com/components/miscellaneous/marquee) component.


# Oasis 500M

![](./media/arch.png)

![](./media/thumb.png)

Oasis is an interactive world model developed by [Decart](https://www.decart.ai/) and [Etched](https://www.etched.com/). Based on diffusion transformers, Oasis takes in user keyboard input and generates gameplay in an autoregressive manner. We release the weights for Oasis 500M, a downscaled version of the model, along with inference code for action-conditional frame generation.

For more details, see our [joint blog post](https://oasis-model.github.io/) to learn more.

And to use the most powerful version of the model, be sure to check out the [live demo](https://oasis.us.decart.ai/) as well!

## Setup
```
git clone https://github.com/etched-ai/open-oasis.git
cd open-oasis
# Install pytorch
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
# Install other dependencies
pip install einops diffusers timm av
```

## Download the model weights
Inside the `open-oasis/` directory, run:
```
huggingface-cli login
huggingface-cli download Etched/oasis-500m oasis500m.safetensors # DiT checkpoint
huggingface-cli download Etched/oasis-500m vit-l-20.safetensors  # ViT VAE checkpoint
```

## Basic Usage
We include a basic inference script that loads a prompt frame from a video and generates additional frames conditioned on actions.
```
python generate.py
# Or specify path to checkpoints:
python generate.py --oasis-ckpt <path to oasis500m.safetensors> --vae-ckpt <path to vit-l-20.safetensors>
```
Use a custom image prompt:
```
python generate.py --prompt-path <path to .png, .jpg, or .jpeg>
```
The resulting video will be saved to `video.mp4`. Here's are some examples of a generation from this 500M model!

![](media/sample_0.gif)
![](media/sample_1.gif)

README.md

Inference script for Oasis 500M


[![LinkedIn](https://img.shields.io/badge/LinkedIn-follow-blue)](https://www.linkedin.com/company/athina-ai/posts/?feedView=all)
[![Twitter](https://img.shields.io/twitter/follow/AthinaAI?label=Follow%20@AthinaAI&style=social)](https://x.com/AthinaAI)
[![Share](https://img.shields.io/badge/share-000000?logo=x&logoColor=white)](https://x.com/intent/tweet?text=Check%20out%20this%20project%20on%20GitHub:%20https://github.com/athina-ai/rag-cookbooks)
[![Share](https://img.shields.io/badge/share-0A66C2?logo=linkedin&logoColor=white)](https://www.linkedin.com/sharing/share-offsite/?url=https://github.com/athina-ai/rag-cookbooks)
[![Share](https://img.shields.io/badge/share-FF4500?logo=reddit&logoColor=white)](https://www.reddit.com/submit?title=Check%20out%20this%20project%20on%20GitHub:%20https://github.com/athina-ai/rag-cookbooks)

>If you find this repository helpful, please consider giving it a star⭐

# Advanced + Agentic RAG Cookbooks👨🏻💻
Welcome to the comprehensive collection of advanced + agentic Retrieval-Augmented Generation (RAG) techniques.

## Introduction🚀
RAG is a popular method that improves accuracy and relevance by finding the right information from reliable sources and transforming it into useful answers. This repository covers the most effective advanced + agentic RAG techniques with clear implementations and explanations.

The main goal of this repository is to provide a helpful resource for researchers and developers looking to use advanced RAG techniques in their projects. Building these techniques from scratch takes time, and finding proper evaluation methods can be challenging. This repository simplifies the process by offering ready-to-use implementations and guidance on how to evaluate them.
>[!NOTE]
>This repository starts with naive RAG as a foundation and progresses to advanced and agentic techniques. It also includes research papers/references for each RAG technique, which you can explore for further reading.

## Introduction to RAG💡
Large Language Models are trained on a fixed dataset, which limits their ability to handle private or recent information. They can sometimes "hallucinate", providing incorrect yet believable answers. Fine-tuning can help but it is expensive and not ideal for retraining again and again on new data. The Retrieval-Augmented Generation (RAG) framework addresses this issue by using external documents to improve the LLM's responses through in-context learning. RAG ensures that the information provided by the LLM is not only contextually relevant but also accurate and up-to-date.

![final diagram](https://github.com/user-attachments/assets/508b3a87-ac46-4bf7-b849-145c5465a6c0)

There are four main components in RAG:

**Indexing:** First, documents (in any format) are split into chunks, and embeddings for these chunks are created. These embeddings are then added to a vector store.

**Retriever:** Then, the retriever finds the most relevant documents based on the user's query, using techniques like vector similarity from the vector store.

**Augment:** After that, the Augment part combines the user's query with the retrieved context into a prompt, ensuring the LLM has the information needed to generate accurate responses.

**Generate:** Finally, the combined query and prompt are passed to the model, which then generates the final response to the user's query.

These components of RAG allow the model to access up-to-date, accurate information and generate responses based on external knowledge. However, to ensure RAG systems are functioning effectively, it’s essential to evaluate their performance.

## RAG Evaluation📊
Evaluating RAG applications is important for understanding how well these systems work. We can see how effectively they combine information retrieval with generative models by checking their accuracy and relevance. This evaluation helps improve RAG applications in tasks like text summarization, chatbots, and question-answering. It also identifies areas for improvement, ensuring that these systems provide trustworthy responses as information changes. Overall, effective evaluation helps optimize performance and builds confidence in RAG applications for real-world use. These notebooks contain an end-to-end RAG implementation + RAG evaluation part in Athina AI.

![evals diagram](https://github.com/user-attachments/assets/65c2b5af-a931-40c5-b006-87567aef019f)

## Advanced RAG Techniques⚙
Here are the details of all the Advanced RAG techniques covered in this repository.

| Technique                    | Tools                        | Description                                                       | Notebooks |
|---------------------------------|------------------------------|--------------------------------------------------------------|-----------|
| Naive RAG      | LangChain, Pinecone, Athina AI                    | Combines retrieved data with LLMs for simple and effective responses.| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/athina-ai/rag-cookbooks/blob/main/advanced_rag_techniques/naive_rag.ipynb) |
| Hybrid RAG      | LangChain, Chromadb, Athina AI                    | Combines vector search and traditional methods like BM25 for better information retrieval.| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/athina-ai/rag-cookbooks/blob/main/advanced_rag_techniques/hybrid_rag.ipynb) |
| Hyde RAG      | LangChain, Weaviate, Athina AI                    | Creates hypothetical document embeddings to find relevant information for a query.| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/athina-ai/rag-cookbooks/blob/main/advanced_rag_techniques/hyde_rag.ipynb) |
| Parent Document Retriever      | LangChain, Chromadb, Athina AI                    | Breaks large documents into small parts and retrieves the full document if a part matches the query.| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/athina-ai/rag-cookbooks/blob/main/advanced_rag_techniques/parent_document_retriever.ipynb) |
| RAG fusion      | LangChain, LangSmith, Qdrant, Athina AI                    | Generates sub-queries, ranks documents with Reciprocal Rank Fusion, and uses top results for accurate responses.| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/athina-ai/rag-cookbooks/blob/main/advanced_rag_techniques/fusion_rag.ipynb) |
| Contextual RAG      | LangChain, Chromadb, Athina AI                    | Compresses retrieved documents to keep only relevant details for concise and accurate responses.| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/athina-ai/rag-cookbooks/blob/main/advanced_rag_techniques/contextual_rag.ipynb) |
| Rewrite Retrieve Read     | LangChain, Chromadb, Athina AI                    | Improves query, retrieves better data, and generates accurate answers.| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/athina-ai/rag-cookbooks/blob/main/advanced_rag_techniques/rewrite_retrieve_read.ipynb) |
| Unstructured RAG     | LangChain, LangGraph, FAISS, Athina AI, Unstructured                    | This method designed to handle documents that combine text, tables, and images.| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/athina-ai/rag-cookbooks/blob/main/advanced_rag_techniques/basic_unstructured_rag.ipynb) |

## Agentic RAG Techniques⚙
Here are the details of all the Agentic RAG techniques covered in this repository.

| Technique                    | Tools                        | Description                                                       | Notebooks |
|---------------------------------|------------------------------|--------------------------------------------------------------|-----------|
| Basic Agentic RAG      | LangChain, FAISS, Athina AI                    | Agentic RAG uses AI agents to find and generate answers using tools like vectordb and web searches.| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/athina-ai/rag-cookbooks/blob/main/agentic_rag_techniques/basic_agentic_rag.ipynb) |
| Corrective RAG      | LangChain, LangGraph, Chromadb, Athina AI                    | Refines relevant documents, removes irrelevant ones or does the web search.| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/athina-ai/rag-cookbooks/blob/main/agentic_rag_techniques/corrective_rag.ipynb) |
| Self RAG     | LangChain, LangGraph, FAISS, Athina AI                    | Reflects on retrieved data to ensure accurate and complete responses.| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/athina-ai/rag-cookbooks/blob/main/agentic_rag_techniques/self_rag.ipynb) |
| Adaptive RAG      | LangChain, LangGraph, FAISS, Athina AI                    | Adjusts retrieval methods based on query type, using indexed data or web search.| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/athina-ai/rag-cookbooks/blob/main/agentic_rag_techniques/adaptive_rag.ipynb) |
| ReAct RAG      | LangChain, LangGraph, FAISS, Athina AI                    |  System combining reasoning and retrieval for context-aware responses| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/athina-ai/rag-cookbooks/blob/main/agentic_rag_techniques/react_rag.ipynb) |

## Demo🎬
A quick demo of how each notebook works:

https://github.com/user-attachments/assets/c6f17961-40a1-4cca-ab1f-2c8fa3d71a7a

## Getting Started🛠
First, clone this repository by using the following command:
```bash
git clone https://github.com/athina-ai/rag-cookbooks.git
```
Next, navigate to the project directory:
```bash
cd rag-cookbooks
```
Once you are in the 'rag-cookbooks' directory, follow the detailed implementation for each technique.

## Creators + Contributors👨🏻💻
[![Contributors](https://contrib.rocks/image?repo=athina-ai/cookbooks)](https://github.com/athina-ai/cookbooks/graphs/contributors)

## Contributing🤝
If you have a new technique or improvement to suggest, we welcome contributions from the community!

## License📝
This project is licensed under [MIT License](LICENSE)

README.md

This repository contains various advanced techniques for Retrieval-Augmented Generation (RAG) systems.


# hertz-dev

Hertz-dev is an open-source, first-of-its-kind base model for full-duplex conversational audio.

See our blog post for more details: https://si.inc/hertz-dev/

## Setup

Inference is known to work on Python 3.10 and CUDA 12.1. Other versions have not been tested as thoroughly. If you want to use CUDA 12.1, you'll need to install torch with `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121` before running `pip install -r requirements.txt`.

On Ubuntu you may need to install libportaudio: `sudo apt-get install libportaudio2`

All three scripts will automatically download the models to the `./ckpt` directory, and checkpoints are also accessible at https://ckpt.si.inc/hertz-dev/index.txt

## Usage

We recommend starting by using `inference.ipynb` to generate one- or two-channel completions from a prompt.

Then, you can use `inference_client.py` and `inference_server.py` to talk to the model live through your microphone.
These are currently experimental, and have primarily been tested with Ubuntu on the server and MacOS on the client.

Alternatively, you can use `inference_client_webrtc.py`, which is built on [streamlit](https://streamlit.io/) + [streamlit-webrtc](https://github.com/whitphx/streamlit-webrtc) and runs in a browser:
```bash
# Install additional requirements
pip install -r requirements_webrtc.txt
# Run the client
streamlit run inference_client_webrtc.py
```
Then, access the client at [http://localhost:8501](http://localhost:8501).

**Note**: If you host the streamlit client anywhere other than `localhost` you will need to connect with https to avoid errors (see [here](https://github.com/whitphx/streamlit-webrtc?tab=readme-ov-file#serving-from-remote-host) for more info). An easy workaround is to `ssh` from the client into the server with port forwarding `ssh -L 127.0.0.1:8501:remote-host:8501 user@remote-host`, after which you can access the client at [http://localhost:8501](http://localhost:8501) as usual. If serving from a remote host with https, you may need to use a STUN server to establish the connection. You can do this by passing the `--use_ice_servers` flag: `streamlit run inference_client_webrtc.py -- --use_ice_servers`.

README.md

first base model for full-duplex conversational audio


# Changelog

Notable changes to this project will be documented in this file.

## [v0.2.0post1] - 2025-02-07
- Fix: Building Kokoro from source with adjustments, to avoid CUDA lock
- Fixed ARM64 compatibility on Spacy dep to avoid emulation slowdown
- Added g++ for Japanese language support
- Temporarily disabled Vietnamese language support due to ARM64 compatibility issues

## [v0.2.0-pre] - 2025-02-06
### Added
- Complete Model Overhaul:
  - Upgraded to Kokoro v1.0 model architecture
  - Pre-installed multi-language support from Misaki:
    - English (en), Japanese (ja), Korean (ko),Chinese (zh), Vietnamese (vi)
  - All voice packs included for supported languages, along with the original versions.
- Enhanced Audio Generation Features:
  - Per-word timestamped caption generation
  - Phoneme-based audio generation capabilities
  - Detailed phoneme generation
- Web UI Improvements:
  - Improved voice mixing with weighted combinations
  - Text file upload support
  - Enhanced formatting and user interface
  - Cleaner UI (in progress)
  - Integration with https://github.com/hexgrad/kokoro and https://github.com/hexgrad/misaki packages

### Removed
- Deprecated support for Kokoro v0.19 model

### Changes
- Combine Voices endpoint now returns a .pt file, with generation combinations generated on the fly otherwise

## [v0.1.4] - 2025-01-30
### Added
- Smart Chunking System:
  - New text_processor with smart_split for improved sentence boundary detection
  - Dynamically adjusts chunk sizes based on sentence structure, using phoneme/token information in an intial pass
  - Should avoid ever going over the 510 limit per chunk, while preserving natural cadence
- Web UI Added (To Be Replacing Gradio):
  - Integrated streaming with tempfile generation
  - Download links available in X-Download-Path header
  - Configurable cleanup triggers for temp files
- Debug Endpoints:
  - /debug/threads for thread information and stack traces
  - /debug/storage for temp file and output directory monitoring
  - /debug/system for system resource information
  - /debug/session_pools for ONNX/CUDA session status
- Automated Model Management:
  - Auto-download from releases page
  - Included download scripts for manual installation
  - Pre-packaged voice models in repository

### Changed
- Significant architectural improvements:
  - Multi-model architecture support
  - Enhanced concurrency handling
  - Improved streaming header management
  - Better resource/session pool management

## [v0.1.2] - 2025-01-23
### Structural Improvements
- Models can be manually download and placed in api/src/models, or use included script
- TTSGPU/TPSCPU/STTSService classes replaced with a ModelManager service
  - CPU/GPU of each of ONNX/PyTorch (Note: Only Pytorch GPU, and ONNX CPU/GPU have been tested)
  - Should be able to improve new models as they become available, or new architectures, in a more modular way
- Converted a number of internal processes to async handling to improve concurrency
- Improving separation of concerns towards plug-in and modular structure, making PR's and new features easier

### Web UI (test release)
- An integrated simple web UI has been added on the FastAPI server directly
  - This can be disabled via core/config.py or ENV variables if desired.
  - Simplifies deployments, utility testing, aesthetics, etc
  - Looking to deprecate/collaborate/hand off the Gradio UI

## [v0.1.0] - 2025-01-13
### Changed
- Major Docker improvements:
  - Baked model directly into Dockerfile for improved deployment reliability
  - Switched to uv for dependency management
  - Streamlined container builds and reduced image sizes
- Dependency Management:
  - Migrated from pip/poetry to uv for faster, more reliable package management
  - Added uv.lock for deterministic builds
  - Updated dependency resolution strategy

## [v0.0.5post1] - 2025-01-11
### Fixed
- Docker image tagging and versioning improvements (-gpu, -cpu, -ui)
- Minor vram management improvements
- Gradio bugfix causing crashes and errant warnings
- Updated GPU and UI container configurations

## [v0.0.5] - 2025-01-10
### Fixed
- Stabilized issues with images tagging and structures from v0.0.4
- Added automatic master to develop branch synchronization
- Improved release tagging and structures
- Initial CI/CD setup

## 2025-01-04
### Added
- ONNX Support:
  - Added single batch ONNX support for CPU inference
  - Roughly 0.4 RTF (2.4x real-time speed)

### Modified
- Code Refactoring:
  - Work on modularizing phonemizer and tokenizer into separate services
  - Incorporated these services into a dev endpoint
- Testing and Benchmarking:
  - Cleaned up benchmarking scripts
  - Cleaned up test scripts
  - Added auto-WAV validation scripts

## 2025-01-02
- Audio Format Support:
  - Added comprehensive audio format conversion support (mp3, wav, opus, flac)

## 2025-01-01
### Added
- Gradio Web Interface:
  - Added simple web UI utility for audio generation from input or txt file

### Modified
#### Configuration Changes
- Updated Docker configurations:
  - Changes to `Dockerfile`:
    - Improved layer caching by separating dependency and code layers
  - Updates to `docker-compose.yml` and `docker-compose.cpu.yml`:
    - Removed commit lock from model fetching to allow automatic model updates from HF
    - Added git index lock cleanup

#### API Changes
- Modified `api/src/main.py`
- Updated TTS service implementation in `api/src/services/tts.py`:
  - Added device management for better resource control:
    - Voices are now copied from model repository to api/src/voices directory for persistence
  - Refactored voice pack handling:
    - Removed static voice pack dictionary
    - On-demand voice loading from disk
  - Added model warm-up functionality:
    - Model now initializes with a dummy text generation
    - Uses default voice (af.pt) for warm-up
    - Model is ready for inference on first request

CHANGELOG.md

Dockerized FastAPI wrapper for Kokoro-82M text-to-speech model w/CPU ONNX and NVIDIA GPU PyTorch support, handling, and auto-stitching


# _`FastKoko`_
[![Tests](https://img.shields.io/badge/tests-69%20passed-darkgreen)]()
[![Coverage](https://img.shields.io/badge/coverage-52%25-tan)]()
[![Try on Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Try%20on-Spaces-blue)](https://huggingface.co/spaces/Remsky/Kokoro-TTS-Zero)

[![Kokoro](https://img.shields.io/badge/kokoro-v0.7.9::31a2b63-BB5420)](https://github.com/hexgrad/kokoro)
[![Misaki](https://img.shields.io/badge/misaki-v0.7.9::ebc76c2-B8860B)](https://github.com/hexgrad/misaki)

[![Tested at Model Commit](https://img.shields.io/badge/last--tested--model--commit-1.0::9901c2b-blue)](https://huggingface.co/hexgrad/Kokoro-82M/commit/9901c2b79161b6e898b7ea857ae5298f47b8b0d6)

Dockerized FastAPI wrapper for [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) text-to-speech model
- Multi-language support (English, Japanese, Korean, Chinese, _Vietnamese soon_)
- OpenAI-compatible Speech endpoint, NVIDIA GPU accelerated or CPU inference with PyTorch
- ONNX support coming soon, see v0.1.5 and earlier for legacy ONNX support in the interim
- Debug endpoints for monitoring system stats, integrated web UI on localhost:8880/web
- Phoneme-based audio generation, phoneme generation
- Per-word timestamped caption generation
- Voice mixing with weighted combinations

### Integration Guides
 [![Helm Chart](https://img.shields.io/badge/Helm%20Chart-black?style=flat&logo=helm&logoColor=white)](https://github.com/remsky/Kokoro-FastAPI/wiki/Setup-Kubernetes) [![DigitalOcean](https://img.shields.io/badge/DigitalOcean-black?style=flat&logo=digitalocean&logoColor=white)](https://github.com/remsky/Kokoro-FastAPI/wiki/Integrations-DigitalOcean) [![SillyTavern](https://img.shields.io/badge/SillyTavern-black?style=flat&color=red)](https://github.com/remsky/Kokoro-FastAPI/wiki/Integrations-SillyTavern)
[![OpenWebUI](https://img.shields.io/badge/OpenWebUI-black?style=flat&color=white)](https://github.com/remsky/Kokoro-FastAPI/wiki/Integrations-OpenWebUi)

## Get Started

Quickest Start (docker run)

Pre built images are available to run, with arm/multi-arch support, and baked in models
Refer to the core/config.py file for a full list of variables which can be managed via the environment

```bash
# the `latest` tag can be used, but should not be considered stable as it may include `nightly` branch builds
# it may have some bonus features however, and feedback/testing is welcome

docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:v0.2.2 # CPU, or:
docker run --gpus all -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu:v0.2.2  #NVIDIA GPU
```

Quick Start (docker compose)

1. Install prerequisites, and start the service using Docker Compose (Full setup including UI):
   - Install [Docker](https://www.docker.com/products/docker-desktop/)
   - Clone the repository:
        ```bash
        git clone https://github.com/remsky/Kokoro-FastAPI.git
        cd Kokoro-FastAPI

        cd docker/gpu  # For GPU support
        # or cd docker/cpu  # For CPU support
        docker compose up --build

        # Models will auto-download, but if needed you can manually download:
        python docker/scripts/download_model.py --output api/src/models/v1_0

        # Or run directly via UV:
        ./start-gpu.sh  # For GPU support
        ./start-cpu.sh  # For CPU support
        ```

Direct Run (via uv)

1. Install prerequisites ():
   - Install [astral-uv](https://docs.astral.sh/uv/)
   - Install [espeak-ng](https://github.com/espeak-ng/espeak-ng) in your system if you want it available as a fallback for unknown words/sounds. The upstream libraries may attempt to handle this, but results have varied.
   - Clone the repository:
        ```bash
        git clone https://github.com/remsky/Kokoro-FastAPI.git
        cd Kokoro-FastAPI
        ```

        Run the [model download script](https://github.com/remsky/Kokoro-FastAPI/blob/master/docker/scripts/download_model.py) if you haven't already

        Start directly via UV (with hot-reload)
        ```bash
        ./start-cpu.sh OR
        ./start-gpu.sh
        ```

 Up and Running?

Run locally as an OpenAI-Compatible Speech Endpoint

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8880/v1", api_key="not-needed"
)

with client.audio.speech.with_streaming_response.create(
    model="kokoro",
    voice="af_sky+af_bella", #single or multiple voicepack combo
    input="Hello world!"
  ) as response:
      response.stream_to_file("output.mp3")
```

- The API will be available at http://localhost:8880
- API Documentation: http://localhost:8880/docs

- Web Interface: http://localhost:8880/web

## Features

OpenAI-Compatible Speech Endpoint

```python
# Using OpenAI's Python library
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8880/v1", api_key="not-needed")
response = client.audio.speech.create(
    model="kokoro",
    voice="af_bella+af_sky", # see /api/src/core/openai_mappings.json to customize
    input="Hello world!",
    response_format="mp3"
)

response.stream_to_file("output.mp3")
```
Or Via Requests:
```python
import requests

response = requests.get("http://localhost:8880/v1/audio/voices")
voices = response.json()["voices"]

# Generate audio
response = requests.post(
    "http://localhost:8880/v1/audio/speech",
    json={
        "model": "kokoro",
        "input": "Hello world!",
        "voice": "af_bella",
        "response_format": "mp3",  # Supported: mp3, wav, opus, flac
        "speed": 1.0
    }
)

# Save audio
with open("output.mp3", "wb") as f:
    f.write(response.content)
```

Quick tests (run from another terminal):
```bash
python examples/assorted_checks/test_openai/test_openai_tts.py # Test OpenAI Compatibility
python examples/assorted_checks/test_voices/test_all_voices.py # Test all available voices
```

Voice Combination

- Weighted voice combinations using ratios (e.g., "af_bella(2)+af_heart(1)" for 67%/33% mix)
- Ratios are automatically normalized to sum to 100%
- Available through any endpoint by adding weights in parentheses
- Saves generated voicepacks for future use

Combine voices and generate audio:
```python
import requests
response = requests.get("http://localhost:8880/v1/audio/voices")
voices = response.json()["voices"]

# Example 1: Simple voice combination (50%/50% mix)
response = requests.post(
    "http://localhost:8880/v1/audio/speech",
    json={
        "input": "Hello world!",
        "voice": "af_bella+af_sky",  # Equal weights
        "response_format": "mp3"
    }
)

# Example 2: Weighted voice combination (67%/33% mix)
response = requests.post(
    "http://localhost:8880/v1/audio/speech",
    json={
        "input": "Hello world!",
        "voice": "af_bella(2)+af_sky(1)",  # 2:1 ratio = 67%/33%
        "response_format": "mp3"
    }
)

# Example 3: Download combined voice as .pt file
response = requests.post(
    "http://localhost:8880/v1/audio/voices/combine",
    json="af_bella(2)+af_sky(1)"  # 2:1 ratio = 67%/33%
)

# Save the .pt file
with open("combined_voice.pt", "wb") as f:
    f.write(response.content)

# Use the downloaded voice file
response = requests.post(
    "http://localhost:8880/v1/audio/speech",
    json={
        "input": "Hello world!",
        "voice": "combined_voice",  # Use the saved voice file
        "response_format": "mp3"
    }
)

```

Multiple Output Audio Formats

- mp3
- wav
- opus
- flac
- m4a
- pcm

Streaming Support

```python
# OpenAI-compatible streaming
from openai import OpenAI
client = OpenAI(
    base_url="http://localhost:8880/v1", api_key="not-needed")

# Stream to file
with client.audio.speech.with_streaming_response.create(
    model="kokoro",
    voice="af_bella",
    input="Hello world!"
) as response:
    response.stream_to_file("output.mp3")

# Stream to speakers (requires PyAudio)
import pyaudio
player = pyaudio.PyAudio().open(
    format=pyaudio.paInt16,
    channels=1,
    rate=24000,
    output=True
)

with client.audio.speech.with_streaming_response.create(
    model="kokoro",
    voice="af_bella",
    response_format="pcm",
    input="Hello world!"
) as response:
    for chunk in response.iter_bytes(chunk_size=1024):
        player.write(chunk)
```

Or via requests:
```python
import requests

response = requests.post(
    "http://localhost:8880/v1/audio/speech",
    json={
        "input": "Hello world!",
        "voice": "af_bella",
        "response_format": "pcm"
    },
    stream=True
)

for chunk in response.iter_content(chunk_size=1024):
    if chunk:
        # Process streaming chunks
        pass
```

Key Streaming Metrics:
- First token latency @ chunksize
    - ~300ms  (GPU) @ 400
    - ~3500ms (CPU) @ 200 (older i7)
    - ~<1s    (CPU) @ 200 (M3 Pro)
- Adjustable chunking settings for real-time playback

*Note: Artifacts in intonation can increase with smaller chunks*

## Processing Details

Performance Benchmarks

Benchmarking was performed on generation via the local API using text lengths up to feature-length books (~1.5 hours output), measuring processing time and realtime factor. Tests were run on:
- Windows 11 Home w/ WSL2
- NVIDIA 4060Ti 16gb GPU @ CUDA 12.1
- 11th Gen i7-11700 @ 2.5GHz
- 64gb RAM
- WAV native output
- H.G. Wells - The Time Machine (full text)

Key Performance Metrics:
- Realtime Speed: Ranges between 35x-100x (generation time to output audio length)
- Average Processing Rate: 137.67 tokens/second (cl100k_base)

GPU Vs. CPU

```bash
# GPU: Requires NVIDIA GPU with CUDA 12.8 support (~35x-100x realtime speed)
cd docker/gpu
docker compose up --build

# CPU: PyTorch CPU inference
cd docker/cpu
docker compose up --build

```
*Note: Overall speed may have reduced somewhat with the structural changes to accommodate streaming. Looking into it*

Natural Boundary Detection

- Automatically splits and stitches at sentence boundaries
- Helps to reduce artifacts and allow long form processing as the base model is only currently configured for approximately 30s output

The model is capable of processing up to a 510 phonemized token chunk at a time, however, this can often lead to 'rushed' speech or other artifacts. An additional layer of chunking is applied in the server, that creates flexible chunks with a `TARGET_MIN_TOKENS` , `TARGET_MAX_TOKENS`, and `ABSOLUTE_MAX_TOKENS` which are configurable via environment variables, and set to 175, 250, 450 by default

Timestamped Captions & Phonemes

Generate audio with word-level timestamps without streaming:
```python
import requests
import base64
import json

response = requests.post(
    "http://localhost:8880/dev/captioned_speech",
    json={
        "model": "kokoro",
        "input": "Hello world!",
        "voice": "af_bella",
        "speed": 1.0,
        "response_format": "mp3",
        "stream": False,
    },
    stream=False
)

with open("output.mp3","wb") as f:

    audio_json=json.loads(response.content)

    # Decode base 64 stream to bytes
    chunk_audio=base64.b64decode(audio_json["audio"].encode("utf-8"))

    # Process streaming chunks
    f.write(chunk_audio)

    # Print word level timestamps
    print(audio_json["timestamps"])
```

Generate audio with word-level timestamps with streaming:
```python
import requests
import base64
import json

response = requests.post(
    "http://localhost:8880/dev/captioned_speech",
    json={
        "model": "kokoro",
        "input": "Hello world!",
        "voice": "af_bella",
        "speed": 1.0,
        "response_format": "mp3",
        "stream": True,
    },
    stream=True
)

f=open("output.mp3","wb")
for chunk in response.iter_lines(decode_unicode=True):
    if chunk:
        chunk_json=json.loads(chunk)

        # Decode base 64 stream to bytes
        chunk_audio=base64.b64decode(chunk_json["audio"].encode("utf-8"))

        # Process streaming chunks
        f.write(chunk_audio)

        # Print word level timestamps
        print(chunk_json["timestamps"])
```

Phoneme & Token Routes

Convert text to phonemes and/or generate audio directly from phonemes:
```python
import requests

def get_phonemes(text: str, language: str = "a"):
    """Get phonemes and tokens for input text"""
    response = requests.post(
        "http://localhost:8880/dev/phonemize",
        json={"text": text, "language": language}  # "a" for American English
    )
    response.raise_for_status()
    result = response.json()
    return result["phonemes"], result["tokens"]

def generate_audio_from_phonemes(phonemes: str, voice: str = "af_bella"):
    """Generate audio from phonemes"""
    response = requests.post(
        "http://localhost:8880/dev/generate_from_phonemes",
        json={"phonemes": phonemes, "voice": voice},
        headers={"Accept": "audio/wav"}
    )
    if response.status_code != 200:
        print(f"Error: {response.text}")
        return None
    return response.content

# Example usage
text = "Hello world!"
try:
    # Convert text to phonemes
    phonemes, tokens = get_phonemes(text)
    print(f"Phonemes: {phonemes}")  # e.g. ðɪs ɪz ˈoʊnli ɐ tˈɛst
    print(f"Tokens: {tokens}")      # Token IDs including start/end tokens

    # Generate and save audio
    if audio_bytes := generate_audio_from_phonemes(phonemes):
        with open("speech.wav", "wb") as f:
            f.write(audio_bytes)
        print(f"Generated {len(audio_bytes)} bytes of audio")
except Exception as e:
    print(f"Error: {e}")
```

See `examples/phoneme_examples/generate_phonemes.py` for a sample script.

Debug Endpoints

Monitor system state and resource usage with these endpoints:

- `/debug/threads` - Get thread information and stack traces
- `/debug/storage` - Monitor temp file and output directory usage
- `/debug/system` - Get system information (CPU, memory, GPU)
- `/debug/session_pools` - View ONNX session and CUDA stream status

Useful for debugging resource exhaustion or performance issues.

## Known Issues

Versioning & Development

I'm doing what I can to keep things stable, but we are on an early and rapid set of build cycles here.
If you run into trouble, you may have to roll back a version on the release tags if something comes up, or build up from source and/or troubleshoot + submit a PR. Will leave the branch up here for the last known stable points:

`v0.1.4`
`v0.0.5post1`

Free and open source is a community effort, and I love working on this project, though there's only really so many hours in a day. If you'd like to support the work, feel free to open a PR, buy me a coffee, or report any bugs/features/etc you find during use.

Linux GPU Permissions

Some Linux users may encounter GPU permission issues when running as non-root.
Can't guarantee anything, but here are some common solutions, consider your security requirements carefully

### Option 1: Container Groups (Likely the best option)
```yaml
services:
  kokoro-tts:
    # ... existing config ...
    group_add:
      - "video"
      - "render"
```

### Option 2: Host System Groups
```yaml
services:
  kokoro-tts:
    # ... existing config ...
    user: "${UID}:${GID}"
    group_add:
      - "video"
```
Note: May require adding host user to groups: `sudo usermod -aG docker,video $USER` and system restart.

### Option 3: Device Permissions (Use with caution)
```yaml
services:
  kokoro-tts:
    # ... existing config ...
    devices:
      - /dev/nvidia0:/dev/nvidia0
      - /dev/nvidiactl:/dev/nvidiactl
      - /dev/nvidia-uvm:/dev/nvidia-uvm
```
⚠ Warning: Reduces system security. Use only in development environments.

Prerequisites: NVIDIA GPU, drivers, and container toolkit must be properly configured.

Visit [NVIDIA Container Toolkit installation](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) for more detailed information

## Model and License

Model

This API uses the [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) model from HuggingFace.

Visit the model page for more details about training, architecture, and capabilities. I have no affiliation with any of their work, and produced this wrapper for ease of use and personal projects.

License
This project is licensed under the Apache License 2.0 - see below for details:

- The Kokoro model weights are licensed under Apache 2.0 (see [model page](https://huggingface.co/hexgrad/Kokoro-82M))
- The FastAPI wrapper code in this repository is licensed under Apache 2.0 to match
- The inference code adapted from StyleTTS2 is MIT licensed

The full Apache 2.0 license text can be found at: https://www.apache.org/licenses/LICENSE-2.0

README.md


---
name: Bug report
about: Create a report to help us improve
title: ''
labels: ''
assignees: ''

---

**Describe the bug**
A clear and concise description of what the bug is.

**Screenshots or console output**
If applicable, add screenshots to help explain your problem. When doing so., please ensure you have the first command that triggered the trace and/or the command that started up your build included, otherwise it is difficult to diagnose.

**Branch / Deployment used**
Let us know if it's the master branch, or the stable branch indicated in the readme, as well as if you're running it locally, in the cloud, via the docker compose (cpu or gpu), or direct docker run commands. Please include the exact commands used to run in the latter cases.

**Operating System**
Include the platform, version numbers of your docker, etc. Whether its GPU (Nvidia or other) or CPU, Mac, Linux, Windows, etc.

**Additional context**
Add any other context about the problem here.


---
name: Feature request
about: Suggest an idea for this project
title: ''
labels: ''
assignees: ''

---

**Describe the feature you'd like**
A clear and concise description of what you want to happen. Is it a quality of life improvement, something new entirely?

**Describe alternatives you've considered**
A clear and concise description of any alternative solutions or features you've considered. Consider whether it could be submitted as PR, or you'd need a hand to do so

**Additional context**
Add any other context or screenshots about the feature request here.


# ESpeak-NG Setup Fix

## Issue Description

Users are reporting two distinct errors:

1. Missing espeak-ng-data/phontab file:
```
Error processing file '/home/runner/work/espeakng-loader/espeakng-loader/espeak-ng/_dynamic/share/espeak-ng-data/phontab': No such file or directory.
```

2. Invalid pipeline state:
```
Error generating speech: The object is in an invalid state.
```

## Root Cause Analysis

### 1. ESpeak-NG Data Issue

The dependency chain has changed:
```
Before:
kokoro-fastapi (phonemizer 3.3.0) -> kokoro -> misaki -> phonemizer

After:
kokoro-fastapi -> kokoro -> misaki -> phonemizer-fork + espeakng-loader
```

The issue arises because:
1. misaki now uses espeakng-loader to manage espeak paths
2. espeakng-loader looks for data in its package directory
3. We have a direct dependency on phonemizer 3.3.0 that conflicts

### 2. Pipeline State Issue
The "invalid state" error occurs due to device mismatch in pipeline creation.

## Solution

### 1. For ESpeak-NG Data

Update dependencies and environment:

1. Remove direct phonemizer dependency:
```diff
- "phonemizer==3.3.0",  # Remove this
```

2. Let misaki handle phonemizer-fork and espeakng-loader

3. Set environment variable in Dockerfile:
```dockerfile
ENV PHONEMIZER_ESPEAK_PATH=/usr/bin \
    PHONEMIZER_ESPEAK_DATA=/usr/share/espeak-ng-data \
    ESPEAK_DATA_PATH=/usr/share/espeak-ng-data  # Add this
```

This approach:
- Works with misaki's new dependencies
- Maintains our working espeak setup
- Avoids complex file copying or path manipulation

### 2. For Pipeline State

Use kokoro_v1's pipeline management:
```python
# Instead of creating pipelines directly:
# pipeline = KPipeline(...)

# Use backend's pipeline management:
pipeline = backend._get_pipeline(pipeline_lang_code)
```

## Implementation Steps

1. Update pyproject.toml:
   - Remove direct phonemizer dependency
   - Keep misaki dependency as is

2. Update Dockerfiles:
   - Add ESPEAK_DATA_PATH environment variable
   - Keep existing espeak-ng setup

3. Update tts_service.py:
   - Use backend's pipeline management
   - Add proper error handling

## Testing

1. Test espeak-ng functionality:
   ```bash
   # Verify environment variables
   echo $ESPEAK_DATA_PATH
   echo $PHONEMIZER_ESPEAK_DATA

   # Check data directory
   ls /usr/share/espeak-ng-data
   ```

2. Test pipeline state:
   - Test on both CPU and GPU
   - Verify no invalid state errors
   - Test with different voice models

## Success Criteria

1. No espeak-ng-data/phontab file errors
2. No invalid state errors
3. Consistent behavior across platforms
4. Successful CI/CD pipeline runs

## Future Considerations

1. Potential PR to misaki:
   - Add fallback mechanism if espeakng-loader fails
   - Make path configuration more flexible
   - Add better error messages

2. Environment Variable Documentation:
   - Document ESPEAK_DATA_PATH requirement
   - Explain interaction with espeakng-loader
   - Provide platform-specific setup instructions

## Notes

- This solution works with misaki's new dependencies while maintaining our setup
- Environment variable approach is simpler than file copying
- May want to contribute improvements back to misaki later


# Streaming Audio Writer Analysis

This auto-document provides an in-depth technical analysis of the `StreamingAudioWriter` class, detailing the streaming and non-streaming paths, supported formats, header management, and challenges faced in the implementation.

## Overview

The `StreamingAudioWriter` class is designed to handle streaming audio format conversions efficiently. It supports various audio formats and provides methods to write audio data in chunks, finalize the stream, and manage audio headers meticulously to ensure compatibility and integrity of the resulting audio files.

## Supported Formats

The class supports the following audio formats:

- **WAV**
- **OGG**
- **Opus**
- **FLAC**
- **MP3**
- **AAC**
- **PCM**

## Initialization

Upon initialization, the class sets up format-specific configurations to prepare for audio data processing:

- **WAV**:
  - Writes an initial WAV header with placeholders for file size (`RIFF` chunk) and data size (`data` chunk).
  - Utilizes the `_write_wav_header` method to generate the header.

- **OGG/Opus/FLAC**:
  - Uses `soundfile.SoundFile` to write audio data to a memory buffer (`BytesIO`).
  - Configures the writer with appropriate format and subtype based on the specified format.

- **MP3/AAC**:
  - Utilizes `pydub.AudioSegment` for incremental writing.
  - Initializes an empty `AudioSegment` as the encoder to accumulate audio data.

- **PCM**:
  - Prepares to write raw PCM bytes without additional headers.

Initialization ensures that each format is correctly configured to handle the specific requirements of streaming and finalizing audio data.

## Streaming Path

### Writing Chunks

The `write_chunk` method handles the incoming audio data, processing it according to the specified format:

- **WAV**:
  - **First Chunk**: Writes the initial WAV header to the buffer.
  - **Subsequent Chunks**: Writes raw PCM data directly after the header.
  - Updates `bytes_written` to track the total size of audio data written.

- **OGG/Opus/FLAC**:
  - Writes audio data to the `soundfile` buffer.
  - Flushes the writer to ensure data integrity.
  - Retrieves the current buffer contents and truncates the buffer for the next chunk.

- **MP3/AAC**:
  - Converts incoming audio data (`np.ndarray`) to a `pydub.AudioSegment`.
  - Accumulates segments in the encoder.
  - Exports the current state to the output buffer without writing duration metadata or XING headers for chunks.
  - Resets the encoder to prevent memory growth after exporting.

- **PCM**:
  - Directly writes raw bytes from the audio data to the output buffer.

### Finalizing

Finalizing the audio stream involves ensuring that all audio data is correctly written and that headers are updated to reflect the accurate file and data sizes:

- **WAV**:
  - Rewrites the `RIFF` and `data` chunks in the header with the actual file size (`bytes_written + 36`) and data size (`bytes_written`).
  - Creates a new buffer with the complete WAV file by copying audio data from the original buffer starting at byte 44 (end of the initial header).

- **OGG/Opus/FLAC**:
  - Closes the `soundfile` writer to flush all remaining data to the buffer.
  - Returns the final buffer content, ensuring that all necessary headers and data are correctly written.

- **MP3/AAC**:
  - Exports any remaining audio data with proper headers and metadata, including duration and VBR quality for MP3.
  - Writes ID3v1 and ID3v2 tags for MP3 formats.
  - Performs final exports to ensure that all audio data is properly encoded and formatted.

- **PCM**:
  - No finalization is needed as PCM involves raw data without headers.

## Non-Streaming Path

The `StreamingAudioWriter` class is inherently designed for streaming audio data. However, it's essential to understand how it behaves when handling complete files versus streaming data:

### Full File Writing

- **Process**:
  - Accumulate all audio data in memory or buffer.
  - Write the complete file with accurate headers and data sizes upon finalization.

- **Advantages**:
  - Simplifies header management since the total data size is known before writing.
  - Reduces complexity in data handling and processing.

- **Disadvantages**:
  - High memory consumption for large audio files.
  - Delay in availability of audio data until the entire file is processed.

### Stream-to-File Writing

- **Process**:
  - Incrementally write audio data in chunks.
  - Update headers and finalize the file dynamically as data flows.

- **Advantages**:
  - Lower memory usage as data is processed in smaller chunks.
  - Immediate availability of audio data, suitable for real-time streaming applications.

- **Disadvantages**:
  - Complex header management to accommodate dynamic data sizes.
  - Increased likelihood of header synchronization issues, leading to potential file corruption.

**Challenges**:
- Balancing memory usage with processing speed.
- Ensuring consistent and accurate header updates during streaming operations.

## Header Management

### WAV Headers

WAV files utilize `RIFF` headers to describe file structure:

- **Initial Header**:
  - Contains placeholders for file size and data size (`struct.pack('<L', 0)`).

- **Final Header**:
  - Calculates and writes the actual file size (`bytes_written + 36`) and data size (`bytes_written`).
  - Ensures that audio players can correctly interpret the file by having accurate header information.

**Technical Details**:
- The `_write_wav_header` method initializes the WAV header with placeholders.
- Upon finalization, the `write_chunk` method creates a new buffer, writes the correct sizes, and appends the audio data from the original buffer starting at byte 44 (end of the initial header).

**Challenges**:
- Maintaining synchronization between audio data size and header placeholders.
- Ensuring that the header is correctly rewritten upon finalization to prevent file corruption.

### MP3/AAC Headers

MP3 and AAC formats require proper metadata and headers to ensure compatibility:

- **XING Headers (MP3)**:
  - Essential for Variable Bit Rate (VBR) audio files.
  - Control the quality and indexing of the MP3 file.

- **ID3 Tags (MP3)**:
  - Provide metadata such as artist, title, and album information.

- **ADTS Headers (AAC)**:
  - Describe the AAC frame headers necessary for decoding.

**Technical Details**:
- During finalization, the `write_chunk` method for MP3/AAC formats includes:
  - Duration metadata (`-metadata duration`).
  - VBR headers for MP3 (`-write_vbr`, `-vbr_quality`).
  - ID3 tags for MP3 (`-write_id3v1`, `-write_id3v2`).
- Ensures that all remaining audio data is correctly encoded and formatted with the necessary headers.

**Challenges**:
- Ensuring that metadata is accurately written during the finalization process.
- Managing VBR headers to maintain audio quality and file integrity.


# Contributing
First of all, __thank you__ for your interest in contributing to AgentStack! Even the smallest contributions help a _ton_.

Our vision is to build the defacto CLI for quickly spinning up an AI Agent project. We want to be the [create-react-app](https://create-react-app.dev/) of agents. Our inspiration also includes the oh-so-convenient [Angular CLI](https://v17.angular.io/cli).

### Exclusive Contributor Sticker
AgentStack contributors all receive a free sticker pack including an exclusive holographic sticker only available to contributors to the project :)

Once your PR is merge, fill out [this form](https://docs.google.com/forms/d/e/1FAIpQLSfvBEnsT8nsQleonJHoWQtHuhbsgUJ0a9IjOqeZbMGkga2NtA/viewform?usp=sf_link) and I'll send your sticker pack out ASAP! <3

## How to Help

Grab an issue from the [issues tab](https://github.com/AgentOps-AI/AgentStack/issues)! Plenty are labelled "Good First Issue". Fork the repo and create a PR when ready!

The best place to engage in conversation about your contribution is in the Issue chat or on our [Discord](https://discord.gg/JdWkh9tgTQ).

## Setup

1. Clone the repo
   `git clone https://github.com/AgentOps-AI/AgentStack.git`
   `cd AgentStack`
2. Install agentstack as an edtiable project and set it up for development and testing
   `pip install -e .[dev,test]`
   This will install the CLI locally and in editable mode so you can use `agentstack <command>` to test your latest changes

## Adding Tools
If you're reading this section, you probably have a product that AI agents can use as a tool. We're glad you're here!

Adding tools is easy once you understand the project structure. Our documentation for adding tools is available on our hosted docs [here](https://docs.agentstack.sh/contributing/adding-tools).

## Before creating your PR
Be sure that you are opening a PR using a branch other than `main` on your fork. This enables us
to pull your branch and make modifications to the PR with your permission that may be helpful.

### Formatting
AgentStack uses Ruff formatter for consistent code formatting. To format your code, run:
```bash
pip install ruff
ruff format .
```

### Type Checking
AgentStack uses MyPy for type checking. To check types, run:
```bash
mypy agentstack
```

### Pre-Commit Hooks
Ruff and MyPy can be run as pre-commit hooks. To enable these hooks, run:
```bash
pre-commit install
```

## Tests
CLI tests are a bit hacky, so we are not tracking coverage.
That said, _some_ testing is required for any new functionality added by a PR.

Tests MUST pass to have your PR merged. We _will not_ allow main to be in a failing state, so if your tests are failing, this is your problem to fix.

### Run tests locally
Install the testing requirements
```bash
pip install 'agentstack[test]'
```

Then run tests in all supported python versions with
```bash
tox
```

## Need Help?
If you're reading this, we're very thankful you wanted to contribute! I understand it can be a little overwhelming to
get up to speed on a project like this and we are here to help!

### Open a draft PR
While we can't promise to write code for you, if you're stuck or need advice/help, open a draft PR and explain what you were trying to build and where you're stuck! Chances are, one of us have the context needed to help you get unstuck :)

### Chat on our Discord
We have an active [Discord server](https://discord.gg/JdWkh9tgTQ) with contributors and AgentStack users! There is a channel just for contributors on there. Feel free to drop a message explaining what you're trying to build and why you're stuck. Someone from our team should reply soon!

# Thank You!
The team behind AgentStack believe that the barrier to entry for building agents is far too high right now! We believe that this technology can be streamlined and made more accessible. If you're here, you likely feel the same! Any contribution is appreciated.

If you're looking for work, we are _always_ open to hiring passionate engineers of all skill levels! While closing issues cannot guarantee an offer, we've found that engineers who contribute to our open source repo are some of the best we could ever hope to find via recruiters! Be active in the community and let us know you're interested in joining the team!

CONTRIBUTING.md

The fastest way to build robust AI agents


# AgentStack

 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/release/python-3100/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) ![python-testing](https://github.com/agentops-ai/agentstack/actions/workflows/python-testing.yml/badge.svg) ![mypy](https://github.com/agentops-ai/agentstack/actions/workflows/mypy.yml/badge.svg) [![codecov.io](https://codecov.io/github/agentops-ai/agentstack/coverage.svg?branch=master)](https://codecov.io/github/agentops-ai/agentstack>?branch=master)

AgentStack scaffolds your _agent stack_ - The tech stack that collectively is your agent

### Install AgentStack

```sh
curl --proto '=https' --tlsv1.2 -LsSf https://install.agentstack.sh | sh
```

or python [other install methods](https://docs.agentstack.sh/installation)

### Start your agent!

Create AI agent projects from the command line.

- [Quickstart Guide](https://docs.agentstack.sh/quickstart) – How to create a new agent project.
- [Video Tutorial](https://www.loom.com/share/68d796b13cd94647bd1d7fae12b2358e?sid=7fdf595b-de84-4d51-9a81-ef1e9c8ac71c) – Follow along and build a web scrape agent with AgentStack

AgentStack works on macOS, Windows, and Linux.

If something doesn't work, please [file an issue](https://github.com/agentops-ai/agentstack/issues/new).

If you have questions or need help, please ask in our [Discord community](https://discord.gg/JdWkh9tgTQ).

> 🛠🏃🏼♀ The quickest way to build your powerful agent project

AgentStack serves as a great tool for starting your agent project and offers many CLI utilities for easy code-gen throughout the development process.

AgentStack is _not_ a low-code alternative to development. Developers will still need an understanding of how to build with their selected agent framework.

### Currently Supported Providers
- **LLMs**: Most all notable LLMs and providers are supported via LiteLLM or LangChain
- **Framework**: Currently supported frameworks include CrewAI, LangGraph, OpenAI Swarms and LlamaStack
  - Roadmap: Pydantic AI, Eliza, AG2 and Autogen
- **Tools**: Maintaining the largest repository of framework-agnostic tools! All tools listed [here](https://docs.agentstack.sh/tools/community)
- **Observability**: AgentOps baked in by default with first-tier support

### Get Started Immediately

You **don't** need to install or configure tools like LangChain or LlamaIndex.

They are preconfigured and hidden so that you can focus on the code.

Create a project, and you're good to go.

## Creating an Agent Project

**You'll need to have Python 3.10+ on your local development machine**. We recommend using the latest version. You can use [pyenv](https://github.com/pyenv/pyenv) to switch Python versions between different projects.

To create a new agent project, run:

```sh
uv pip install agentstack # or other install method
agentstack init <project_name>
```

It will create a directory with your project name inside the current folder.

Inside that directory, it will generate the initial project structure and install the transitive dependencies.

No configuration or complicated folder structures, only the files you need to build your agent project.

Once the initialization is done, you can open your project folder:

```sh
cd <your_agent_project>
uv pip install
```

then run the default agent!

```sh
agentstack run
```

### Templates
Additionally, pre-built templates are available as a shortcut to building your project. [View the available templates](https://docs.agentstack.sh/templates).

## Building Agent Functionality

After generating a project, the next step is to build your agent project by creating Agents and Tasks. You can do this quickly with AgentStack:

```bash
agentstack generate agent/task <name>
```

Modify the agents and tasks by changing the `agents.yaml` and `tasks.yaml` configuration files in `src/config`

## Tooling

One of AgentStack's core principles is to establish the de facto agent _stack_. A critical component of this stack is the tooling and functionality given to agents beyond simply LLM capabilities.

AgentStack has worked to make access to tools as easy as possible, staying framework agnostic and featuring the best tools.

A list of all tools can be found [on our docs](https://docs.agentstack.sh/tools/core).

Adding tools is as simple as

```bash
agentstack tools add
```

## Running Your Agent

`agentstack run`

Runs the agent project in development mode.

> 👀 Support for easy production deployment of agents is coming soon.

## Philosophy

- **Agents should be easy:** There are so many frameworks out there, but starting from scratch is a pain. Similar to `create-react-app`, AgentStack aims to simplify the "from scratch" process by giving you a simple boilerplate of an agent. It uses popular agent frameworks and LLM providers, but provides a cohesive curated experience on top of them.

- **No Configuration Required:** You don't need to configure anything. A reasonably good configuration of both development and production builds is handled for you so you can focus on writing code.

- **No Lock-In:** You can customize your setup at any time. AgentStack is designed to make it easy to get the components you need running right off the bat; it's up to you what to do next.

- **Provider Agnosticism:** AgentStack is designed to be provider agnostic in all ways. This means especially that the framework layer of your agent stack should be interoperable with every other layer. Frameworks must still be supported by AgentStack. See supported frameworks above.

AgentStack is not designed to be a low-code solution to building agents. Instead it is a great head-start for starting an agent project from scratch.

## Roadmap

### Tools
- More [core tools](https://docs.agentstack.sh/tools/core) built by AgentStack
- Preferred partners in the package directly
- Community partner tools added through external repositories

### New Stack Layers
- Prompting layer (DSPy)
- Eval Layer
- UI layer

### Other Features
- Generated testing
- Integrated benchmarking
- Easy integration of tools for browsing, RAG, and more.
- A fast interactive test runner with built-in support for coverage reporting.
- A live development server that warns about common mistakes (in progress).
- A build script to bundle your project for production (in progress).

## License

AgentStack is open source software [licensed as MIT](LICENSE).

## How to Contribute

AgentStack is a new project built by passionate AI agent developers! We'd love help making this tool better. Easy first issues are available, create new issues with feature ideas, or chat with us on our [Discord](https://discord.gg/JdWkh9tgTQ). Make sure you read our contributor documentation to familiarize yourself with the project at [How to Contribute](https://docs.agentstack.sh/contributing/how-to-contribute).

If you are an Agent Tool developer, feel free to create an issue or even a PR to add your tool to AgentStack.

README.md


## Wizard

## LangGraph

[ ] Bug: empty `bind_tools` list on a new Agent throws an error

[ ] Reliably handle adding two Tasks and two Agent via CLI

[ ] Create a new template demonstrating graph usage

"Top of Funnel"

[√] Hello World!

[√] Catch common exception types from the user's first `agentstack run` and provide a helpful error message.
    - In order to avoid importing all the sub-libraries, use string matching to determine what the exception is.

[√] Allow the user to select from a list of tools if a <tool_name> is not provided to `agenstack add tools`

[ ] Handle all setup tasks that `agentstack init` needs.
    - Wrap the output in a `curses` window to show progress.
    - Prevent the user from having to scroll back up to find the help text from the `init` command.
    - Use `uv` for all package management.

[√] Modify agentops init to indicate which tools are being used.
    - Possibly with an `agentstack.get_tags()` method that automatically sets relevant tags.

[√] If there is only one agent in the project, treat it as a default.
    - New tasks should be assigned to it.

[√] Wrap tools in the framework's protocol before including them in the project.
    - Access tools with `agentstack.tools['tool_name']` which dynamically generates the wrapped tool.
    - This will be a breaking change with the 0.3 release.

TODO.md


## 📥 Pull Request

**📘 Description**
_Briefly describe the changes you've made._

**🧪 Testing**
_Describe the tests you performed to validate your changes._

.github/PULL_REQUEST_TEMPLATE.md


# Docs

## Building
To build and view docs from this folder, install the Mintlify CLI:
```bash
pip install mintlify
```

then serve it with

```bash
mintlify dev
```

docs/README.md


MIT License

Copyright (c) 2024 me

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


# howards_agent
desc

~~ Built with AgentStack ~~

## How to build your Crew
### With the CLI
Add an agent using AgentStack with the CLI:
`agentstack generate agent <agent_name>`
You can also shorten this to `agentstack g a <agent_name>`
For wizard support use `agentstack g a <agent_name> --wizard`
Finally for creation in the CLI alone, use `agentstack g a <agent_name> --role/-r <role> --goal/-g <goal> --backstory/-b <backstory> --model/-m <provider/model>`

This will automatically create a new agent in the `agents.yaml` config as well as in your code. Either placeholder strings will be used, or data included in the wizard.

Similarly, tasks can be created with `agentstack g t <tool_name>`

Add tools with `agentstack tools add <tool_name>` and view tools available with `agentstack tools list`

## How to use your Crew
In this directory, run `poetry install`

To run your project, use the following command:
`crewai run` or `python src/main.py`

This will initialize your crew of AI agents and begin task execution as defined in your configuration in the main.py file.

#### Replay Tasks from Latest Crew Kickoff:

CrewAI now includes a replay feature that allows you to list the tasks from the last run and replay from a specific one. To use this feature, run:
`crewai replay <task_id>`
Replace <task_id> with the ID of the task you want to replay.

#### Reset Crew Memory
If you need to reset the memory of your crew before running it again, you can do so by calling the reset memory feature:
`crewai reset-memory`
This will clear the crew's memory, allowing for a fresh start.


# job_posting
_An example project built with AgentStack_

## Commands used to create this project

```bash
agentstack init job_posting
agentstack g a research_agent
agentstack g a writer_agent
agentstack g a review_agent
agentstack g t research_company_culture_task
agentstack g t research_role_requirements_task
agentstack g t draft_job_posting_task
agentstack g t review_and_edit_job_posting_task
agentstack g t industry_analysis_task
agentstack tools add firecrawl
```

## Other work
- Prompt engineering was done in `agents.yaml` and `tasks.yaml`
- Inputs were modified in `crew.py`
- Firecrawl API key added to `.env`

## Run this agent
```bash
agentstack run
```


MIT License

Copyright (c) 2025 Name <Email>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


# research_assistant

## How to build your Crew Agent
### With the CLI
Add an agent using AgentStack with the CLI:
`agentstack generate agent <agent_name>`
You can also shorten this to `agentstack g a <agent_name>`
For wizard support use `agentstack g a <agent_name> --wizard`
Finally for creation in the CLI alone, use `agentstack g a <agent_name> --role/-r <role> --goal/-g <goal> --backstory/-b <backstory> --model/-m <provider/model>`

This will automatically create a new agent in the `agents.yaml` config as well as in your code. Either placeholder strings will be used, or data included in the wizard.

Similarly, tasks can be created with `agentstack g t <tool_name>`

Add tools with `agentstack tools add` and view tools available with `agentstack tools list`

## How to use your Agent
In this directory, run `uv pip install --requirements pyproject.toml`

To run your project, use the following command:
`agentstack run`

This will initialize your crew of AI agents and begin task execution as defined in your configuration in the main.py file.

#### Replay Tasks from Latest Crew Kickoff:

CrewAI now includes a replay feature that allows you to list the tasks from the last run and replay from a specific one. To use this feature, run:
`crewai replay <task_id>`
Replace <task_id> with the ID of the task you want to replay.

#### Reset Crew Memory
If you need to reset the memory of your crew before running it again, you can do so by calling the reset memory feature:
`crewai reset-memory`
This will clear the crew's memory, allowing for a fresh start.

> 🪩 Project built with [AgentStack](https://github.com/AgentOps-AI/AgentStack)


# sentiment_analyser
This is the start of your AgentStack project.

## How to build your Crew
### With the CLI
Add an agent using AgentStack with the CLI:
`agentstack generate agent <agent_name>`
You can also shorten this to `agentstack g a <agent_name>`
For wizard support use `agentstack g a <agent_name> --wizard`
Finally for creation in the CLI alone, use `agentstack g a <agent_name> --role/-r <role> --goal/-g <goal> --backstory/-b <backstory> --model/-m <provider/model>`

This will automatically create a new agent in the `agents.yaml` config as well as in your code. Either placeholder strings will be used, or data included in the wizard.

Similarly, tasks can be created with `agentstack g t <tool_name>`

Add tools with `agentstack tools add` and view tools available with `agentstack tools list`

## How to use your Crew
In this directory, run `poetry install`

To run your project, use the following command:
`agentstack run`

This will initialize your crew of AI agents and begin task execution as defined in your configuration in the main.py file.

#### Replay Tasks from Latest Crew Kickoff:

CrewAI now includes a replay feature that allows you to list the tasks from the last run and replay from a specific one. To use this feature, run:
`crewai replay <task_id>`
Replace <task_id> with the ID of the task you want to replay.

#### Reset Crew Memory
If you need to reset the memory of your crew before running it again, you can do so by calling the reset memory feature:
`crewai reset-memory`
This will clear the crew's memory, allowing for a fresh start.

> 🪩 Project built with [AgentStack](https://github.com/AgentOps-AI/AgentStack)


# stock_analysis
asdf

~~ Built with AgentStack ~~

## How to build your Crew
### With the CLI
Add an agent using AgentStack with the CLI:
`agentstack generate agent <agent_name>`
You can also shorten this to `agentstack g a <agent_name>`
For wizard support use `agentstack g a <agent_name> --wizard`
Finally for creation in the CLI alone, use `agentstack g a <agent_name> --role/-r <role> --goal/-g <goal> --backstory/-b <backstory> --model/-m <provider/model>`

This will automatically create a new agent in the `agents.yaml` config as well as in your code. Either placeholder strings will be used, or data included in the wizard.

Similarly, tasks can be created with `agentstack g t <tool_name>`

Add tools with `agentstack tools add <tool_name>` and view tools available with `agentstack tools list`

## How to use your Crew
In this directory, run `poetry install`

To run your project, use the following command:
`crewai run` or `python src/main.py`

This will initialize your crew of AI agents and begin task execution as defined in your configuration in the main.py file.

#### Replay Tasks from Latest Crew Kickoff:

CrewAI now includes a replay feature that allows you to list the tasks from the last run and replay from a specific one. To use this feature, run:
`crewai replay <task_id>`
Replace <task_id> with the ID of the task you want to replay.

#### Reset Crew Memory
If you need to reset the memory of your crew before running it again, you can do so by calling the reset memory feature:
`crewai reset-memory`
This will clear the crew's memory, allowing for a fresh start.


MIT License

Copyright (c) 2024 Braelyn Boynton

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


# trip_planner 🍄

> Example credit to CrewAI

A team of agents that expertly design a trip

~~ Built with AgentStack ~~

## How to build your Crew
### With the CLI
Add an agent using AgentStack with the CLI:
`agentstack generate agent <agent_name>`
You can also shorten this to `agentstack g a <agent_name>`
For wizard support use `agentstack g a <agent_name> --wizard`
Finally for creation in the CLI alone, use `agentstack g a <agent_name> --role/-r <role> --goal/-g <goal> --backstory/-b <backstory> --model/-m <provider/model>`

This will automatically create a new agent in the `agents.yaml` config as well as in your code. Either placeholder strings will be used, or data included in the wizard.

Similarly, tasks can be created with `agentstack g t <tool_name>`

Add tools with `agentstack tools add <tool_name>` and view tools available with `agentstack tools list`

## How to use your Crew
In this directory, run `poetry install`

To run your project, use the following command:
`crewai run`

This will initialize your crew of AI agents and begin task execution as defined in your configuration in the main.py file.

#### Replay Tasks from Latest Crew Kickoff:

CrewAI now includes a replay feature that allows you to list the tasks from the last run and replay from a specific one. To use this feature, run:
`crewai replay <task_id>`
Replace <task_id> with the ID of the task you want to replay.

#### Reset Crew Memory
If you need to reset the memory of your crew before running it again, you can do so by calling the reset memory feature:
`crewai reset-memory`
This will clear the crew's memory, allowing for a fresh start.


Please see the detailed 7-day itinerary, packing suggestions, and budget breakdown above. Be aware that rates can change and availability might vary; make sure to book your accommodations and activities in advance!

Enjoy your trip and immerse yourself in the rich history, culture, art, and music of Berlin!


# web_researcher
research a web page and create a short description

~~ Built with AgentStack ~~

## How to build your Crew
### With the CLI
Add an agent using AgentStack with the CLI:
`agentstack generate agent <agent_name>`
You can also shorten this to `agentstack g a <agent_name>`
For wizard support use `agentstack g a <agent_name> --wizard`
Finally for creation in the CLI alone, use `agentstack g a <agent_name> --role/-r <role> --goal/-g <goal> --backstory/-b <backstory> --model/-m <provider/model>`

This will automatically create a new agent in the `agents.yaml` config as well as in your code. Either placeholder strings will be used, or data included in the wizard.

Similarly, tasks can be created with `agentstack g t <tool_name>`

Add tools with `agentstack tools add <tool_name>` and view tools available with `agentstack tools list`

## How to use your Crew
In this directory, run `poetry install`

To run your project, use the following command:
`crewai run` or `python src/main.py`

This will initialize your crew of AI agents and begin task execution as defined in your configuration in the main.py file.

#### Replay Tasks from Latest Crew Kickoff:

CrewAI now includes a replay feature that allows you to list the tasks from the last run and replay from a specific one. To use this feature, run:
`crewai replay <task_id>`
Replace <task_id> with the ID of the task you want to replay.

#### Reset Crew Memory
If you need to reset the memory of your crew before running it again, you can do so by calling the reset memory feature:
`crewai reset-memory`
This will clear the crew's memory, allowing for a fresh start.