Metadata-Version: 2.4
Name: tiphys-ai
Version: 0.3.0
Summary: A local-first, extensible AI agent framework in Python
Project-URL: Homepage, https://github.com/substratum-labs/tiphys
Project-URL: Documentation, https://github.com/substratum-labs/tiphys#readme
Project-URL: Repository, https://github.com/substratum-labs/tiphys
Author: Tiphys Contributors
License: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,chatbot,framework,llm
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: aiofiles>=23.2.0
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: castor-kernel>=0.5.1
Requires-Dist: croniter>=2.0.0
Requires-Dist: discord-py>=2.3.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: filelock>=3.13.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: instructor>=1.0.0
Requires-Dist: litellm>=1.30.0
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: python-telegram-bot[job-queue]>=21.0
Requires-Dist: structlog>=24.1.0
Requires-Dist: uvicorn[standard]>=0.27.0
Requires-Dist: watchfiles>=0.21.0
Requires-Dist: websockets>=12.0
Provides-Extra: all
Requires-Dist: chromadb>=0.4.0; extra == 'all'
Requires-Dist: mypy>=1.8.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'all'
Requires-Dist: pytest-cov>=4.1.0; extra == 'all'
Requires-Dist: pytest>=8.0.0; extra == 'all'
Requires-Dist: ruff>=0.3.0; extra == 'all'
Requires-Dist: sentence-transformers>=2.5.0; extra == 'all'
Requires-Dist: types-aiofiles>=23.2.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Requires-Dist: types-aiofiles>=23.2.0; extra == 'dev'
Provides-Extra: memory
Requires-Dist: chromadb>=0.4.0; extra == 'memory'
Requires-Dist: sentence-transformers>=2.5.0; extra == 'memory'
Description-Content-Type: text/markdown

# Tiphys

**Your Personal AI Assistant. Python-Native. Local-First.**

[![CI](https://github.com/substratum-labs/tiphys/actions/workflows/ci.yml/badge.svg)](https://github.com/substratum-labs/tiphys/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://www.docker.com/)

Tiphys is a resilient, self-hosted AI agent framework designed to run 24/7 on your own infrastructure. Built on Python's `asyncio`, it connects your favorite messaging platforms to powerful LLMs, giving you a personal assistant that remembers context, executes tasks, and protects your data.

Inspired by [OpenClaw](https://github.com/openclaw/openclaw) (formerly Moltbot), Tiphys brings the same "local-first" philosophy to the Python ecosystem, adding enterprise-grade resilience and security defaults.
## Features

- **State-Persistent Runtime**: Powered by the [Castor](https://github.com/substratum-labs/castor) microkernel. Supports checkpoint/replay, allowing your agent to resume complex reasoning tasks even after a service restart or crash.
- **Safety Gates (HITL)**: Define mandatory human approval for high-stakes tools (e.g., spending > $1.00, executing shell commands) using Castor's capability budgets. Your agent won't spend your money or delete your files without asking.
- **Multi-Channel Hub**: Seamlessly connect via **Telegram**, **Discord**, or the built-in **WebChat** while maintaining unified context. Slack & Matrix coming soon.
- **Resilient Memory**: Long-term vector storage (ChromaDB) ensures your agent remembers who you are and what you've discussed — weeks later.
- **Task Scheduler**: "Remind me every Monday at 9am to check server logs." (Cron/Interval/One-time)
- **Secure Pairing**: One-time code authentication (`/pair 123456`) protects your DM channels.
- **Sandboxing**: Run untrusted code or shell commands inside isolated Docker containers.
- **Context Guard**: Automatically manages token limits to prevent context overflow crashes.
- **Auth Rotation**: Rotates multiple API keys to handle rate limits and quotas gracefully.
- **24/7 Resilience**: Built-in process supervision, automatic channel reconnection, and session persistence ensure your agent never sleeps.

## Quick Start

> **Prerequisites**: Have at least one LLM API key ready (e.g., OpenAI, Anthropic, or OpenRouter). Optionally, a Telegram Bot Token or Discord Bot Token if you want to connect a chat platform.

```bash
# 1. Clone & Install
git clone https://github.com/substratum-labs/tiphys.git
cd tiphys
uv sync

# 2. Configure (interactive wizard — have your API keys ready!)
uv run tiphys onboard

# 3. Launch
uv run tiphys gateway
```

Your agent is now live! Open `http://localhost:8000` to chat via WebChat, or message your configured Telegram/Discord bot.

## Deployment (Production)

For 24/7 availability, deploy Tiphys to a VPS (DigitalOcean, Hetzner, AWS) using Docker.

```bash
# 1. Clone & Configure
git clone https://github.com/substratum-labs/tiphys.git
cp .env.example .env   # edit with your API keys

# 2. Start with Docker Compose
docker compose up -d
```

Key environment variables:

| Variable | Description |
|----------|-------------|
| `TIPHYS_LLM__API_KEY` | Your LLM provider API key |
| `TIPHYS_LLM__PROVIDER` | Provider name (`openai`, `anthropic`, `openrouter`, ...) |
| `TIPHYS_SECRET_KEY` | Secret key for session encryption |

## Architecture

Tiphys uses an async, modular "Hub & Spoke" architecture:

```mermaid
graph TD
    User((User)) <-->|Telegram/Discord| Channel[Channel Adapters]
    Channel <--> Gateway[Tiphys Gateway]

    subgraph "Tiphys Core"
        Gateway <--> Agent[Agent Runtime]
        Agent <--> Kernel[Castor Kernel]
        Agent <--> Memory[(ChromaDB Memory)]
        Agent <--> Scheduler[Task Scheduler]
        Agent <--> Tools[Tool Registry]
    end

    Kernel -.->|Checkpoint/Replay| Store[(Checkpoint Store)]
    Kernel -.->|Budget & HITL| Tools
    Tools -.->|Policy Check| Policy[Security Policy]
    Tools --> Sandbox[Docker Sandbox]
```

## Documentation

| Section | Description |
|---------|-------------|
| [API Reference](docs/index.html) | Auto-generated API documentation |
| [Security](SECURITY.md) | Security policy and architecture |
| [Contributing](CONTRIBUTING.md) | Development setup and PR workflow |
| [Changelog](CHANGELOG.md) | Release notes |

## License

Apache 2.0 © [Tiphys Contributors](https://github.com/substratum-labs/tiphys/graphs/contributors)
