Metadata-Version: 2.4
Name: birdie-agent
Version: 0.2.14
Summary: Dynamic skill-based LangGraph agent
Author-email: Gernot Kvas <gernot@kvas.at>
License: Apache-2.0
Keywords: llm,agent,langgraph,langchain,mcp,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: langchain-core>=0.2
Requires-Dist: langchain-openai>=0.1
Requires-Dist: langgraph>=0.1
Requires-Dist: langgraph-checkpoint-sqlite>=2.0
Requires-Dist: aiosqlite
Requires-Dist: pydantic>=2.0
Requires-Dist: requests
Requires-Dist: pyyaml
Requires-Dist: rich>=13.0
Requires-Dist: prompt_toolkit>=3.0
Requires-Dist: mistralai>=1.0
Requires-Dist: anthropic>=0.25
Requires-Dist: mcp>=1.0
Requires-Dist: langchain-mcp-adapters>=0.1
Requires-Dist: ddgs>=0.1
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Provides-Extra: gemini
Dynamic: license-file

# Birdie

```
      ___                       ___           ___                       ___     
    /\  \          ___        /\  \         /\  \          ___        /\  \    
   /::\  \        /\  \      /::\  \       /::\  \        /\  \      /::\  \   
  /:/\:\  \       \:\  \    /:/\:\  \     /:/\:\  \       \:\  \    /:/\:\  \  
 /::\~\:\__\      /::\__\  /::\~\:\  \   /:/  \:\__\      /::\__\  /::\~\:\  \ 
/:/\:\ \:|__|  __/:/\/__/ /:/\:\ \:\__\ /:/__/ \:|__|  __/:/\/__/ /:/\:\ \:\__\
\:\~\:\/:/  / /\/:/  /    \/_|::\/:/  / \:\  \ /:/  / /\/:/  /    \:\~\:\ \/__/
 \:\ \::/  /  \::/__/        |:|::/  /   \:\  /:/  /  \::/__/      \:\ \:\__\  
  \:\/:/  /    \:\__\        |:|\/__/     \:\/:/  /    \:\__\       \:\ \/__/  
   \::/__/      \/__/        |:|  |        \::/__/      \/__/        \:\__\    
    ~~                        \|__|         ~~                        \/__/    
```

A LangGraph-based agent that discovers capabilities at runtime from **SKILL.MD** and **AGENT.MD** files. Skills, tools, and sub-agents are all declared in plain Markdown - no code changes required to add new capabilities.

Birdie is a minimal yet fully functional implementation. The design goal is simplicity and transparency: the codebase is intended to be readable, hackable, and easy to extend. Every major feature - the agent loop, skill loading, session persistence, conversation compaction, long-term memory - is implemented in a small number of well-commented Python files that you can read from top to bottom in an afternoon.

> **Security notice:** Birdie has no guardrails against local tool misuse. Skills such as `Shell` and `Filesystem` can read, write, and execute anything the running user is permitted to do. Only enable skills you trust and run Birdie under an account with appropriate restrictions.

---

<img src="doc/assets/demo.gif" alt="Birdie CLI demo" width="800">

---

## Installation

**From PyPI (recommended)**

```bash
pip install birdie-agent
```

**From source**

```bash
git clone https://github.com/gkvas/birdie.git
cd birdie
pip install -e .
```

**Optional extras**

```bash
pip install "birdie-agent[mcp]"   # MCP server support
pip install -e ".[dev,mcp]"       # development + MCP (from source)
```

---

## Quick start

Configure your LLM provider and run `birdie`.

**Environment variables**

```bash
# Anthropic
export LLM_VENDOR=anthropic
export LLM_MODEL=claude-sonnet-4-6
export ANTHROPIC_API_KEY=your-key-here
birdie

# OpenAI
export LLM_VENDOR=openai
export LLM_MODEL=gpt-4o
export OPENAI_API_KEY=your-key-here
birdie

# Mistral
export LLM_VENDOR=mistral
export LLM_MODEL=mistral-large-latest
export MISTRAL_API_KEY=your-key-here
birdie

#Azure OpenAI
export  LLM_VENDOR=azure
export LLM_MODEL=your-deployment-name
export AZURE_OPENAI_API_KEY=your-key-here
export AZURE_OPENAI_ENDPOINT=your-base-url
birdie
```

**JSON config file**

```bash
birdie --config ~/.birdie/provider.json
```

```json
{
  "vendor": "anthropic",
  "model": "claude-sonnet-4-6",
  "api_key": "sk-ant-..."
}
```

See [doc/cli.md](doc/cli.md) for all supported vendors, config fields, and environment variable options.

---

## Built-in skills

Skills extend Birdie and are defined in **SKILL.MD** files. All skills are **disabled by default**. Enable them for the current session:

```
/skill enable Shell
/skill enable DuckDuckGo
```

Birdie ships with the following default skills:

| Skill | Description |
|---|---|
| `Shell` | Run arbitrary shell commands |
| `Filesystem` | Read and write local files |
| `ssh` | Connect to remote hosts and run commands |
| `ToDo` | Step-by-step planning and progress tracking |
| `Weather` | Weather lookup via external API |
| `DuckDuckGo` | Web search - no API key required |
| `mcp_demo` | Demo MCP server (echo and reverse_string) |

See [doc/skills.md](doc/skills.md) for the full SKILL.MD format and how to write skills.

---

## Sub-agents

Sub-agents are AI agents defined by **AGENT.MD** files. When enabled, a sub-agent appears to the calling LLM as a regular tool. Invoking it spins up an ephemeral agent, runs it to completion, and returns the result.

All agents are **disabled by default**. Enable them for the current session:

```
/agent enable Summarizer
```

Drop an `AGENT.MD` in `~/.birdie/agents/<name>/` to add custom sub-agents without reinstalling.

See [doc/agents.md](doc/agents.md) for the full AGENT.MD format and how to write custom agents.

---

## Conversation memory

Birdie maintains three separate memory stores that work together to give the agent context across turns and sessions.

**Short-term memory** is handled automatically by LangGraph's SQLite checkpointer. Every message is stored in `~/.birdie/sessions/<user>/checkpoints.db` and loaded at the start of each turn. The agent trims the loaded history to a 20-message context window before calling the LLM, so cost stays bounded even in very long sessions.

**Manual long-term memory** is written by you, explicitly. Use `/remember` to save any fact you want the agent to recall in future sessions:

```
/remember I prefer compact, direct answers without preamble
/remember The project uses Python 3.12 and pytest for tests
```

Notes are stored in `~/.birdie/sessions/<user>/memory.json` and injected into the system prompt at the start of every turn, across all sessions.

**Automatic long-term memory** is written by the compaction pipeline. When a session grows beyond 100 messages, Birdie automatically summarises the oldest segment using the LLM, extracts structured facts, preferences, tool outcomes, and open tasks, and stores them in `~/.birdie/ltm/<user>.json`. On future turns, the top-5 most semantically relevant entries are retrieved and injected alongside your manual `/remember` notes.

You can trigger compaction at any time with:

```
/compact
```

This is useful at the end of a long working session to capture everything important before starting fresh. The command displays the summary that was generated and how many messages were removed from the checkpoint.

The retrieval uses a lightweight hash-trick embedding (`birdie/core/retrieval.py`) that requires no model downloads or extra dependencies - just SHA-256 and a dot product.

See [doc/architecture.md](doc/architecture.md) for a detailed explanation of how all three stores interact, how the compaction algorithm picks the split point, and how the LTM store is queried each turn.

---

## Key commands

| Command | Description |
|---|---|
| `/skill list` | List all skills and their status |
| `/skill enable <name>` | Enable a skill for this session |
| `/agent list` | List all sub-agents and their status |
| `/agent enable <name>` | Enable a sub-agent for this session |
| `/agent output short\|full\|off` | Control sub-agent transcript verbosity |
| `/tool output short\|full\|off` | Control tool result verbosity |
| `/remember <text>` | Save a note to long-term memory |
| `/compact` | Summarise old messages into long-term memory now |
| `/session new` | Start a new session |
| `/session list` | List all sessions |
| `/help` | Show all commands |

---

## Documentation

| Document | Contents |
|---|---|
| [doc/cli.md](doc/cli.md) | CLI flags, provider config reference, all slash commands, key bindings |
| [doc/skills.md](doc/skills.md) | SKILL.MD format, entrypoints, tool and knowledge skills, skill loading |
| [doc/agents.md](doc/agents.md) | AGENT.MD format, sub-agent system, runtime controls, custom agents |
| [doc/mcp.md](doc/mcp.md) | MCP integration, declaring MCP servers, writing MCP servers |
| [doc/architecture.md](doc/architecture.md) | Project layout, agent loop, system prompt, providers, conversation compaction, long-term memory store, sessions |

---

## Running tests

```bash
pip install -e ".[dev,mcp]"
pytest
```
