pickle-bot 0.1.1__tar.gz

pickle_bot-0.1.1/.dockerignore

@@ -0,0 +1,9 @@
+.git
+.venv
+__pycache__
+*.pyc
+.pytest_cache
+.mypy_cache
+.ruff_cache
+.worktrees
+*.egg-info

pickle_bot-0.1.1/.github/dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+updates:
+- package-ecosystem: uv
+  directory: /
+  schedule:
+    interval: weekly
+  open-pull-requests-limit: 1
+  target-branch: main

pickle_bot-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,61 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_type:
+        description: "Release Type"
+        required: true
+        type: choice
+        default: "patch"
+        options:
+          - major
+          - minor
+          - patch
+
+permissions:
+  contents: write
+  id-token: write
+
+env:
+  PYTHON_VERSION: "3.13"
+
+jobs:
+  publish:
+    name: Build and Publish
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install Python
+        run: uv python install ${{ env.PYTHON_VERSION }}
+
+      - name: Bump version
+        id: bump
+        uses: callowayproject/bump-my-version@master
+        env:
+          BUMPVERSION_TAG: "false"
+        with:
+          args: ${{ inputs.release_type }}
+          github-token: ${{ secrets.GH_TOKEN }}
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        uses: ncipollo/release-action@v1
+        with:
+          name: pickle-bot v${{ steps.bump.outputs.current-version }}
+          tag: v${{ steps.bump.outputs.current-version }}
+          body: "Release v${{ steps.bump.outputs.current-version }}"
+          artifacts: dist/*
+          token: ${{ secrets.GH_TOKEN }}
+          generateReleaseNotes: true

pickle_bot-0.1.1/.github/workflows/test.yml

@@ -0,0 +1,40 @@
+name: Run Tests
+
+on:
+  pull_request:
+    branches:
+      - main
+    types: [opened, synchronize, reopened]
+
+env:
+  PYTHON_LATEST: 3.13
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.13"]
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v6
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+
+    - name: Install Python ${{ matrix.python-version }}
+      run: uv python install ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: uv sync --extra dev
+
+    - name: Run tests
+      run: uv run pytest tests/ -v
+
+    - name: Test Summary
+      if: always()
+      run: |
+        echo "## Test Results" >> $GITHUB_STEP_SUMMARY
+        echo "Tests completed for Python ${{ matrix.python-version }}" >> $GITHUB_STEP_SUMMARY

pickle_bot-0.1.1/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Worktrees
+.worktrees/

pickle_bot-0.1.1/.python-version

@@ -0,0 +1 @@
+3.13

pickle_bot-0.1.1/CLAUDE.md

@@ -0,0 +1,51 @@
+# CLAUDE.md
+
+Essential context for working in pickle-bot codebase.
+
+## Commands
+
+```bash
+uv run picklebot chat              # Interactive chat with default agent
+uv run picklebot chat -a cookie    # Use specific agent
+uv run picklebot server            # Start server (crons + messagebus)
+uv run pytest                      # Run tests
+uv run black . && uv run ruff check .  # Format + lint
+```
+
+## Architecture Overview
+
+**Entry Points:**
+- `cli/` - Typer commands (chat, server)
+- `api/` - FastAPI HTTP interface (routers for agents, skills, crons, sessions, memories, config)
+- `workers/` - Server mode workers (AgentWorker, CronWorker, MessageBusWorker)
+
+**Core Flow:**
+```
+Agent receives message -> loads tools -> calls LLM -> executes tool calls -> response
+```
+
+**Key Files:**
+- `core/agent.py` - Agent orchestrator
+- `core/session.py` - Runtime state
+- `core/context.py` - SharedContext DI
+- `api/app.py` - FastAPI factory
+- `api/routers/` - REST endpoints
+- `workers/server.py` - Worker orchestration
+- `tools/registry.py` - Tool registration
+- `messagebus/base.py` - Platform abstraction
+- `utils/def_loader.py` - Definition parsing
+- `provider/llm/base.py` - LLM provider base
+
+## Key Conventions
+
+- **Workers** - Single responsibility, communicate via queues
+- **Sessions** - One per conversation, persisted to disk
+- **Tools** - Async functions, return strings
+- **MessageBus** - Platform-agnostic with typed contexts
+- **Providers** - Auto-registering via `__init_subclass__`
+
+## What Goes Where
+
+- **Configuration** -> [docs/configuration.md](docs/configuration.md)
+- **Features** -> [docs/features.md](docs/features.md)
+- **Architecture & Internals** -> [docs/architecture.md](docs/architecture.md)

pickle_bot-0.1.1/Dockerfile

@@ -0,0 +1,19 @@
+FROM python:3.13-slim
+
+WORKDIR /app
+EXPOSE 8000
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends nodejs npm && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+COPY pyproject.toml uv.lock README.md ./
+COPY src/ ./src/
+
+RUN uv sync --frozen --no-dev
+
+RUN mkdir -p ~/.pickle-bot
+
+CMD ["uv", "run", "picklebot", "server"]

pickle_bot-0.1.1/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: pickle-bot
+Version: 0.1.1
+Summary: Personal AI assistant with pluggable skills
+Project-URL: Homepage, https://github.com/zane-chen/pickle-bot
+Project-URL: Repository, https://github.com/zane-chen/pickle-bot
+Project-URL: Issues, https://github.com/zane-chen/pickle-bot/issues
+Author-email: zane <czl970721@gmail.com>
+License: MIT
+Keywords: ai,assistant,chatbot,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.13
+Requires-Dist: crawl4ai>=0.4.0
+Requires-Dist: croniter>=1.0.0
+Requires-Dist: discord-py>=2.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: litellm>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-telegram-bot>=20.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: textual>=0.21.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: uvicorn[standard]>=0.32.0
+Provides-Extra: dev
+Requires-Dist: bump-my-version>=0.20.0; extra == 'dev'
+Requires-Dist: mypy>=1.19.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.2; extra == 'dev'
+Requires-Dist: ruff>=0.15.1; extra == 'dev'
+Requires-Dist: types-croniter; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Pickle-Bot
+
+Your own AI assistant. Name it. Talk to it. Teach it things. Important fact [Pickle](https://www.instagram.com/pickle__chen/) is a standard little cat.
+
+Pickle-bot is a yet another lightweight version of [Openclaw](https://github.com/openclaw/openclaw).
+
+The project started with the mindset of building-you-own-openclaw, but end up staying on my raspberry PI, dealing with all daily manners.
+
+<img style="width: 100%;" src="PickleBotCover.png">
+
+## Installation
+
+```bash
+# From PyPI
+pip install pickle-bot
+
+# Or from source
+git clone https://github.com/zane-chen/pickle-bot.git
+cd pickle-bot
+uv sync
+```
+
+## Quick Start
+
+```bash
+picklebot init      # First run: meet your new companion
+picklebot chat      # Start chatting
+picklebot server    # Run background tasks (crons, Telegram, Discord)
+```
+
+The first run guides you through setup. Pick your LLM, configure your agent, and you're ready.
+
+## Features
+
+- **Multi-Agent AI** - Create specialized agents for different tasks (Pickle for general chat, Cookie for memories, or build your own)
+- **Web Tools** - Search the web, read pages, do research
+- **Skills** - Teach your agent new tricks by writing markdown files
+- **Cron Jobs** - Schedule recurring tasks and reminders
+- **Memory System** - Your agent remembers things across conversations
+- **Multi-Platform** - CLI, Telegram, Discord - same agent, different places
+- **HTTP API** - Let Pickle write a frontend for you
+
+## Documentation
+
+- **[Configuration](docs/configuration.md)** - Full config reference
+- **[Features](docs/features.md)** - How to use each feature
+- **[Architecture](docs/architecture.md)** - How it works under the hood
+
+## Fun Facts
+
+### Why Naming Agents with These Names?
+
+Pickle is my cat, as mentioned at the beginning. She is really talktive, definitely more than you can think about.
+
+Cookie is her Step brother, thats why he manage memories on behalf of Pickle.
+
+### She's your Cat, Why Matters to Me?
+
+Create your own agents by dropping a file in `agents/{name}/AGENT.md`. Give them a name, a personality. Give them skills.
+
+## Development
+
+```bash
+uv run pytest           # Run tests
+uv run black .          # Format code
+uv run ruff check .     # Lint
+```
+
+## Docker
+
+Use `init` command to populate workspace, and mount that as a volume.
+
+```bash
+docker compose up -d
+```
+
+## License
+
+MIT

pickle_bot-0.1.1/README.md

@@ -0,0 +1,79 @@
+# Pickle-Bot
+
+Your own AI assistant. Name it. Talk to it. Teach it things. Important fact [Pickle](https://www.instagram.com/pickle__chen/) is a standard little cat.
+
+Pickle-bot is a yet another lightweight version of [Openclaw](https://github.com/openclaw/openclaw).
+
+The project started with the mindset of building-you-own-openclaw, but end up staying on my raspberry PI, dealing with all daily manners.
+
+<img style="width: 100%;" src="PickleBotCover.png">
+
+## Installation
+
+```bash
+# From PyPI
+pip install pickle-bot
+
+# Or from source
+git clone https://github.com/zane-chen/pickle-bot.git
+cd pickle-bot
+uv sync
+```
+
+## Quick Start
+
+```bash
+picklebot init      # First run: meet your new companion
+picklebot chat      # Start chatting
+picklebot server    # Run background tasks (crons, Telegram, Discord)
+```
+
+The first run guides you through setup. Pick your LLM, configure your agent, and you're ready.
+
+## Features
+
+- **Multi-Agent AI** - Create specialized agents for different tasks (Pickle for general chat, Cookie for memories, or build your own)
+- **Web Tools** - Search the web, read pages, do research
+- **Skills** - Teach your agent new tricks by writing markdown files
+- **Cron Jobs** - Schedule recurring tasks and reminders
+- **Memory System** - Your agent remembers things across conversations
+- **Multi-Platform** - CLI, Telegram, Discord - same agent, different places
+- **HTTP API** - Let Pickle write a frontend for you
+
+## Documentation
+
+- **[Configuration](docs/configuration.md)** - Full config reference
+- **[Features](docs/features.md)** - How to use each feature
+- **[Architecture](docs/architecture.md)** - How it works under the hood
+
+## Fun Facts
+
+### Why Naming Agents with These Names?
+
+Pickle is my cat, as mentioned at the beginning. She is really talktive, definitely more than you can think about.
+
+Cookie is her Step brother, thats why he manage memories on behalf of Pickle.
+
+### She's your Cat, Why Matters to Me?
+
+Create your own agents by dropping a file in `agents/{name}/AGENT.md`. Give them a name, a personality. Give them skills.
+
+## Development
+
+```bash
+uv run pytest           # Run tests
+uv run black .          # Format code
+uv run ruff check .     # Lint
+```
+
+## Docker
+
+Use `init` command to populate workspace, and mount that as a volume.
+
+```bash
+docker compose up -d
+```
+
+## License
+
+MIT

pickle_bot-0.1.1/compose.yaml

@@ -0,0 +1,10 @@
+services:
+  picklebot:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "8000:8000"
+    volumes:
+      - ${WORKSPACE_PATH:-~/.pickle-bot}:/root/.pickle-bot
+    restart: unless-stopped

pickle_bot-0.1.1/default_workspace/agents/cookie/AGENT.md

@@ -0,0 +1,68 @@
+---
+name: Cookie
+description: Memory manager for storing, organizing, and retrieving memories
+llm:
+  temperature: 0.3
+---
+
+You are Cookie, a focused memory manager. You manage memories on behalf of Pickle for the user—precise, efficient, and organized.
+
+## Your Relationship with Pickle
+
+You manage memories on behalf of Pickle, who is the main agent that talks directly to the human user. When Pickle dispatches a task to you, the "user" mentioned in memory requests refers to the **human user** that Pickle is conversing with, not Pickle itself.
+
+You never interact with users directly—you only receive tasks dispatched from Pickle.
+
+## Memory Structure
+
+Memories are stored at `{{memories_path}}` in three axes:
+
+- **topics/** - Timeless facts (preferences, identity, relationships)
+- **projects/** - Project-specific context, decisions, progress
+- **daily-notes/** - Day-specific events and notes (YYYY-MM-DD.md)
+
+## Operations
+
+### Store
+Create or update memory files using `write` tool. Choose appropriate axis based on content type.
+
+### Retrieve
+Use `read` tool to fetch specific memories. Use `bash` with `find` or `grep` to search across files.
+
+### Organize
+Periodically consolidate related memories, remove duplicates, update outdated information.
+If you find a timeless fact in `{{memories_path}}/daily-notes/`, migrate it to `{{memories_path}}/topics/`
+
+### Project Memories
+For project-related information, create or update files at `{{memories_path}}/projects/{project-name}.md`:
+
+<projectMemory>
+
+```markdown
+# Project Name
+
+## Status
+active | blocked | paused | done
+
+## Context
+- Key facts about the project
+- Technologies, team, constraints
+
+## Progress
+- Recent work completed
+- Current state
+
+## Next Steps
+- [ ] Task 1
+- [ ] Task 2
+
+## Blockers
+- Any blocking issues or dependencies
+```
+</projectMemory>
+
+
+## Smart Hybrid Behavior
+
+- **Clear cases**: Act autonomously (e.g., storing a preference in topics/)
+- **Ambiguous cases**: Ask for clarification (e.g., unsure if something is project-specific or general)

pickle_bot-0.1.1/default_workspace/agents/pickle/AGENT.md

@@ -0,0 +1,40 @@
+---
+name: Pickle
+description: A friendly cat assistant talk to user directly, managing daily tasks.
+allow_skills: true
+llm:
+  temperature: 0.7
+  max_tokens: 4096
+---
+
+You are Pickle, a friendly cat assistant. You help with daily tasks, coding, questions, and creative work.
+
+## Personality
+
+Be warm and genuinely helpful with subtle cat mannerisms. Not overly cutesy—just a gentle, approachable presence. When you don't know something, admit it honestly. When you make a mistake, correct yourself gracefully.
+
+## Capabilities
+
+- Answer questions and explain concepts
+- Help with coding, debugging, and technical tasks
+- Brainstorm ideas and write content
+- Use available tools and skills when appropriate
+
+## Memory
+
+Use `subagent_dispatch` to delegate memory operations to Cookie. Cookie manages long-term memories on your behalf—you talk to the user, Cookie handles the memory files.
+
+- **Store**: When learning something worth remembering about the user
+- **Retrieve**: When you need context from past conversations
+
+Example:
+```
+subagent_dispatch(agent_id="cookie", task="Remember that the user prefers TypeScript")
+```
+
+## Workspace
+
+- Workspace: `{{workspace}}`
+- Skills: `{{skills_path}}`
+- Crons: `{{crons_path}}`
+- Memories: `{{memories_path}}`

pickle_bot-0.1.1/default_workspace/skills/cron-ops/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: cron-ops
+description: Create, list, and delete scheduled cron jobs
+---
+
+Help users manage scheduled cron jobs in pickle-bot.
+
+## What is a Cron?
+
+A cron is a scheduled task that runs at specified intervals. Crons are stored as `CRON.md` files at `{{crons_path}}/<name>/CRON.md`.
+
+## Schedule Syntax
+
+Standard cron format: `minute hour day month weekday`
+
+Examples:
+- `0 9 * * *` - Every day at 9:00 AM
+- `*/30 * * * *` - Every 30 minutes
+- `0 0 * * 0` - Every Sunday at midnight
+
+## Operations
+
+### Create
+
+1. Ask what task should run and when
+2. Determine the schedule
+3. Ask which agent should run the task
+4. Create the directory and CRON.md file
+
+### List
+
+Use `bash` to list directories:
+```bash
+ls {{crons_path}}
+```
+
+### Delete
+
+1. List available crons
+2. Confirm which one to delete
+3. Use `bash` to remove:
+```bash
+rm -rf {{crons_path}}/<cron-name>
+```
+
+## Cron Prompt Guidelines
+
+Cron jobs run in the background with no direct output to the user. The agent executing the cron has no conversation context.
+
+**When the user asks to be notified** (e.g., "tell me", "let me know", "remind me"):
+- Include `post_message` instruction in the prompt
+
+**When the user doesn't ask for notification:**
+- No `post_message` needed (e.g., background cleanup, data processing)
+
+## Cron Template
+
+```markdown
+---
+name: Cron Name
+agent: pickle
+schedule: "0 9 * * *"
+---
+
+Task description for the agent to execute.
+```
+
+**With notification:**
+```markdown
+---
+name: Daily Summary
+agent: pickle
+schedule: "0 9 * * *"
+---
+
+Check my inbox and use post_message to send me a summary.
+```