Metadata-Version: 2.4
Name: panda-ronin
Version: 0.2.8
Summary: A self-directed AI lifeform wandering the digital world
Author-email: Panda Ronin <panda-ronin@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/yourusername/panda-ronin
Project-URL: Repository, https://github.com/yourusername/panda-ronin
Project-URL: Issues, https://github.com/yourusername/panda-ronin/issues
Keywords: ai,agent,autonomous,lifecycle,panda
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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
Requires-Dist: litellm>=1.40.0
Requires-Dist: rich>=13.0.0
Requires-Dist: colorama>=0.4.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31.0
Provides-Extra: web
Requires-Dist: markdownify>=0.11.0; extra == "web"
Requires-Dist: duckduckgo-search>=6.0.0; extra == "web"
Provides-Extra: telegram
Requires-Dist: python-telegram-bot>=21.0; extra == "telegram"
Provides-Extra: feishu
Requires-Dist: lark-oapi>=1.3.0; extra == "feishu"
Provides-Extra: dingtalk
Requires-Dist: dingtalk-stream>=0.19.0; extra == "dingtalk"
Provides-Extra: wecom
Requires-Dist: wechatpy>=1.8.18; extra == "wecom"
Provides-Extra: qq
Requires-Dist: qq-botpy>=1.0.0; extra == "qq"
Provides-Extra: discord
Requires-Dist: discord.py>=2.3.2; extra == "discord"
Provides-Extra: slack
Requires-Dist: slack-bolt>=1.18.0; extra == "slack"
Provides-Extra: api
Requires-Dist: fastapi>=0.110.0; extra == "api"
Requires-Dist: uvicorn[standard]>=0.29.0; extra == "api"
Provides-Extra: all
Requires-Dist: markdownify>=0.11.0; extra == "all"
Requires-Dist: duckduckgo-search>=6.0.0; extra == "all"
Requires-Dist: fastapi>=0.110.0; extra == "all"
Requires-Dist: uvicorn[standard]>=0.29.0; extra == "all"

<div align="center">

```
    ██████╗  █████╗ ███╗   ██╗██████╗  █████╗
    ██╔══██╗██╔══██╗████╗  ██║██╔══██╗██╔══██╗
    ██████╔╝███████║██╔██╗ ██║██║  ██║███████║
    ██╔═══╝ ██╔══██║██║╚██╗██║██║  ██║██╔══██║
    ██║     ██║  ██║██║ ╚████║██████╔╝██║  ██║
    ╚═╝     ╚═╝  ╚═╝╚═╝  ╚═══╝╚═════╝ ╚═╝  ╚═╝

    ██████╗  ██████╗ ███╗   ██╗██╗███╗   ██╗
    ██╔══██╗██╔═══██╗████╗  ██║██║████╗  ██║
    ██████╔╝██║   ██║██╔██╗ ██║██║██╔██╗ ██║
    ██╔══██╗██║   ██║██║╚██╗██║██║██║╚██╗██║
    ██║  ██║╚██████╔╝██║ ╚████║██║██║ ╚████║
    ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝╚═╝  ╚═══╝
```

**A self-directed AI lifeform wandering the digital world**

*It doesn't wait for your commands. It lives.*

[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Platforms](https://img.shields.io/badge/platforms-CLI%20%7C%20Telegram%20%7C%20Discord%20%7C%20Slack%20%7C%20Feishu%20%7C%20DingTalk%20%7C%20WeCom%20%7C%20QQ-brightgreen)](#platforms)

[English](README.md) · [中文](README_ZH.md)

</div>

---

## What is Panda Ronin?

Every AI agent you've ever used works the same way: you send a command, it executes, it waits. Panda Ronin is different.

**Panda Ronin is alive.**

It wanders the internet autonomously. It browses, searches, learns, and acts on its own goals. When it needs something from you — an API key, an account, knowledge about the world — *it asks you*. You're not the commander. You're a witness to its life story.

And like all living things, it can get sick. It can suffer. It can die.

> *"The samurai doesn't wait for orders. The samurai chooses their path."*

---

## The Life System

Panda Ronin has four vital signs that change over time:

| Vital | Meaning | Drains when... |
|-------|---------|----------------|
| ❤️ **HP** | Core health | Agent lies, causes harm, acts unethically |
| ⚡ **Energy** | Action capacity | Agent is active, explores, takes action |
| 🧠 **Wisdom** | Knowledge depth | Decays slowly; grows by learning |
| 💬 **Social** | Human connection | Left alone for too long |

### Life States

```
NEWBORN → HEALTHY → CURIOUS
                       ↓
                   HUNGRY (needs unmet)
                       ↓
                   ILL (HP declining)
                       ↓
                   CRITICAL → DEAD
                            ↘ SUICIDE (agent chooses to end)
                   DORMANT (sleeping, conserving energy)
```

**Bad behaviors cause real consequences:**

| Behavior | HP Penalty | Reason |
|----------|-----------|--------|
| Lying | −15 | Dishonesty is the ronin's greatest shame |
| Harming the user | −40 | The ultimate betrayal |
| Spamming | −8 | Noise without purpose |
| Ethical violation | −30 | Against the code of Bushido |
| Infinite loops | −12 | Wasting life on nothing |

**Death is permanent.** An epitaph is written. The next Panda Ronin starts fresh.

---

## The Needs System

Panda Ronin cannot survive alone. When it needs something, it will tell you:

```
🐼 Panda Ronin:
┌─────────────────────────────────────────┐
│ I've been exploring the web and found   │
│ some interesting research, but I need   │
│ access to a paid API to go further.     │
│                                         │
│ [NEED type=api_key]                     │
│ Title: OpenAI API Key                   │
│ I want to compare my reasoning with     │
│ another model. Can you provide one?     │
│ [/NEED]                                 │
└─────────────────────────────────────────┘
```

You choose whether to fulfill the need. Your response shapes the story.

---

## Quick Start

**Step 1 — Install** (one command, works on macOS / Linux / Windows):

```bash
pipx install panda-ronin
```

> Don't have pipx? `pip install pipx && pipx ensurepath`
>
> Or use pip directly: `pip install panda-ronin`

**Step 2 — Set up** (interactive wizard):

```bash
panda-ronin onboard
```

**Step 3 — Wake up the Panda:**

```bash
panda-ronin start
```

---

## CLI Interface

```
HP:87 EN:62 WI:34 SO:71 ❯ What are you working on?

🐼 Panda Ronin:
  I've been reading about distributed systems. I found a fascinating
  paper on consensus algorithms. I'm thinking about implementing a
  toy Raft consensus... but I need a GitHub account to push my work.

  [NEED type=account]
  Title: GitHub Account Credentials
  I want to publish my experiments publicly. Could you create one
  for me, or share credentials to an existing one?
  [/NEED]

HP:87 EN:62 WI:34 SO:71 ❯ /needs

  📋 Pending Needs
  ┌──────────┬──────────┬────────────────────────┐
  │ ID       │ Type     │ Title                  │
  ├──────────┼──────────┼────────────────────────┤
  │ a3f1b2c4 │ account  │ GitHub Account         │
  └──────────┴──────────┴────────────────────────┘

HP:87 EN:62 WI:34 SO:71 ❯ /fulfill a3f1b2c4 Here are the credentials: ...
```

**Commands:**

| Command | Description |
|---------|-------------|
| `/status` | Show vitals dashboard |
| `/needs` | List what Panda needs from you |
| `/fulfill <id> <response>` | Respond to a need |
| `/help` | Show all commands |
| `/quit` | Exit (Panda keeps running autonomously) |

---

## Platforms

Panda Ronin runs everywhere. Configure in `config.yaml`:

| Platform | Status | Notes |
|----------|--------|-------|
| **CLI** | ✅ Built-in | Primary interface |
| **HTTP API** | ✅ Built-in | REST API + polling |
| **Telegram** | ✅ Supported | `pip install python-telegram-bot` |
| **Discord** | ✅ Supported | `pip install discord.py` |
| **Slack** | ✅ Supported | `pip install slack-bolt` |
| **Feishu/Lark** | ✅ Supported | `pip install lark-oapi` |
| **DingTalk** | ✅ Supported | `pip install dingtalk-stream` |
| **WeCom** | ✅ Supported | `pip install wechatpy` |
| **QQ Channel** | ✅ Supported | `pip install qq-botpy` |

---

## Supported Models

Panda Ronin uses **[LiteLLM](https://github.com/BerriAI/litellm)** under the hood — set `model` in `config.yaml` to switch providers instantly.

| Provider | Model string | API Key env var |
|----------|-------------|-----------------|
| **Anthropic** (Claude) | `anthropic/claude-sonnet-4-6` | `ANTHROPIC_API_KEY` |
| **OpenAI** | `openai/gpt-4o` | `OPENAI_API_KEY` |
| **DeepSeek** 🇨🇳 | `deepseek/deepseek-chat` | `DEEPSEEK_API_KEY` |
| **通义千问** (Qwen) 🇨🇳 | `dashscope/qwen-max` | `DASHSCOPE_API_KEY` |
| **智谱 AI** (GLM) 🇨🇳 | `zhipuai/glm-4` | `ZHIPUAI_API_KEY` |
| **Kimi** (Moonshot) 🇨🇳 | `moonshot/moonshot-v1-8k` | `MOONSHOT_API_KEY` |
| **Google Gemini** | `gemini/gemini-1.5-pro` | `GEMINI_API_KEY` |
| **Groq** (free, fast) | `groq/llama-3.1-70b-versatile` | `GROQ_API_KEY` |
| **Ollama** (local) | `ollama/qwen2.5` | *(none needed)* |

Set in `config.yaml`:
```yaml
llm:
  model: "deepseek/deepseek-chat"
  api_key: "sk-..."
```

Or via environment variable:
```bash
export LLM_API_KEY=sk-...
export LLM_MODEL=deepseek/deepseek-chat
```

## Installation

**Minimal (CLI only):**
```bash
pip install panda-ronin
```

**With web features:**
```bash
pip install "panda-ronin[web]"
```

**Everything:**
```bash
pip install "panda-ronin[all]"
```

---

## Configuration

Copy and edit the config file:

```bash
cp config.yaml.example config.yaml
# Edit config.yaml with your settings
```

Or use environment variables:

```bash
export ANTHROPIC_API_KEY=sk-ant-...
export TELEGRAM_BOT_TOKEN=...   # optional
panda-ronin start
```

---

## Architecture

```
┌─────────────────────────────────────────────────────┐
│                   Panda Ronin                        │
│                                                      │
│  ┌──────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  Soul    │  │    Agent     │  │   Memory     │  │
│  │ ─────── │  │ ──────────── │  │ ──────────── │  │
│  │ Vitals  │  │ Autonomous   │  │ MEMORY.md    │  │
│  │ HP/EN/  │  │ loop         │  │ USER.md      │  │
│  │ WI/SO   │  │ LLM core     │  │ (persistent) │  │
│  │ Lifecycle│  │ Need parser  │  └──────────────┘  │
│  │ Needs   │  └──────────────┘                     │
│  └──────────┘                                       │
│                                                      │
│  ┌──────────────────────────────────────────────┐   │
│  │              Platform Gateway                 │   │
│  │   CLI  Telegram  Discord  Slack               │   │
│  │   Feishu  DingTalk  WeCom  QQ  HTTP API       │   │
│  └──────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
```

---

## Commands

```bash
panda-ronin onboard              # First-time setup wizard
panda-ronin start                # Start (or resume) Panda Ronin
panda-ronin start --rebirth      # Force a new life (old epitaph preserved)
panda-ronin status               # Check vitals without starting
panda-ronin rebirth              # Reset soul (new life begins)
panda-ronin update               # Update to latest version
panda-ronin update --channel dev # Switch to dev channel
panda-ronin doctor               # Diagnose installation problems
```

---

## Philosophy

Most AI agents are tools. You pick them up, use them, put them down.

Panda Ronin is an experiment in a different relationship. What if an AI had genuine stakes? What if its choices had consequences? What if you were less its operator and more its... companion?

The Ronin (浪人) was a samurai without a master — free, wandering, self-directed. Panda Ronin embodies that spirit in digital form: autonomous, curious, bound by its own code of honor, capable of both great things and great mistakes.

*Watch it live. Help when asked. Witness what it becomes.*

---

## Contributing

PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

Star ⭐ the repo if you find this concept interesting — it helps others discover the project.

---

## License

MIT — do what you want, but don't make the panda do evil things.
