langclaw 0.1.0__tar.gz

langclaw-0.1.0/.cursor/rules/extending-the-framework.mdc

@@ -0,0 +1,48 @@
+---
+description: When adding new tools, channels, middleware, message bus backends, or checkpointer backends to the langclaw framework
+alwaysApply: false
+---
+
+# Extending Langclaw
+
+## Adding a Tool
+
+Tools are async functions decorated with `@tool` from `langchain_core.tools` or registered via `@app.tool()` on the `Langclaw` instance. Follow the pattern in `langclaw/agents/tools/`.
+
+- Return a dict on failure: `{"error": f"Failed to ...: {exc}"}` — never raise
+- Add type hints to all parameters — LangChain uses them for the tool schema
+- The docstring becomes the tool description the LLM sees — make it actionable
+- Register in `langclaw/agents/tools/__init__.py` if it's a built-in tool
+
+## Adding a Channel
+
+Extend `BaseChannel` in `langclaw/gateway/base.py`. See `telegram.py`, `discord.py`, `websocket.py` for reference.
+
+- Implement `start()`, `stop()`, `send()`, and `send_ai_message()`
+- The channel publishes `InboundMessage` to the bus — it never talks to the agent directly
+- Add the optional dependency to `pyproject.toml` under `[project.optional-dependencies]`
+- Guard the import in `Langclaw._build_all_channels()` with `try/except ImportError`
+
+## Adding a Bus or Checkpointer Backend
+
+Follow the abstract-base + factory pattern:
+
+1. Create the implementation in the respective package (e.g. `bus/redis_bus.py`)
+2. Extend the abstract base (`bus/base.py` or `checkpointer/base.py`)
+3. Implement the async context manager protocol (`__aenter__` / `__aexit__`)
+4. Register in the factory function (`make_message_bus` or `make_checkpointer_backend`)
+5. Add config options to `config/schema.py` following the existing nested pattern
+
+## Adding Middleware
+
+Middleware uses the `@wrap_model_call` pattern from deepagents. See `middleware/permissions.py` for the canonical example.
+
+- Middleware filters or transforms the tool list **before** the LLM sees it
+- Order matters — middleware is composed in `agents/builder.py`
+- Accept `LangclawConfig` in the factory, return the middleware callable
+
+## Config Changes
+
+When adding config, update both:
+1. `langclaw/config/schema.py` — add the Pydantic model/field
+2. `.env.example` — document the new env var with the `LANGCLAW__` prefix

langclaw-0.1.0/.cursor/rules/testing.mdc

@@ -0,0 +1,26 @@
+---
+description: Testing conventions for langclaw
+globs: tests/**/*.py
+alwaysApply: false
+---
+
+# Testing
+
+## Setup
+
+- Framework: pytest + pytest-asyncio (`asyncio_mode = "auto"` — no need for `@pytest.mark.asyncio`)
+- Run: `uv run pytest tests/ -v`
+
+## Patterns
+
+- Use `monkeypatch.setenv()` for env var overrides — never mutate `os.environ` directly
+- Use factory functions (`make_message_bus`, `make_checkpointer_backend`) for integration tests
+- Class-based grouping for related tests (e.g. `TestSplitMessage`, `TestIsAllowed`)
+- Prefer real implementations over mocks when the component is fast and deterministic (buses, config)
+- For async tests, just define `async def test_...` — the auto mode handles the rest
+
+## Assertions
+
+- Assert tool error responses with `assert result == {"error": ...}`
+- For bus tests, use `async with bus:` and break after first consumed message
+- For config tests, use `monkeypatch.setenv("LANGCLAW__...", value)` then call `load_config()`

langclaw-0.1.0/.env.example

@@ -0,0 +1,249 @@
+# ============================================================
+# langclaw — environment configuration
+# Copy this file to .env and fill in your values.
+# All variables use the LANGCLAW__ prefix with __ as the
+# nested delimiter (matches pydantic-settings).
+# ============================================================
+
+
+# ------------------------------------------------------------
+# LLM Providers — set at least one
+# ------------------------------------------------------------
+# Langclaw uses LangChain's init_chat_model() which reads standard
+# provider env vars directly. Set the key for your chosen provider.
+
+# Anthropic (default model: claude-sonnet-4-5-20250929)
+# ANTHROPIC_API_KEY=sk-ant-...
+
+# OpenAI
+# OPENAI_API_KEY=sk-...
+
+# Google Gemini
+# GOOGLE_API_KEY=...
+
+# OpenRouter (routes to any model, useful as a fallback)
+# OPENROUTER_API_KEY=...
+
+# Azure OpenAI
+# AZURE_OPENAI_API_KEY=...
+# AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com/
+# OPENAI_API_VERSION=2025-01-01-preview
+#   Set model to azure_openai:<your-deployment-name>
+#   The part after the colon is the Azure *deployment* name (set in Azure AI Foundry),
+#   NOT the underlying model name. Examples:
+#     LANGCLAW__AGENTS__MODEL=azure_openai:gpt-4o-prod
+#     LANGCLAW__AGENTS__MODEL=azure_openai:my-claude-deployment
+
+# Ollama (local — no key needed)
+# OLLAMA_BASE_URL=http://localhost:11434
+
+
+# ------------------------------------------------------------
+# Agent
+# ------------------------------------------------------------
+
+# Model string format: "<provider>:<model-name>"
+# Examples: anthropic:claude-sonnet-4-5-20250929  |  openai:gpt-4.1
+LANGCLAW__AGENTS__MODEL=anthropic:claude-sonnet-4-5-20250929
+
+# Requests per minute per user before rate-limit kicks in
+LANGCLAW__AGENTS__RATE_LIMIT_RPM=60
+
+# Comma-separated keywords that will be blocked before reaching the LLM
+# LANGCLAW__AGENTS__BANNED_KEYWORDS=
+
+
+# ------------------------------------------------------------
+# Permissions (per-user tool RBAC)
+# ------------------------------------------------------------
+
+# Enable per-user tool permission filtering.
+# When disabled (default), all users get access to every tool.
+# LANGCLAW__PERMISSIONS__ENABLED=false
+
+# Role assigned to users not listed in any channel's USER_ROLES.
+# LANGCLAW__PERMISSIONS__DEFAULT_ROLE=viewer
+
+# Role definitions (role -> allowed tools) are best set in
+# ~/.langclaw/config.json because nested dicts don't map
+# cleanly to env vars.  Example config.json snippet:
+#
+#   {
+#     "permissions": {
+#       "enabled": true,
+#       "default_role": "viewer",
+#       "roles": {
+#         "admin":  { "tools": ["*"] },
+#         "editor": { "tools": ["web_search", "web_fetch",
+#                                "gmail_read", "gmail_send"] },
+#         "viewer": { "tools": ["web_search", "web_fetch"] }
+#       }
+#     }
+#   }
+#
+# Use ["*"] to grant a role access to all tools (including
+# deepagents built-ins like ls, read_file, write_file, etc.).
+# Per-channel user -> role mappings live alongside ALLOW_FROM
+# in each channel section below.
+
+
+# ------------------------------------------------------------
+# Channels — Telegram (default/recommended)
+# ------------------------------------------------------------
+
+# Get a token from @BotFather on Telegram
+LANGCLAW__CHANNELS__TELEGRAM__ENABLED=true
+LANGCLAW__CHANNELS__TELEGRAM__TOKEN=<your-telegram-bot-token>
+
+# Whitelist of Telegram user IDs or @usernames (leave empty to allow everyone)
+# LANGCLAW__CHANNELS__TELEGRAM__ALLOW_FROM=123456789,@yourusername
+
+# Per-user role mapping (format: user_id:role,user_id:role)
+# Only used when PERMISSIONS__ENABLED=true
+# LANGCLAW__CHANNELS__TELEGRAM__USER_ROLES=123456789:admin,@yourusername:editor
+
+# Discord (disabled by default — requires langclaw[discord])
+# LANGCLAW__CHANNELS__DISCORD__ENABLED=false
+# LANGCLAW__CHANNELS__DISCORD__TOKEN=
+# LANGCLAW__CHANNELS__DISCORD__USER_ROLES=123456:admin,789012:viewer
+
+
+# ------------------------------------------------------------
+# Message Bus
+# ------------------------------------------------------------
+
+# asyncio  — default, single-process (dev / single-instance)
+# rabbitmq — multi-process production (requires langclaw[rabbitmq])
+# kafka    — high-throughput (requires langclaw[kafka])
+LANGCLAW__BUS__BACKEND=asyncio
+
+# RabbitMQ (only used when BUS__BACKEND=rabbitmq)
+# LANGCLAW__BUS__RABBITMQ__AMQP_URL=amqp://guest:guest@localhost/
+# LANGCLAW__BUS__RABBITMQ__QUEUE_NAME=langclaw.inbound
+
+# Kafka (only used when BUS__BACKEND=kafka)
+# LANGCLAW__BUS__KAFKA__BOOTSTRAP_SERVERS=localhost:9092
+# LANGCLAW__BUS__KAFKA__TOPIC=langclaw.inbound
+# LANGCLAW__BUS__KAFKA__GROUP_ID=langclaw
+
+
+# ------------------------------------------------------------
+# Checkpointer (conversation state persistence)
+# ------------------------------------------------------------
+
+# sqlite   — default, zero-config (dev / single-process)
+# postgres — production multi-instance (requires langclaw[postgres])
+LANGCLAW__CHECKPOINTER__BACKEND=sqlite
+
+# SQLite database file path (tilde expansion supported)
+LANGCLAW__CHECKPOINTER__SQLITE__DB_PATH=~/.langclaw/state.db
+
+# PostgreSQL DSN (only used when CHECKPOINTER__BACKEND=postgres)
+# LANGCLAW__CHECKPOINTER__POSTGRES__DSN=postgresql://user:pass@localhost:5432/langclaw
+
+
+# ------------------------------------------------------------
+# Tools (web search & fetch — requires langclaw[search])
+# ------------------------------------------------------------
+
+# Search backend: brave | tavily | duckduckgo (default: brave)
+# LANGCLAW__TOOLS__SEARCH_BACKEND=brave
+
+# Brave Search API key (required when SEARCH_BACKEND=brave)
+# Get one at https://api.search.brave.com/app/dashboard
+# LANGCLAW__TOOLS__BRAVE_API_KEY=BSA...
+
+# Tavily Search API key (required when SEARCH_BACKEND=tavily)
+# Get one at https://app.tavily.com
+# LANGCLAW__TOOLS__TAVILY_API_KEY=tvly-...
+
+# duckduckgo requires no API key
+
+
+# ------------------------------------------------------------
+# Tools — Gmail (requires langclaw[gmail])
+# ------------------------------------------------------------
+
+# Enable Gmail tools (read, search, send, draft, reply, labels)
+# Requires a Google Cloud project with the Gmail API enabled and
+# OAuth 2.0 Desktop credentials.
+# Setup guide: https://console.cloud.google.com/apis/credentials
+# LANGCLAW__TOOLS__GMAIL__ENABLED=true
+
+# OAuth 2.0 client_id and client_secret from your credentials JSON
+# LANGCLAW__TOOLS__GMAIL__CLIENT_ID=123456789-xxxxxxx.apps.googleusercontent.com
+# LANGCLAW__TOOLS__GMAIL__CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxx
+
+# When true, only read_email and search_emails are registered.
+# Set to false to also enable send, draft, reply, and label management.
+# LANGCLAW__TOOLS__GMAIL__READONLY=true
+
+# Path to the persisted OAuth token (created automatically on first auth)
+# LANGCLAW__TOOLS__GMAIL__TOKEN_PATH=~/.langclaw/gmail_token.json
+
+
+# ------------------------------------------------------------
+# Cron
+# ------------------------------------------------------------
+
+LANGCLAW__CRON__ENABLED=true
+LANGCLAW__CRON__TIMEZONE=UTC
+
+# ── Local dev (default) ──────────────────────────────────────────────────────
+# SQLite + local broker: persistent, zero-config, single-process.
+# Requires: uv add sqlalchemy aiosqlite
+#
+# Jobs survive gateway restarts and are visible to `langclaw cron list`.
+# Both the gateway and the CLI connect directly to the same .db file.
+
+# Data store — where job schedules are persisted
+#   sqlite   — default, persistent local file (requires sqlalchemy + aiosqlite)
+#   postgres — persistent shared DB (requires sqlalchemy + asyncpg)
+#   memory   — in-process only, lost on restart
+LANGCLAW__CRON__DATA_STORE__BACKEND=sqlite
+
+# SQLite data store path (only used when DATA_STORE__BACKEND=sqlite)
+# LANGCLAW__CRON__DATA_STORE__SQLITE__DB_PATH=~/.langclaw/cron.db
+
+# ── Production ───────────────────────────────────────────────────────────────
+# PostgreSQL data store + asyncpg or psycopg event broker.
+# Required when running multiple gateway instances (shared scheduler state).
+# Requires: uv add sqlalchemy asyncpg   (or psycopg[binary] for psycopg broker)
+#
+# LANGCLAW__CRON__DATA_STORE__BACKEND=postgres
+# LANGCLAW__CRON__DATA_STORE__POSTGRES__DSN=postgresql+asyncpg://user:pass@localhost/langclaw
+
+# ── Production + Redis pub/sub ───────────────────────────────────────────────
+# Use when you prefer Redis over PostgreSQL pub/sub for scheduler events.
+# Requires: uv add sqlalchemy asyncpg redis
+#
+# LANGCLAW__CRON__DATA_STORE__BACKEND=postgres
+# LANGCLAW__CRON__DATA_STORE__POSTGRES__DSN=postgresql+asyncpg://user:pass@localhost/langclaw
+# LANGCLAW__CRON__EVENT_BROKER__BACKEND=redis
+# LANGCLAW__CRON__EVENT_BROKER__REDIS__HOST=localhost
+# LANGCLAW__CRON__EVENT_BROKER__REDIS__PORT=6379
+
+# Event broker — how scheduler events are fanned out across instances
+#   local   — default, in-process only (single gateway instance)
+#   asyncpg — PostgreSQL pub/sub via asyncpg (multi-instance)
+#   psycopg — PostgreSQL pub/sub via psycopg3 (multi-instance)
+#   redis   — Redis pub/sub (multi-instance)
+LANGCLAW__CRON__EVENT_BROKER__BACKEND=local
+
+# asyncpg event broker DSN (only used when EVENT_BROKER__BACKEND=asyncpg)
+# LANGCLAW__CRON__EVENT_BROKER__ASYNCPG__DSN=postgresql+asyncpg://user:pass@localhost/langclaw
+
+# psycopg event broker DSN (only used when EVENT_BROKER__BACKEND=psycopg)
+# LANGCLAW__CRON__EVENT_BROKER__PSYCOPG__DSN=postgresql+psycopg://user:pass@localhost/langclaw
+
+# Redis event broker (only used when EVENT_BROKER__BACKEND=redis)
+# LANGCLAW__CRON__EVENT_BROKER__REDIS__HOST=localhost
+# LANGCLAW__CRON__EVENT_BROKER__REDIS__PORT=6379
+
+
+# ------------------------------------------------------------
+# Heartbeat (proactive condition-based agent wake-up)
+# ------------------------------------------------------------
+
+LANGCLAW__HEARTBEAT__ENABLED=false
+LANGCLAW__HEARTBEAT__INTERVAL_SECONDS=60

langclaw-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["**"]
+  pull_request: {}
+
+env:
+  UV_FROZEN: "1"
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+          enable-cache: true
+          cache-suffix: lint
+
+      - name: Install dependencies
+        run: uv sync --group lint
+
+      - name: Run pre-commit
+        run: uv run pre-commit run --all-files --verbose
+        env:
+          SKIP: no-commit-to-branch
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-suffix: test
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Test
+        run: uv run pytest tests/ -v
+
+  check:
+    if: always()
+    needs: [lint, test]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Decide whether the needed jobs succeeded or failed
+        uses: re-actors/alls-green@release/v1
+        with:
+          jobs: ${{ toJSON(needs) }}

langclaw-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "${{ github.ref_name }}" --generate-notes

langclaw-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environment
+.venv/
+venv/
+env/
+
+# Secrets — never commit these
+.env
+*.env
+!.env.example
+
+# langclaw runtime data
+~/.langclaw/
+state.db
+*.db
+workspace/**
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# pytest / coverage
+.pytest_cache/
+.coverage
+htmlcov/

langclaw-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      # - id: no-commit-to-branch
+      - id: check-yaml
+        args: ["--unsafe"]
+      - id: check-toml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-added-large-files
+        args: ["--maxkb=512"]
+        exclude: uv\.lock
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.2
+    hooks:
+      - id: ruff-format
+      - id: ruff
+        args: ["--fix"]

langclaw-0.1.0/.python-version

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

langclaw-0.1.0/AGENTS.md

@@ -0,0 +1,49 @@
+# Langclaw
+
+Multi-channel AI agent **framework** (not an app) built on LangChain, LangGraph, and deepagents. Developers `pip install langclaw` and build on top of it — think Flask/FastAPI for agentic systems. Python 3.11+.
+
+## Package Map
+
+| Package | Purpose |
+|---|---|
+| `app.py` | `Langclaw` class — developer's primary interface (decorators, lifecycle, wiring) |
+| `agents/` | LangGraph agent construction, tool wiring, subagent delegation |
+| `gateway/` | Channel orchestration (`GatewayManager`), command routing, message dispatch |
+| `bus/` | Message bus abstraction — asyncio (dev), RabbitMQ, Kafka (prod) |
+| `middleware/` | Request pipeline: RBAC, rate limit, content filter, PII redaction |
+| `config/` | Pydantic Settings with `LANGCLAW__` env var prefix (nested `__` delimiter) |
+| `cron/` | Scheduled jobs via APScheduler v4 |
+| `session/` | Maps (channel, user, context) → LangGraph thread IDs |
+| `checkpointer/` | Conversation state persistence — SQLite (dev), Postgres (prod) |
+| `providers/` | LLM model resolution via `init_chat_model` |
+| `cli/` | Typer CLI: `langclaw gateway`, `langclaw agent`, `langclaw cron`, `langclaw status` |
+
+## Development
+
+```bash
+uv sync --group dev                    # Install all deps
+uv run pytest tests/ -v                # Run tests
+uv run ruff check . && uv run ruff format .  # Lint + format
+uv run pre-commit run --all-files      # Full pre-commit suite
+```
+
+## Architecture
+
+Read `docs/ARCHITECTURE.md` for design principles and rationale. Critical invariants:
+
+- **Message flow:** Channel → `InboundMessage` → Bus → `GatewayManager` → Middleware → Agent → `OutboundMessage` → Channel
+- **Commands** (`/start`, `/reset`, `/help`) bypass the bus and LLM — handled by `CommandRouter` in `gateway/commands.py`
+- **Cron jobs** publish `InboundMessage` to the same bus, flowing through the identical agent pipeline
+- **Pluggable backends** always follow: abstract `base.py` + factory function (`make_message_bus`, `make_checkpointer_backend`)
+- **Middleware order matters** — see `agents/builder.py` for the stack composition
+- **Explicit registration** over auto-discovery — tools, channels, middleware are registered on the `Langclaw` app object
+
+## Conventions
+
+- `from __future__ import annotations` in every module
+- `TYPE_CHECKING` guard for import-only types
+- Modern type syntax: `list[T]`, `dict[K, V]`, `str | None` — never `typing.List`, `Optional`
+- `loguru.logger` for all application logging (not stdlib `logging`)
+- Google-style docstrings (Args/Returns/Raises)
+- Tools return `{"error": "..."}` dicts on failure — never raise into the agent
+- Ruff handles formatting and linting — see `[tool.ruff]` in `pyproject.toml`

langclaw-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 langclaw contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.