Metadata-Version: 2.2
Name: penguin-ai
Version: 0.8.1
Summary: Penguin: A modular, extensible AI coding agent and software engineer with its own execution environment.
Author-email: Maximus Putnam <MaximusPutnam@gmail.com>
Maintainer-email: Maximus Putnam <MaximusPutnam@gmail.com>
License: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/Maximooch/penguin
Project-URL: Repository, https://github.com/Maximooch/penguin
Project-URL: Documentation, https://penguin-rho.vercel.app
Project-URL: Bug Tracker, https://github.com/Maximooch/penguin/issues
Keywords: ai,agent,ai-agent,llm,llm-agent,assistant,cognitive-architecture,code-generation,developer-tool
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: <3.13,>=3.9
Description-Content-Type: text/markdown
Requires-Dist: tenacity>=8.0.1
Requires-Dist: pydantic>=1.8.2
Requires-Dist: python-dotenv>=0.19.0
Requires-Dist: pyyaml>=5.4.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: requests>=2.26.0
Requires-Dist: tiktoken
Requires-Dist: typing_extensions>=4.0.0
Requires-Dist: fastapi<1.0,>=0.68.0
Requires-Dist: uvicorn>=0.15.0
Requires-Dist: websockets>=10.0
Requires-Dist: python-multipart>=0.0.7
Requires-Dist: anthropic>=0.3.0
Requires-Dist: openai>=1.12.0
Requires-Dist: ollama
Requires-Dist: rich>=10.0.0
Requires-Dist: typer>=0.4.0
Requires-Dist: questionary>=1.10.0
Requires-Dist: IPython
Requires-Dist: ipykernel
Requires-Dist: ipywidgets
Requires-Dist: plotext
Requires-Dist: matplotlib
Requires-Dist: networkx
Requires-Dist: watchdog>=2.3.0
Requires-Dist: PyGithub>=1.55
Requires-Dist: GitPython>=3.1.0
Requires-Dist: Pillow>=8.3.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Provides-Extra: web
Provides-Extra: tui
Provides-Extra: legacy-tui
Requires-Dist: textual; extra == "legacy-tui"
Provides-Extra: mcp
Requires-Dist: mcp>=1.2.0; python_version >= "3.10" and extra == "mcp"
Requires-Dist: pyjwt[crypto]>=2.8.0; extra == "mcp"
Requires-Dist: requests-oauthlib>=1.3.1; extra == "mcp"
Provides-Extra: minimal
Requires-Dist: tenacity>=8.0.1; extra == "minimal"
Requires-Dist: pydantic>=1.8.2; extra == "minimal"
Requires-Dist: python-dotenv>=0.19.0; extra == "minimal"
Requires-Dist: pyyaml>=5.4.0; extra == "minimal"
Requires-Dist: httpx>=0.24.0; extra == "minimal"
Requires-Dist: tiktoken; extra == "minimal"
Requires-Dist: anthropic>=0.3.0; extra == "minimal"
Requires-Dist: openai>=1.12.0; extra == "minimal"
Provides-Extra: memory-lance
Requires-Dist: lancedb>=0.5.4; extra == "memory-lance"
Requires-Dist: pyarrow>=15.0.0; extra == "memory-lance"
Provides-Extra: memory-faiss
Requires-Dist: faiss-cpu>=1.7.4; extra == "memory-faiss"
Requires-Dist: numpy>=1.20.0; extra == "memory-faiss"
Requires-Dist: sentence-transformers>=2.3.0; extra == "memory-faiss"
Provides-Extra: memory-chroma
Requires-Dist: chromadb>=0.4.22; extra == "memory-chroma"
Provides-Extra: llm-litellm
Requires-Dist: litellm>=1.0.0; extra == "llm-litellm"
Provides-Extra: llm-transformers
Requires-Dist: transformers>=4.38.0; extra == "llm-transformers"
Requires-Dist: torch>=2.0.0; extra == "llm-transformers"
Requires-Dist: accelerate>=0.25.0; extra == "llm-transformers"
Requires-Dist: bitsandbytes>=0.43.0; sys_platform != "darwin" and extra == "llm-transformers"
Requires-Dist: sentence-transformers>=2.3.0; extra == "llm-transformers"
Provides-Extra: llm-ollama
Requires-Dist: ollama>=0.1.7; extra == "llm-ollama"
Provides-Extra: orchestration
Requires-Dist: temporalio>=1.5.0; extra == "orchestration"
Provides-Extra: pydoll
Requires-Dist: pydoll-python>=2.0.0; python_version >= "3.10" and extra == "pydoll"
Provides-Extra: browser
Requires-Dist: pydoll-python>=2.0.0; python_version >= "3.10" and extra == "browser"
Provides-Extra: dev
Requires-Dist: pytest>=6.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: hypothesis>=6.0.0; extra == "dev"
Requires-Dist: black>=21.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: textual; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Requires-Dist: wheel>=0.40.0; extra == "dev"
Requires-Dist: setuptools<77,>=76.1; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pydoll-python>=2.0.0; python_version >= "3.10" and extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=6.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: hypothesis>=6.0.0; extra == "test"
Provides-Extra: all
Requires-Dist: pyjwt[crypto]>=2.8.0; extra == "all"
Requires-Dist: mcp>=1.2.0; python_version >= "3.10" and extra == "all"
Requires-Dist: requests-oauthlib>=1.3.1; extra == "all"
Requires-Dist: lancedb>=0.5.4; extra == "all"
Requires-Dist: pyarrow>=15.0.0; extra == "all"
Requires-Dist: faiss-cpu>=1.7.4; extra == "all"
Requires-Dist: sentence-transformers>=2.3.0; extra == "all"
Requires-Dist: chromadb>=0.4.22; extra == "all"
Requires-Dist: transformers>=4.38.0; extra == "all"
Requires-Dist: torch>=2.0.0; extra == "all"
Requires-Dist: accelerate>=0.25.0; extra == "all"
Requires-Dist: bitsandbytes>=0.43.0; sys_platform != "darwin" and extra == "all"
Requires-Dist: ollama>=0.1.7; extra == "all"
Requires-Dist: temporalio>=1.5.0; extra == "all"
Requires-Dist: pydoll-python>=2.0.0; python_version >= "3.10" and extra == "all"
Requires-Dist: textual; extra == "all"

```
ooooooooo.                                                 o8o
`888   `Y88.                                               `"'
 888   .d88'  .ooooo.  ooo. .oo.    .oooooooo oooo  oooo  oooo  ooo. .oo.
 888ooo88P'  d88' `88b `888P"Y88b  888' `88b  `888  `888  `888  `888P"Y88b
 888         888ooo888  888   888  888   888   888   888   888   888   888
 888         888    .o  888   888  `88bod8P'   888   888   888   888   888
o888o        `Y8bod8P' o888o o888o `8oooooo.   `V88V"V8P' o888o o888o o888o
                                   d"     YD
                                   "Y88888P'
```

[![PyPI version](https://img.shields.io/pypi/v/penguin-ai.svg)](https://pypi.org/project/penguin-ai/)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![GitHub Actions](https://img.shields.io/github/actions/workflow/status/Maximooch/penguin/publish.yml?branch=main)](https://github.com/Maximooch/penguin/actions)
[![Documentation Status](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://penguin-rho.vercel.app)
[![Downloads](https://img.shields.io/pypi/dm/penguin-ai.svg)](https://pypi.org/project/penguin-ai/)

Penguin is an open-source coding agent built on a scalable cognitive architecture runtime.

It is designed for long-running, tool-using, multi-agent software workflows: from
interactive coding in the TUI to persistent sessions, subagent delegation, and
API-driven automation. Penguin combines a coding-focused agent runtime with durable
state, workspace-aware tools, and multiple interfaces on top of the same core.

## Why Penguin

- Purpose-built for software engineering workflows, with coding tools, sessions, and subagents.
- Stateful runtime: sessions, checkpoints, tool history, and replayable transcripts.
- Context Window Manager: long sessions stay coherent through category-aware token budgeting,
  truncation, and replay, preserving recency and message-category priorities across long-running sessions.
- Multi-agent orchestration: planner/implementer/QA patterns, subagents, and scoped delegation.
- Multiple surfaces: TUI, CLI, web API, and Python client on the same backend.
- OpenCode-compatible TUI path: Penguin web/core now powers an OpenCode-style terminal UX.

## Quick Start

```bash
# Recommended: use uv for less environment/package-management hassle,
# faster installs/syncs, and support for this repo's safer dependency workflow.
uv tool install penguin-ai

# Alternative: plain pip still works
pip install penguin-ai

# Set a model provider key (OpenRouter is the easiest starting point)
export OPENROUTER_API_KEY="your_api_key"

# Launch Penguin
penguin
```

`uv` is the recommended path for most users: it is generally faster than `pip`, keeps
Python environment management simpler, and supports this repo's `exclude-newer` safety rail
for dependency resolution in development workflows.

Other entrypoints:

- `penguin` - interactive Penguin TUI launcher
- `ptui` - direct TUI alias
- `penguin-cli` - headless CLI for automation and scripts
- `penguin-web` - FastAPI server for web/API usage

## What You Get

- Coding workflow tools: file reads/writes/diffs, shell commands, test execution, search,
  code analysis, and background process management.
- Context Window Manager: category-based token budgets, multimodal truncation, and live usage
  reporting to keep histories within model limits. This supports theoretically infinite sessions.
- Persistent memory and file-backed context: declarative notes, summary notes, `context/`
  artifacts, docs cache, and daily journal continuity.
- Multi-agent execution: isolated or shared-context subagents, delegation, planner/
  implementer/QA patterns, and background task execution.
- Browser and research support: web search plus browser automation for documentation,
  web workflows, and UI testing.
- Session durability: checkpoints, rollback, branching, transcript replay, and long-running
  task continuity.
- Project and task orchestration backed by SQLite, including todo tracking and Run Mode.
- Native and gateway model support across OpenAI, Anthropic, and OpenRouter by default, with LiteLLM available as an optional extra.

## Interfaces

Penguin exposes the same runtime through several surfaces:

- `penguin` / `ptui` - terminal-first coding workflow with streaming, tools, and session navigation.
- `penguin-cli` - scriptable CLI interface for prompts, tasks, config, and automation.
- `penguin-web` - REST + WebSocket/SSE backend for the TUI and custom integrations.
- Python API - `PenguinAgent`, `PenguinClient`, and `PenguinAPI` for embedding Penguin in code.

### Web/API Surface Notes

- Task/project endpoints now expose current runtime state rather than only legacy task summaries.
  - Task payloads include `status`, `phase`, `dependencies`, `dependency_specs`, `artifact_evidence`, `recipe`, `metadata`, and `clarification_requests` where relevant.
- `POST /api/v1/tasks/{task_id}/execute` now routes through `RunMode`, so non-terminal outcomes like `waiting_input` and clarification-needed results are preserved instead of being flattened into fake completion/failure states.
- `POST /api/v1/tasks/{task_id}/clarification/resume` answers the latest open clarification request and resumes execution through the same `RunMode` lifecycle.
- `GET /api/v1/events/sse` streams OpenCode-compatible events and now includes session-scoped clarification status visibility for web clients.
- `PenguinAPI.run_task(...)` and `PenguinAPI.resume_with_clarification(...)` are aligned with the web route behavior so programmatic callers see the same lifecycle truth.

These surfaces are still under active audit, but the current direction is explicit: web/API consumers should receive the same task/clarification truth that the backend runtime uses internally.

### Quick Python Example

```python
from penguin import PenguinAgent

with PenguinAgent() as agent:
    response = agent.chat("Summarize the current task charter")
    print(response["assistant_response"])
```

## Installation

### Recommended

```bash
# Default install: CLI + web runtime + OpenCode TUI launcher support
pip install penguin-ai

# Compatibility alias for older install commands
pip install penguin-ai[web]

# Compatibility alias for older install commands
pip install "penguin-ai[tui]"

# Legacy Textual prototype / experimental UI support
pip install "penguin-ai[legacy_tui]"

# Full feature set
pip install penguin-ai[all]
```

### Development

```bash
git clone https://github.com/Maximooch/penguin.git
cd penguin/penguin

# Safe default: respects `[tool.uv] exclude-newer = "7 days"`
uv sync

# Editable dev/test install via pip still works if you prefer it
pip install -e .[dev,test]
```

### Safer `uv` Installs

This repo configures `uv` to ignore package releases newer than 7 days by default:

```toml
[tool.uv]
exclude-newer = "7 days"
```

That gives the ecosystem a little time to detect and yank malicious releases before you
pull them in. It's a useful guardrail, not a complete supply-chain strategy.

Convenience shortcuts:

```bash
make sync-safe    # use the default 7-day delay
make lock-safe    # refresh lockfile with the 7-day delay
make lock-latest  # intentionally override and resolve newest compatible releases
make sync-latest  # resolve + sync using newest compatible releases
```

Under the hood, the `latest` targets override the project default with `--exclude-newer 2999-12-31T23:59:59Z`.

### Extras

| Extra | Description |
|---|---|
| `[tui]` | Compatibility alias; default install already includes TUI launcher runtime |
| `[web]` | Compatibility alias; default install already includes web runtime |
| `[legacy_tui]` | Legacy Textual prototype / experimental UI support |
| `[llm_litellm]` | Optional LiteLLM support for legacy/custom gateway workflows |
| `[memory_faiss]` | FAISS vector search + embeddings |
| `[memory_lance]` | LanceDB vector database |
| `[memory_chroma]` | ChromaDB integration |
| `[mcp]` | Model Context Protocol client/server dependencies (Python 3.10+ for the MCP SDK) |
| `[browser]` | Browser automation support. Installs PyDoll fallback; browser-harness must be installed from a local/source checkout because it is not published on PyPI yet. |
| `[pydoll]` | PyDoll browser automation fallback only |
| `[all]` | Everything above that is available from PyPI |

Browser-harness is Penguin's preferred `browser_*` backend on this branch, but it
is currently a local/source dependency rather than a PyPI package. For local
browser-harness testing, install Penguin's browser extra for the PyPI-available
fallback and then install browser-harness into the same environment from a source
checkout:

```bash
pip install "penguin-ai[browser]"
pip install -e /path/to/browser-harness
```

If browser-harness is unavailable, the `pydoll_browser_*` tools remain available
as the compatibility fallback.

## TUI Runtime

The Penguin TUI launcher supports both development and packaged installs.

- In a source checkout, `penguin` prefers local `penguin-tui/packages/opencode` sources.
- Outside a source checkout, it bootstraps a cached sidecar binary under `~/.cache/penguin/tui`.
- Stable installs prefer a sidecar that matches the installed Penguin version.
- You can override the source or binary path when needed:

```bash
# Force local source mode
export PENGUIN_OPENCODE_DIR="/path/to/penguin/penguin-tui/packages/opencode"

# Force a specific sidecar binary
export PENGUIN_TUI_BIN_PATH="/path/to/opencode"
```

You can also override the release endpoint for staging/testing with `PENGUIN_TUI_RELEASE_URL`.

## Common Commands

```text
/models                 # interactive model selector
/model set <MODEL_ID>   # set a specific model
/stream on|off          # toggle streaming
/checkpoint [name]      # save a checkpoint
/checkpoints [limit]    # list checkpoints
/rollback <checkpoint>  # restore a checkpoint
/tokens                 # token usage summary
/run task "Name"       # start a specific task
```

## Architecture

Penguin is structured as a runtime for long-lived agent workflows.

- `PenguinCore` coordinates configuration, interfaces, events, and runtime state.
- `Engine` runs the reasoning loop, model calls, and tool orchestration.
- `ConversationManager` persists sessions, checkpoints, and conversation state.
- `ContextWindowManager` manages long-session token budgets with category-aware truncation,
  multimodal handling, and replay-friendly context continuity.
- `ToolManager` and `ActionExecutor` run workspace-aware tools and action pipelines.
- CLI, TUI, web, and Python APIs all sit on top of the same backend services.

Penguin's long-term direction is a scalable cognitive architecture runtime: a persistent
agent kernel with userland surfaces for sessions, tools, orchestration, and observability.

Read more:

- `architecture.md`
- `context/tasks/Penguin_SCAR_80_20_Roadmap.md`
- `context/tasks/tui-opencode-implementation.md`

## Version Highlights

### v0.8.1

- Fixed Python 3.9 import compatibility for MCP configuration by avoiding a runtime PEP 604 union type alias.

### v0.8.0

- Shipped three weeks of daily dogfooding hardening across Penguin's core runtime, tool execution, task orchestration, and TUI/web surfaces.
- Added ordered batch tool execution and process-runtime foundations for more reliable multi-step agent workflows.
- Improved native tool-call runtime behavior across provider adapters, transcript replay, tool-result handling, and action execution metadata.
- Tightened RunMode, project-task, and clarification flows so API/web clients preserve non-terminal runtime truth instead of flattening everything into fake success/failure states.
- Continued OpenCode-compatible TUI integration work, including better event ordering, session scoping, sidecar packaging, and launcher behavior.
- Strengthened local web/API security and operational surfaces around auth, settings, credentials, provider routes, SSE/WebSocket behavior, and GitHub integration.
- Expanded test coverage around provider contracts, streaming, session isolation, task state, permission/question flows, package exports, and TUI launcher behavior.
- Added and updated assurance and architecture documentation for the next phase of core refactoring and testing discipline.

### v0.7.0

- Hardened the native tool-call runtime across provider adapters, transcript replay, tool-result adjacency, and TUI event ordering.
- Shipped a safer local web/TUI auth flow with protected HTTP, SSE, and WebSocket bootstrap paths plus stronger upload and webhook guards.
- Expanded project bootstrap and task orchestration surfaces across TUI, web/API routes, and Run Mode while preserving non-terminal runtime truth.
- Added OpenAI/Codex fast-mode service-tier support and improved OAuth-backed Codex/latest-model access.
- Added Penguin TUI themes and defaulted the packaged TUI experience to the Emperor theme.

### v0.6.3

- Expanded native OpenAI / Codex integration, including stronger Responses API handling and OAuth-backed Codex response support.
- Improved OpenAI-compatible provider support and model/runtime normalization for native and gateway flows.
- Better handling of tool-only OpenAI/Codex turns and Responses-style tool calls in the runtime loop.
- Continued runtime/docs alignment work across task clarification, dependency-policy, and public surface verification.

## Documentation

- [Official Documentation](https://penguin-rho.vercel.app)
- [Release Notes](https://github.com/Maximooch/penguin/releases)
- `architecture.md`
- `context/tasks/Penguin_SCAR_80_20_Roadmap.md`

## Contributing

```bash
git clone https://github.com/Maximooch/penguin.git
cd penguin/penguin
pip install -e .[dev,test]
pytest -q
```

- Open issues: [GitHub Issues](https://github.com/Maximooch/penguin/issues)
- Discuss ideas: [GitHub Discussions](https://github.com/Maximooch/penguin/discussions)

## Support

- [Documentation](https://penguin-rho.vercel.app)
- [Examples and tutorials](https://penguin-rho.vercel.app/docs/usage/)
- [Bug reports](https://github.com/Maximooch/penguin/issues/new?template=bug_report.md)
- [Feature requests](https://github.com/Maximooch/penguin/issues/new?template=feature_request.md)

## License

Licensing in this repository is split by component:

- `penguin/` and the main Penguin runtime are licensed under the GNU Affero General Public
  License v3.0 or later.
- `penguin-tui/` contains OpenCode-derived TUI code that remains MIT-licensed; see
  `penguin-tui/LICENSE`.
- Read the official [GNU AGPL v3 text](https://www.gnu.org/licenses/agpl-3.0.en.html)

Enterprise licensing without AGPL copyleft requirements is under consideration. If
you are interested, contact MaximusPutnam@gmail.com.

## Acknowledgments

Built upon insights from:

- [CodeAct](https://arxiv.org/abs/2402.01030)
- [OpenCode](https://github.com/sst/opencode) for the upstream TUI and UX foundation used in `penguin-tui/`
- [Claude-Engineer](https://github.com/Doriandarko/claude-engineer)
- [Aider](https://github.com/paul-gauthier/aider)
- [RawDog](https://github.com/AbanteAI/rawdog)
