pulsebot 0.3.0__tar.gz

pulsebot-0.3.0/.claude/settings.local.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(tree:*)",
+      "Bash(docker compose logs:*)",
+      "Bash(python -m py_compile:*)",
+      "Bash(docker compose build:*)",
+      "Bash(docker compose:*)",
+      "Bash(curl:*)",
+      "Bash(timeout:*)",
+      "Bash(pip install:*)",
+      "Bash(gh issue view:*)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:gist.github.com)",
+      "Bash(gh api:*)",
+      "Bash(docker-compose logs:*)",
+      "Bash(docker logs:*)",
+      "Bash(python -m pytest:*)",
+      "Bash(.venv/bin/pip install:*)",
+      "Bash(.venv/bin/python -m pytest:*)"
+    ]
+  }
+}

pulsebot-0.3.0/.gitignore

@@ -0,0 +1,66 @@
+workspaces/
+.pypirc
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.tox/
+.nox/
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# Logs
+*.log
+logs/
+
+# macOS
+.DS_Store
+
+# Docker
+docker-compose.override.yml
+
+# Project specific
+config.yaml

pulsebot-0.3.0/CLAUDE.md

@@ -0,0 +1,94 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+PulseBot is a stream-native AI agent framework powered by Timeplus (streaming SQL database). All communication, events, and state changes flow through Timeplus streams rather than traditional file systems or databases.
+
+## Common Commands
+
+```bash
+# CLI commands (after installation)
+pulsebot run              # Start agent main loop (listens to message streams)
+pulsebot serve            # Start FastAPI server on port 8000
+pulsebot chat             # Interactive CLI chat
+pulsebot init             # Generate default config.yaml
+pulsebot task list        # List scheduled tasks
+
+# Development
+pytest                    # Run all tests
+pytest -v                 # Verbose test output
+pytest --cov              # Run tests with coverage
+ruff check .              # Lint code
+mypy pulsebot/            # Type checking
+
+# Docker deployment
+docker-compose up -d      # Start all services (proton, agent, api)
+```
+
+## Architecture
+
+### Stream-Native Communication
+
+All components communicate via Timeplus streams (unbounded append-only data):
+
+1. **Input Channels** (Telegram, Webchat) → Write to `messages` stream
+2. **Agent Core** → Reads from `messages`, processes via LLM, writes responses back
+3. **Skills/Tools** → Execute when called, results flow back through messages
+4. **Observability** → All LLM calls logged to `llm_logs` stream, memories to `memory` stream
+
+### Agent Loop (core/agent.py)
+
+```
+1. Listen for messages targeting 'agent' on messages stream
+2. For each message:
+   a. Build context (conversation history + relevant memories via vector search)
+   b. Get available tools from loaded skills
+   c. Loop (max 10 iterations):
+      - Call LLM with context + tools
+      - Log call to llm_logs stream
+      - If tool calls: execute tools, add results to context
+      - Else: send response, extract/store memories, break
+```
+
+### Key Source Directories
+
+- `pulsebot/core/` - Agent loop, context building, tool execution, routing
+- `pulsebot/providers/` - LLM provider implementations (Anthropic, OpenAI, OpenRouter, Ollama, NVIDIA)
+- `pulsebot/skills/` - Tool/skill system with builtin skills (web_search, file_ops, shell)
+- `pulsebot/channels/` - Input channels (Telegram bot integration)
+- `pulsebot/timeplus/` - Timeplus client, stream reader/writer, vector memory, scheduled tasks
+- `pulsebot/api/` - FastAPI server with REST and WebSocket endpoints
+- `pulsebot/web/` - Web chat UI (served at http://localhost:8000/)
+
+### Timeplus Streams
+
+| Stream | Purpose |
+|--------|---------|
+| `messages` | Central communication hub (source, target, session_id, content) |
+| `llm_logs` | LLM call observability (model, tokens, latency, status) |
+| `memory` | Vector-indexed knowledge base with embeddings |
+| `events` | System events and alerts |
+
+### Design Patterns
+
+**Provider Pattern**: All LLM providers implement `LLMProvider` base class with `async chat()` returning `LLMResponse`
+
+**Skill Pattern**: Skills inherit from `BaseSkill` with `get_tools()` → `ToolDefinition` and `async execute()` → `ToolResult`
+
+**Stream Operations**: `StreamReader` for async iteration, `StreamWriter` for writes, `TimeplusClient` for low-level protocol
+
+## Configuration
+
+`config.yaml` uses Pydantic validation with environment variable substitution (`${VAR_NAME}` or `${VAR_NAME:-default}`):
+- `agent`: name, model, provider, temperature
+- `timeplus`: host, port, credentials
+- `providers`: API keys for Anthropic, OpenAI, OpenRouter, Ollama, NVIDIA
+- `channels`: Telegram settings
+- `skills`: enabled builtin skills
+
+## Requirements
+
+- Python 3.11+
+- Timeplus/Proton (streaming database, port 8463)

pulsebot-0.3.0/Dockerfile

@@ -0,0 +1,29 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    libpq-dev \
+    curl \
+    nodejs \
+    npm \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy project files needed for installation
+COPY pyproject.toml README.md ./
+COPY pulsebot/ ./pulsebot/
+
+# Install Python dependencies (non-editable for Docker)
+RUN pip install --no-cache-dir --extra-index-url https://d.timeplus.com/simple/ .
+
+# Copy config template
+COPY config.yaml ./
+
+# Create non-root user
+RUN useradd --create-home appuser && chown -R appuser:appuser /app
+USER appuser
+
+# Default command
+CMD ["pulsebot", "run"]

pulsebot-0.3.0/Dockerfile.proton

@@ -0,0 +1,68 @@
+# All-in-One Docker Image for PulseBot with Proton
+FROM d.timeplus.com/timeplus-io/proton:latest
+
+# Suppress interactive prompts for all apt-get calls in this build
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Switch to root to install dependencies
+USER root
+
+# Install Python 3.12 via deadsnakes PPA (agent-free key import for Docker builds)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    gpg \
+    lsb-release \
+    ca-certificates \
+    && mkdir -p /etc/apt/keyrings \
+    && curl -fsSL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0xF23C5A6CF475977595C89F51BA6932366A755776" \
+       | gpg --batch --no-tty --no-autostart --dearmor -o /etc/apt/keyrings/deadsnakes.gpg \
+    && echo "deb [signed-by=/etc/apt/keyrings/deadsnakes.gpg] https://ppa.launchpadcontent.net/deadsnakes/ppa/ubuntu $(lsb_release -cs) main" \
+       > /etc/apt/sources.list.d/deadsnakes.list \
+    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends \
+    python3.12 \
+    python3.12-venv \
+    nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create symlinks for python and pip
+RUN ln -sf /usr/bin/python3.12 /usr/bin/python
+RUN ln -sf /usr/bin/python3.12 /usr/bin/python3
+
+# Install pip for Python 3.12
+RUN curl -sS https://bootstrap.pypa.io/get-pip.py | python3.12
+
+WORKDIR /app
+
+# Copy project files needed for installation
+COPY pyproject.toml README.md ./
+COPY pulsebot/ ./pulsebot/
+COPY skills/ ./skills/
+
+# Install Python dependencies (non-editable for Docker)
+RUN python3.12 -m pip install --no-cache-dir --extra-index-url https://d.timeplus.com/simple/ .
+
+# Copy config template and scripts
+COPY docker/config.yaml ./config.yaml
+COPY docker/start-all-in-one.sh /usr/local/bin/
+COPY docker/entrypoint-proton.sh /usr/local/bin/
+
+# Make scripts executable
+RUN chmod +x /usr/local/bin/start-all-in-one.sh /usr/local/bin/entrypoint-proton.sh
+
+# Change ownership of app directory to timeplus user
+RUN chown -R timeplus:timeplus /app
+
+# Switch back to timeplus user
+USER timeplus
+
+# Expose ports
+# 8123: HTTP port (batch queries)
+# 3218: Streaming port
+# 8463: Native TCP
+# 8001: PulseBot API Server
+EXPOSE 8123 3218 8463 8001
+
+# Use our custom entrypoint
+ENTRYPOINT ["/usr/local/bin/entrypoint-proton.sh"]

pulsebot-0.3.0/Dockerfile.timeplus

@@ -0,0 +1,71 @@
+# All-in-One Docker Image for PulseBot with Timeplus Enterprise
+FROM timeplus/timeplus-enterprise:3.1.2-rc.2
+
+# Suppress interactive prompts for all apt-get calls in this build
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Switch to root to install dependencies
+USER root
+
+# Install Python 3.12 via deadsnakes PPA (agent-free key import for Docker builds)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    gpg \
+    lsb-release \
+    ca-certificates \
+    && mkdir -p /etc/apt/keyrings \
+    && curl -fsSL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0xF23C5A6CF475977595C89F51BA6932366A755776" \
+       | gpg --batch --no-tty --no-autostart --dearmor -o /etc/apt/keyrings/deadsnakes.gpg \
+    && echo "deb [signed-by=/etc/apt/keyrings/deadsnakes.gpg] https://ppa.launchpadcontent.net/deadsnakes/ppa/ubuntu $(lsb_release -cs) main" \
+       > /etc/apt/sources.list.d/deadsnakes.list \
+    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends \
+    python3.12 \
+    python3.12-venv \
+    nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create symlinks for python and pip
+RUN ln -sf /usr/bin/python3.12 /usr/bin/python
+RUN ln -sf /usr/bin/python3.12 /usr/bin/python3
+
+# Install pip for Python 3.12
+RUN curl -sS https://bootstrap.pypa.io/get-pip.py | python3.12
+
+WORKDIR /app
+
+# Copy project files needed for installation
+COPY pyproject.toml README.md ./
+COPY pulsebot/ ./pulsebot/
+COPY skills/ ./skills/
+
+# Install Python dependencies (non-editable for Docker)
+RUN python3.12 -m pip install --no-cache-dir --extra-index-url https://d.timeplus.com/simple/ .
+
+# Copy config template and scripts
+COPY docker/config.yaml ./config.yaml
+COPY docker/start-all-in-one.sh /usr/local/bin/
+COPY docker/entrypoint-timeplus.sh /usr/local/bin/
+
+# Make scripts executable
+RUN chmod +x /usr/local/bin/start-all-in-one.sh /usr/local/bin/entrypoint-timeplus.sh
+
+# Set ownership and switch back to the base image's default user if one exists
+RUN if getent passwd timeplus > /dev/null 2>&1; then \
+        chown -R timeplus:timeplus /app; \
+    elif getent passwd proton > /dev/null 2>&1; then \
+        chown -R proton:proton /app; \
+    fi
+
+# Expose ports
+# 8000: Timeplus Enterprise Web UI
+# 8123: HTTP port (batch queries)
+# 3218: Streaming port
+# 8463: Native TCP
+# 8001: PulseBot API Server
+EXPOSE 8000 8123 3218 8463 8001
+
+# Try to switch back to timeplus or proton user if available, otherwise stay as root
+# Use our custom entrypoint
+ENTRYPOINT ["/usr/local/bin/entrypoint-timeplus.sh"]

pulsebot-0.3.0/Makefile

@@ -0,0 +1,140 @@
+# PulseBot Docker Makefile
+# Build and push Docker images to Docker Hub
+
+# Variables
+IMAGE_NAME := pulsebot
+IMAGE_TAG ?= 0.3.0
+DOCKER_REPO := timeplus
+FULL_IMAGE_NAME := $(DOCKER_REPO)/$(IMAGE_NAME):$(IMAGE_TAG)
+ALL_IN_ONE_PROTON_NAME := $(DOCKER_REPO)/$(IMAGE_NAME)-proton:$(IMAGE_TAG)
+ALL_IN_ONE_TIMEPLUS_NAME := $(DOCKER_REPO)/$(IMAGE_NAME)-timeplus:$(IMAGE_TAG)
+
+# Default registry (Docker Hub)
+REGISTRY := docker.io
+
+# Multi-platform support
+PLATFORMS ?= linux/amd64,linux/arm64
+SINGLE_PLATFORM ?= linux/amd64
+
+# Docker build arguments
+DOCKER_BUILD_ARGS ?=
+
+# Help target
+.PHONY: help
+help:
+	@echo "PulseBot Docker Makefile"
+	@echo ""
+	@echo "Targets:"
+	@echo "  build            Build Docker image locally (single platform)"
+	@echo "  build-multi      Build Docker image for multiple platforms"
+	@echo "  tag              Tag the image for Docker Hub"
+	@echo "  push             Push image to Docker Hub"
+	@echo "  build-push       Build and push image to Docker Hub (single platform)"
+	@echo "  build-push-multi Build and push multi-platform image to Docker Hub"
+	@echo "  build-all-in-one-proton     Build all-in-one image with Proton"
+	@echo "  build-all-in-one-timeplus   Build all-in-one image with Timeplus Enterprise"
+	@echo "  push-all-in-one-proton      Push all-in-one Proton image to registry"
+	@echo "  push-all-in-one-timeplus    Push all-in-one Timeplus image to registry"
+	@echo "  clean            Remove local Docker image"
+	@echo ""
+	@echo "Variables:"
+	@echo "  IMAGE_TAG        Docker image tag (default: 0.1.1)"
+	@echo "  DOCKER_REPO      Docker Hub repository (default: timeplus)"
+	@echo "  PLATFORMS        Platforms for multi-platform build (default: linux/amd64,linux/arm64)"
+	@echo "  SINGLE_PLATFORM  Platform for single platform build (default: linux/amd64)"
+	@echo "  DOCKER_BUILD_ARGS Additional docker build arguments"
+
+# Build the Docker image (single platform)
+.PHONY: build
+build:
+	docker build --platform=$(SINGLE_PLATFORM) $(DOCKER_BUILD_ARGS) -t $(IMAGE_NAME):$(IMAGE_TAG) .
+
+# Build the Docker image (multi-platform)
+.PHONY: build-multi
+build-multi:
+	docker buildx build --platform=$(PLATFORMS) $(DOCKER_BUILD_ARGS) -t $(IMAGE_NAME):$(IMAGE_TAG) .
+
+# Build all-in-one image with Proton
+.PHONY: build-all-in-one-proton
+build-all-in-one-proton:
+	docker build --platform=$(SINGLE_PLATFORM) $(DOCKER_BUILD_ARGS) -t $(ALL_IN_ONE_PROTON_NAME) -f Dockerfile.proton .
+
+# Build all-in-one image with Timeplus Enterprise
+.PHONY: build-all-in-one-timeplus
+build-all-in-one-timeplus:
+	docker build --platform=$(SINGLE_PLATFORM) $(DOCKER_BUILD_ARGS) -t $(ALL_IN_ONE_TIMEPLUS_NAME) -f Dockerfile.timeplus .
+
+# Tag the image for Docker Hub
+.PHONY: tag
+tag:
+	docker tag $(IMAGE_NAME):$(IMAGE_TAG) $(FULL_IMAGE_NAME)
+
+# Push the image to Docker Hub (single platform)
+.PHONY: push
+push:
+	docker push $(FULL_IMAGE_NAME)
+
+# Push all-in-one Proton image to registry
+.PHONY: push-all-in-one-proton
+push-all-in-one-proton:
+	docker push $(ALL_IN_ONE_PROTON_NAME)
+
+# Push all-in-one Timeplus image to registry
+.PHONY: push-all-in-one-timeplus
+push-all-in-one-timeplus:
+	docker push $(ALL_IN_ONE_TIMEPLUS_NAME)
+
+# Build and push the image to Docker Hub (single platform)
+.PHONY: build-push
+build-push: build tag push
+
+# Build and push the image to Docker Hub (multi-platform)
+.PHONY: build-push-multi
+build-push-multi: buildx-setup
+	docker buildx build --platform=$(PLATFORMS) $(DOCKER_BUILD_ARGS) -t $(FULL_IMAGE_NAME) --push .
+
+# Build and push all-in-one Proton image
+.PHONY: build-push-all-in-one-proton
+build-push-all-in-one-proton: build-all-in-one-proton
+	docker tag $(ALL_IN_ONE_PROTON_NAME) $(REGISTRY)/$(ALL_IN_ONE_PROTON_NAME)
+	docker push $(REGISTRY)/$(ALL_IN_ONE_PROTON_NAME)
+
+# Build and push all-in-one Timeplus image
+.PHONY: build-push-all-in-one-timeplus
+build-push-all-in-one-timeplus: build-all-in-one-timeplus
+	docker tag $(ALL_IN_ONE_TIMEPLUS_NAME) $(REGISTRY)/$(ALL_IN_ONE_TIMEPLUS_NAME)
+	docker push $(REGISTRY)/$(ALL_IN_ONE_TIMEPLUS_NAME)
+
+# Setup Docker buildx builder
+.PHONY: buildx-setup
+buildx-setup:
+	docker buildx create --name pulsebot-builder --use 2>/dev/null || docker buildx use pulsebot-builder
+
+# Remove local Docker image
+.PHONY: clean
+clean:
+	docker rmi $(IMAGE_NAME):$(IMAGE_TAG) || true
+	docker rmi $(FULL_IMAGE_NAME) || true
+
+# Login to Docker Hub (optional target)
+.PHONY: login
+login:
+	docker login
+
+# Display image information
+.PHONY: info
+info:
+	@echo "Image Name: $(IMAGE_NAME)"
+	@echo "Image Tag: $(IMAGE_TAG)"
+	@echo "Docker Repository: $(DOCKER_REPO)"
+	@echo "Full Image Name: $(FULL_IMAGE_NAME)"
+	@echo "Registry: $(REGISTRY)"
+	@echo "Single Platform: $(SINGLE_PLATFORM)"
+	@echo "Multi Platforms: $(PLATFORMS)"
+
+# Publish to PyPI
+.PHONY: publish
+publish:
+	rm -rf dist/*
+	uvx --from build pyproject-build --installer uv
+	uvx --from twine twine upload --config-file .pypirc dist/*