Metadata-Version: 2.4
Name: tiphys-ai
Version: 0.4.1
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

**The autonomous research agent that learns.**

[![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/)

Drop Tiphys into any system. It explores, hypothesizes, experiments, and builds knowledge over time. The longer it runs, the deeper it understands.

Powered by the [Castor](https://pypi.org/project/castor-kernel/) security kernel for checkpoint/replay, budget control, and human-in-the-loop approval.

> **Early alpha.** APIs will change. Feedback welcome.

## Install

```bash
pip install tiphys-ai
```

## Quick Start

```bash
# Interactive setup (configure LLM provider + API key)
tiphys onboard

# Run autonomous research on a system
tiphys research "Find performance bottlenecks in this API"

# View what the agent has learned
tiphys genome

# Start the web gateway
tiphys gateway
```

## What It Does

**Research** — Give it a goal. It decomposes the goal into questions, investigates each one (hypothesis → experiment → conclusion), and writes findings as human-readable markdown documents.

**Learn** — It learns from failures. The evolution subsystem analyzes past mistakes, distills them into skills and knowledge, and injects them into the agent's prompt. It gets better over time.

**Safe** — Budget caps prevent runaway costs. Human-in-the-loop gates block risky actions. Checkpoint/replay enables rollback and time-travel debugging.

## Key Capabilities

- **Autonomous Research** — Planner decomposes goals, Researcher runs hypothesis-experiment-conclusion loops, findings accumulate as documents
- **Self-Evolution** — Consolidator learns from failures, Tool Forge builds new tools, Arena validates via counterfactual replay
- **22 Built-in Tools** — File I/O, code search (grep/glob), structured editing, shell execution, memory, scheduling
- **Document-Based Knowledge** — Findings stored as markdown with frontmatter (confidence, evidence, tags) — readable by humans and LLMs
- **Checkpoint/Replay** — Crash recovery, time-travel rollback, fork for counterfactual evaluation
- **Multi-Agent** — Spawn sub-agents with isolated sessions and delegated budgets
- **Proactive** — Background observer suggests actions (uncommitted changes, untested code, new learnings)

## License

Apache 2.0
