Metadata-Version: 2.4
Name: katalyst
Version: 0.9.1
Summary: A terminal coding agent for Python.
Author-email: Maruti Agarwal <marutiagarwal@gmail.com>
License-Expression: MIT
Requires-Python: <4.0,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai==1.97.0
Requires-Dist: langgraph==0.5.3
Requires-Dist: langchain-core==0.3.69
Requires-Dist: python-dotenv==1.1.1
Requires-Dist: langchain-openai==0.3.28
Requires-Dist: pathspec==0.12.1
Requires-Dist: tree-sitter==0.21.3
Requires-Dist: tree-sitter-languages==1.10.2
Requires-Dist: rich==14.0.0
Requires-Dist: instructor==1.10.0
Requires-Dist: bm25s==0.2.13
Requires-Dist: thefuzz==0.22.1
Requires-Dist: langchain-ollama==0.3.5
Requires-Dist: langchain-anthropic==0.3.17
Requires-Dist: simple-term-menu==1.6.6
Requires-Dist: langgraph-checkpoint-sqlite==2.0.10
Requires-Dist: langmem==0.0.28
Requires-Dist: langgraph-supervisor<0.0.29,>=0.0.28
Requires-Dist: jupyter-client>=8.6.0
Requires-Dist: ipykernel>=6.29.0
Provides-Extra: test
Requires-Dist: pytest==8.4.0; extra == "test"
Requires-Dist: pytest-cov==6.2.1; extra == "test"
Requires-Dist: pytest-asyncio==1.0.0; extra == "test"
Dynamic: license-file

# Katalyst Agent

A modular, node-based terminal coding agent for Python, designed for robust, extensible, and production-ready workflows.

![Katalyst Demo: Installation and Usage](docs/images/katalyst_demo.gif)
*Figure: Demo showing how to install and use Katalyst from the terminal*

![Katalyst Coding Agent Architecture](docs/images/katalyst-coding-agent-dag.png)
*Figure: Architecture diagram of the Katalyst Coding Agent (DAG/graph structure)*

## Quick Setup

To install Katalyst from PyPI, simply run:

```bash
pip install katalyst
```

**1. Copy the example environment file:**

```bash
cp .env.example .env
```

**2.** You must set your OpenAI API key as the environment variable `OPENAI_API_KEY` or add it to a `.env` file in your project directory.

## Searching Files (ripgrep required)

The `search_files` tool requires [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) to be installed on your system:
- **macOS:**   `brew install ripgrep`
- **Ubuntu:**  `sudo apt-get install ripgrep`
- **Windows:** `choco install ripgrep`

## Features

- Automatic conversation persistence: Katalyst saves your conversation history to a SQLite database in `.katalyst/checkpoints.db`, allowing you to resume conversations across sessions. Use `/new` to start fresh. 

- Modular Node-Based Architecture: Built on a robust DAG (Directed Acyclic Graph) structure that enables flexible and extensible workflows. The system uses a two-level agent structure with an outer planning loop and inner ReAct (Reason-Act) cycles.

- Intelligent Task Planning: Automatically breaks down complex tasks into manageable sub-tasks and executes them sequentially with built-in error recovery and replanning capabilities.

- Human-in-the-Loop Verification: Interactive plan approval system that allows users to:
  - Review generated plans before execution
  - Provide feedback for better plans
  - Automatically approve plans with `--auto-approve` flag
  - Iterate on plans until they meet requirements

- Rich Tool Integration: Comprehensive set of built-in tools for:
  - File operations (reading, writing, searching)
  - Code analysis and syntax checking
  - Terminal command execution
  - And more, with easy extensibility for custom tools

- Robust Error Handling: Sophisticated error recovery system that can:
  - Classify and format errors for better LLM understanding
  - Automatically trigger replanning when needed
  - Maintain detailed error traces for debugging

- Multi-Language Support: Built-in support for multiple programming languages including:
  - Python
  - JavaScript/TypeScript
  - JSX/TSX
  - (More languages will be added soon...)

- Interactive CLI: User-friendly command-line interface with:
  - Helpful welcome screens and onboarding
  - Real-time feedback and progress updates
  - Detailed logging for debugging

- Configurable LLM Integration: Flexible LLM provider support with:
  - Default OpenAI integration
  - Configurable model selection
  - Easy extension for other LLM providers

## Testing

Katalyst includes both unit and functional tests. For detailed information about running tests, writing new tests, and test coverage, see [TESTS.md](TESTS.md).


## TODO

See [TODO.md](./TODO.md) for the latest development tasks and roadmap.

