Metadata-Version: 2.4
Name: kader
Version: 2.6.6
Summary: kader coding agent
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: aiofiles>=25.1.0
Requires-Dist: anthropic>=0.83.0
Requires-Dist: faiss-cpu>=1.9.0
Requires-Dist: google-api-core>=2.24.0
Requires-Dist: google-genai>=1.61.0
Requires-Dist: jinja2>=3.1.6
Requires-Dist: loguru>=0.7.3
Requires-Dist: mistralai>=1.12.0
Requires-Dist: ollama>=0.6.1
Requires-Dist: openai>=2.20.0
Requires-Dist: outdated>=0.2.2
Requires-Dist: prompt-toolkit>=3.0.50
Requires-Dist: python-frontmatter>=1.1.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=14.0.0
Requires-Dist: tenacity>=9.1.2
Requires-Dist: typing-extensions>=4.15.0
Requires-Dist: wcmatch>=10.1
Description-Content-Type: text/markdown

# Kader

Kader is an intelligent coding agent designed to assist with software development tasks. It provides a comprehensive framework for building AI-powered agents with advanced reasoning capabilities and tool integration.

## Features

- 🤖 **AI-powered Code Assistance** - Support for multiple LLM providers:
  - **Ollama**: Local LLM execution for privacy and speed.
  - **Google Gemini**: Cloud-based powerful models via the Google GenAI SDK.
  - **Anthropic**: High-quality Claude models via the Anthropic SDK.
- 🖥️ **Interactive CLI** - Modern terminal interface built with Rich & prompt_toolkit:
  - **Beautiful Output**: Markdown rendering, styled panels, and dynamic tables.
  - **Interactive Tools**: Built-in interactive prompts for model selection and tool confirmation.
- 🛠️ **Tool Integration** - File system, command execution, web search, and more.
- 🧠 **Memory Management** - State persistence, conversation history, and isolated sub-agent memory.
- 🔁 **Session Management** - Save and load conversation sessions.
- ⌨️ **Keyboard Shortcuts** - Efficient navigation and operations.
- 📝 **YAML Configuration** - Agent configuration via YAML files.
- 🔄 **Planner-Executor Framework** - Sophisticated reasoning and acting architecture using task planning and delegation.
- 🗂️ **File System Tools** - Read, write, search, and edit files with automatic `.gitignore` filtering.
- 🤝 **Agent-As-Tool** - Spawn sub-agents for specific tasks with isolated memory and automated context aggregation.
- 🎯 **Agent Skills** - Modular skill system for specialized domain knowledge and task-specific instructions.

## Installation

### Prerequisites

- Python 3.11 or higher
- [Ollama](https://ollama.ai/) (optional, for local LLMs)
- [uv](https://docs.astral.sh/uv/) package manager (recommended) or [pip](https://pypi.org/project/pip/)

### Using uv (recommended)

```bash
# Clone the repository
git clone https://github.com/your-repo/kader.git
cd kader

# Install dependencies with uv
uv sync

# Run the CLI
uv run python -m cli
```

### Using uv tool

With uv tool, you can install Kader globally and run it directly with the `kader` command:

```bash
# Install Kader globally using uv tool
uv tool install kader

# Run the CLI
kader
```

### Using pip

```bash
# Clone the repository
git clone https://github.com/your-repo/kader.git
cd kader

# Install in development mode
pip install -e .

# Run the CLI
python -m cli
```

## Quick Start

### Running the CLI

```bash
# Run the Kader CLI using uv
uv run python -m cli

# Or using pip
python -m cli
```

### First Steps in CLI

Once the CLI is running:

1. Type any question to start chatting with the agent.
2. Use `/help` to see available commands.
3. Use `/models` to check and interactively switch available models.
4. Run terminal commands directly by prefixing with `!` (e.g. `!ls -la`).

## Configuration

When the kader module is imported for the first time, it automatically creates a `.kader` directory in your home directory and a `.env` file.

### Environment Variables

The application automatically loads environment variables from `~/.kader/.env`:
- `OLLAMA_API_KEY`: API key for Ollama service (if applicable).
- `GOOGLE_API_KEY`: API key for Google Gemini (required for Google Provider).
- `ANTHROPIC_API_KEY`: API key for Anthropic Claude (required for Anthropic Provider).
- Additional variables can be added to the `.env` file and will be automatically loaded.

### Memory and Sessions

Kader stores data in `~/.kader/`:
- Sessions: `~/.kader/memory/sessions/`
- Configuration: `~/.kader/`
- Memory files: `~/.kader/memory/`
- Checkpoints: `~/.kader/memory/sessions/<session-id>/executors/` (Aggregated context from sub-agents)

## CLI Commands

| Command | Description |
|---------|-------------|
| `/help` | Show command reference |
| `/models` | Show available models (Ollama, Google & Anthropic) |
| `/clear` | Clear conversation |
| `/save` | Save current session |
| `/load <id>` | Load a saved session |
| `/sessions` | List saved sessions |
| `/skills` | List loaded skills |
| `/cost` | Show usage costs |
| `/init` | Initialize .kader directory with KADER.md |
| `/exit` | Exit the CLI |
| `!cmd` | Run terminal command |

### Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Ctrl+C` | Cancel current operation |
| `Ctrl+D` | Exit the CLI |

## Project Structure

```
kader/
├── cli/                    # Interactive command-line interface
│   ├── app.py             # Main application entry point (Rich + prompt_toolkit)
│   ├── utils.py           # Constants and helpers
│   ├── llm_factory.py     # Provider selection logic
│   ├── __init__.py        # Package exports
│   └── commands/          # CLI command handlers
│       ├── base.py        # Base command class
│       └── initialize.py  # /init command
│   └── README.md          # CLI documentation
├── examples/              # Example implementations
│   ├── memory_example.py  # Memory management examples
│   ├── google_example.py  # Google Gemini provider examples
│   ├── anthropic_example.py # Anthropic Claude provider examples
│   ├── planner_executor_example.py # Advanced workflow examples
│   ├── skills/           # Agent skills examples
│   │   ├── hello/        # Greeting skill with instructions
│   │   ├── calculator/   # Math calculation skill
│   │   └── react_agent.py # Skills demo with ReAct agent
│   └── README.md         # Examples documentation
├── kader/                # Core framework
│   ├── agent/            # Agent implementations (Planning, ReAct)
│   ├── memory/           # Memory management & persistence
│   ├── providers/        # LLM providers (Ollama, Google, Anthropic)
│   ├── tools/            # Tools (File System, Web, Command, AgentTool)
│   ├── prompts/          # Prompt templates (Jinja2)
│   └── utils/            # Utilities (Checkpointer, ContextAggregator)
├── pyproject.toml        # Project dependencies
├── README.md             # This file
└── uv.lock               # Dependency lock file
```

## Core Components

### Agents

Kader provides a robust agent architecture:

- **ReActAgent**: Reasoning and Acting agent that combines thoughts with actions.
- **PlanningAgent**: High-level agent that breaks complex tasks into manageable plans.
- **BaseAgent**: Abstract base class for creating custom agent behaviors.

### LLM Providers

Kader supports multiple backends:
- **OllamaProvider**: Connects to locally running Ollama instances.
- **GoogleProvider**: High-performance access to Gemini models.
- **AnthropicProvider**: Full support for Claude models.

### Agent-As-Tool (AgentTool)

The `AgentTool` allows a `PlanningAgent` (Architect) to delegate work to a `ReActAgent` (Worker). It features:
- **Persistent Memory**: Sub-agent conversations are saved to JSON.
- **Context Aggregation**: Sub-agent research and actions are automatically merged into the main session's `checkpoint.md` via `ContextAggregator`.

### Agent Skills

Kader supports a modular skill system for domain-specific knowledge and specialized instructions:

- **Skill Structure**: Skills are defined as directories containing `SKILL.md` files with YAML frontmatter
- **Skill Loading**: Skills are loaded from `~/.kader/skills` (high priority) and `./.kader/` directories
- **Skill Injection**: Available skills are automatically injected into the system prompt
- **Skills Tool**: Agents can load skills dynamically using the `skills_tool`

### File System Tools with Gitignore Filtering

The file system tools (`read_directory`, `grep`, `glob`) automatically filter out files and directories that match patterns defined in `.gitignore` files.

You can disable this filtering by passing `apply_gitignore_filter=False` when creating tools:

```python
from pathlib import Path
from kader.tools.filesys import get_filesystem_tools

# With filtering (default)
tools = get_filesystem_tools(base_path=Path.cwd())

# Without filtering
tools = get_filesystem_tools(base_path=Path.cwd(), apply_gitignore_filter=False)
```

Example skill structure:
```
~/.kader/skills/hello/
├── SKILL.md
└── scripts/
    └── hello.py
```

Example skill (`SKILL.md`):
```yaml
---
name: hello
description: Skill for ALL greeting requests
---

# Hello Skill

This skill provides the greeting format you must follow.

## How to greet

Always greet the user with:
- A warm welcome
- Their name if mentioned
- A friendly emoji
```

### Memory Management

- **SlidingWindowConversationManager**: Maintains context within token limits.
- **PersistentSlidingWindowConversationManager**: Auto-saves sub-agent history.
- **Checkpointer**: Generates markdown summaries of agent actions.

## Development

### Setting up for Development

```bash
# Clone the repository
git clone https://github.com/your-repo/kader.git
cd kader

# Install in development mode with uv
uv sync

# Run the CLI
uv run python -m cli
```

### Running Tests

```bash
# Run tests with uv
uv run pytest

# Run tests with specific options
uv run pytest --verbose
```

### Code Quality

Kader uses various tools for maintaining code quality:

```bash
# Run linter
uv run ruff check .

# Format code
uv run ruff format .
```

## Troubleshooting

### Common Issues

- **No models found**: Ensure your providers are correctly configured. For Ollama, run `ollama serve`. For Google, ensure `GOOGLE_API_KEY` is set. For Anthropic, ensure `ANTHROPIC_API_KEY` is set.
- **Connection errors**: Verify internet access for cloud providers and local service availability for Ollama.

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on:

- Setting up your development environment
- Code style guidelines
- Running tests
- Submitting pull requests

### Quick Start for Contributors

```bash
# Fork and clone
git clone https://github.com/your-username/kader.git
cd kader

# Install dependencies
uv sync

# Run tests
uv run pytest

# Run linter
uv run ruff check .
```

### Coding with AI

This project includes a specialized skill for AI coding agents. When working with AI assistants on this codebase, they should use the `contributing-to-kader` skill located in [`.kader/skills/contributing-to-kader`](.kader/skills/contributing-to-kader). This skill provides AI agents with essential guidelines including:

- Core development rules (linting, formatting, testing)
- Key commands for development workflow
- Project structure overview
- Best practices for contributing

AI assistants can load this skill using the skills_tool to get specialized instructions for working with this project.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Acknowledgments

- Built with [Rich](https://github.com/Textualize/rich) and [prompt_toolkit](https://python-prompt-toolkit.readthedocs.io/) for the beautiful CLI interface.
- Uses [Ollama](https://ollama.ai/) for local LLM execution.
- Powered by [Google Gemini](https://ai.google.dev/) for advanced cloud-based reasoning.
- Enhanced by [Anthropic Claude](https://www.anthropic.com/) for high-quality coding assistance.
