[](https://github.com/maximooch/penguin)
[](https://www.python.org/downloads/)
[](https://pypi.org/project/penguin-ai/)
[](https://www.gnu.org/licenses/agpl-3.0)
[](https://github.com/Maximooch/penguin/actions)
[](https://penguin-rho.vercel.app)
[](https://pypi.org/project/penguin-ai/)
[](https://github.com/psf/black)
[](https://deepwiki.com/Maximooch/penguin)
## Table of Contents
- [Overview](#overview)
- [Quick Start](#quick-start)
- [Development Status](#development-status)
- [Key Features](#key-features)
- [Installation](#installation)
- [Usage](#usage)
- [Architecture](#architecture)
- [Contributing](#contributing)
- [Support & Help](#support--help)
- [License](#license)
- [Acknowledgments](#acknowledgments)
## Overview
Penguin is an autonomous software engineering agent that goes beyond code completion—it manages entire projects from planning to execution. Unlike other AI coding assistants that require constant supervision, Penguin features built-in project management, autonomous task execution, and a modular architecture that handles everything from writing code to coordinating complex development workflows. Think of it as your AI software engineer that can take a project spec and deliver working software, not just code snippets.
## Quick Start
```bash
# Install with CLI tools (recommended for most users)
pip install penguin-ai
# Optional: Install with web interface
pip install penguin-ai[web]
# Set up your API key (OpenRouter recommended)
export OPENROUTER_API_KEY="your_api_key" # On Windows: set OPENROUTER_API_KEY=...
# Run the setup wizard
penguin config setup
# Start using Penguin
penguin # Interactive CLI chat
penguin-web # Web API server (if [web] installed)
```
## Development Status
### ✅ **Phase 2 Complete: Developer Preview (v0.2.x)**
- **Core Architecture**: Modular namespaces (`penguin.cli`, `penguin.web`, `penguin.project`)
- **CLI Interface**: Full project/task management with 20+ commands
- **Multi-Model Support**: OpenRouter, Anthropic, OpenAI via LiteLLM
- **Project Management**: SQLite ACID transactions with dependency tracking
- **Hybrid Dependencies**: Smart defaults + optional extras ([web], [memory_*], [browser])
- **Web API**: Production FastAPI/WebSocket backend with OpenAPI docs
- **Automated Publishing**: GitHub Actions with trusted PyPI publishing
### 🚧 **Phase 3 Active: Performance & Benchmarking (v0.3.x)**
**Current Performance Work:**
- **Fast Startup Mode**: Deferred memory indexing reducing cold start by 60-80%
- **Lazy Loading**: Memory providers and tools loaded on-demand vs upfront
- **Background Processing**: Memory indexing moved to separate threads
- **Profiling Integration**: Built-in performance monitoring with detailed reports
- **Resource Optimization**: Memory usage tracking and garbage collection tuning
**Benchmarking Pipeline (In Progress):**
- **SWE-bench Integration**: Automated coding task evaluation
- **HumanEval Testing**: Code generation accuracy benchmarks
- **Startup Performance**: Sub-250ms P95 target for CLI initialization
- **Memory Footprint**: <200MB baseline memory usage optimization
- **Token Efficiency**: Cost optimization with intelligent model routing
**Technical Debt & Architecture:**
- **Background Memory Daemon**: Separate process for indexing and search
- **Connection Pooling**: Database and API connection optimization
- **Async Optimization**: Converting blocking I/O to async patterns
- **Error Recovery**: Graceful degradation and circuit breaker patterns
### 📅 **Planned: Advanced Features (v0.4.x+)**
- **Rich Web UI**: React-based interface with real-time updates
- **Advanced Memory**: Vector search, knowledge graphs, cross-session learning
- **Multi-Agent Systems**: Coordinated AI agents for complex projects
- **Plugin Ecosystem**: Third-party tool integration and marketplace
[View Full Roadmap →](https://penguin-rho.vercel.app/docs/advanced/roadmap) • [Performance Tracking →](https://github.com/maximooch/penguin/blob/main/test_startup_performance.py)
<!-- For now link roadmap to future considerations, or the Penguin super roadmap file. Then later on have a github projects roadmap? -->
# Penguin AI Assistant
Penguin is a modular, extensible AI coding assistant powered by LLMs, enabling support for multiple AI models thanks to LiteLLM. It functions as an intelligent software engineer that can assist with coding tasks while maintaining its own code execution, memory tools, and workspace environment.
## Key Features
### **Cognitive Architecture**
Penguin implements a sophisticated multi-system cognitive architecture:
- **Reasoning & Response Generation**: Advanced prompt engineering with context-aware decision making
- **Persistent Memory Management**: Conversation history with cross-session knowledge retention
- **Pluggable Memory Providers**: Support for SQLite, FAISS, LanceDB, and ChromaDB backends
- **Tool & Action Processing**: Modular system with 15+ built-in tools and extensible action handlers
- **Task Coordination**: SQLite-backed project management with dependency tracking
- **Performance Monitoring**: Built-in diagnostics, error tracking, and execution metrics
### **Development Capabilities**
Comprehensive coding assistance and automation:
- **Code Execution**: IPython notebook integration for running, testing, and debugging code
- **Project Scaffolding**: Automated project structure generation with best practices
- **Code Generation**: Documentation, unit tests, and architectural recommendations
- **File System Operations**: Complete file management (create, read, write, search, organize)
- **Web Search Integration**: Real-time information retrieval during conversations
- **Browser Use**: PyDoll integration for web interaction and Chrome debugging
- **Debugging & Analysis**: Intelligent error detection and resolution suggestions
### **Project Management**
Enterprise-grade project coordination:
- **SQLite-backed Storage**: ACID transactions for reliable project and task data
- **Task Dependencies**: Complex workflow management with dependency graphs
- **Progress Tracking**: Real-time status updates and detailed execution history
- **Resource Management**: Token budgets, time limits, and tool constraints per task
- **Workspace Organization**: Structured file and project management
- **Memory Search**: Semantic search across conversations and project history
### **Multi-Interface Support**
Flexible interaction methods:
- **Interactive CLI**: Full-featured command-line with project/task management commands
- **Web API**: Production-ready REST/WebSocket backend (FastAPI-powered)
- **Python Library**: Rich programmatic API for integration and automation
- **Multi-Model Support**: OpenAI, Anthropic, OpenRouter, and local models via LiteLLM
### **Advanced Features**
- **Automatic Checkpoints**: Conversation branching and rollback capabilities *(planned)*
- **Plugin Architecture**: Extensible tool system for third-party integrations *(in development)*
- **Team Collaboration**: Multi-user workspaces and shared projects *(planned)*
- **Rich Web UI**: Complete browser interface with real-time updates *(in development)*
## Prerequisites
- [Python 3.9+](https://www.python.org/downloads/) (3.10+ recommended for best performance)
- Valid API key(s) for your chosen AI model provider(s)
- [UV package manager](https://docs.astral.sh/uv/getting-started/installation/) (optional, for development)
## Installation
### Recommended: PyPI Installation
```bash
# Core installation (includes CLI tools)
pip install penguin-ai
# With web interface
pip install penguin-ai[web]
# With memory providers
pip install penguin-ai[memory_faiss] # FAISS + sentence-transformers
pip install penguin-ai[memory_lance] # LanceDB
pip install penguin-ai[memory_chroma] # ChromaDB
# Full installation (all features)
pip install penguin-ai[all]
```
### Development Installation
For contributing or using latest features:
```bash
git clone https://github.com/maximooch/penguin.git
cd penguin/penguin
pip install -e . # Editable install
# OR with UV (faster)
pip install uv && python uv_setup.py # Automated UV setup
```
### Available Extras
| Extra | Description |
|-------|-------------|
| `[web]` | FastAPI server + WebSocket support |
| `[memory_faiss]` | FAISS vector search + embeddings |
| `[memory_lance]` | LanceDB vector database |
| `[memory_chroma]` | ChromaDB integration |
| `[browser]` | Browser automation (Python 3.11+ only) |
| `[all]` | Everything above |
## Usage
```bash
# Interactive chat
penguin
# Run setup wizard
penguin config setup
# Project management
penguin project create "My Project"
penguin project task create PROJECT_ID "Task description"
# Web API server (requires [web] extra)
penguin-web
```
For detailed usage, see the [documentation](https://penguin-rho.vercel.app).
<!-- ## 🎬 Demo & Screenshots
### CLI Interface
```bash
# Interactive chat with project context
$ penguin
🐧 Penguin AI Assistant v0.2.3
📁 Workspace: /path/to/your/project
💭 Type your message or use /help for commands
You: Create a FastAPI app with user authentication
🤖 I'll help you create a FastAPI application with user authentication...
```
### Project Management
```bash
# Create and manage projects
$ penguin project create "E-commerce API" -d "REST API for online store"
✓ Created project: E-commerce API (ID: abc123)
$ penguin project task create abc123 "Setup FastAPI project structure"
✓ Created task: Setup FastAPI project structure (ID: task456)
$ penguin project task start task456
🚀 Starting task: Setup FastAPI project structure
```
### Web API Interface
```bash
# Start the web server
$ penguin-web
🌐 Starting Penguin Web API...
📡 Server running at http://localhost:8000
📚 API docs: http://localhost:8000/docs
```
> 📸 **Coming Soon**: Screenshots and GIFs demonstrating the full interface -->
## Architecture
Penguin uses a modular architecture with these key systems:
- **Core**: Central coordinator between systems
- **Cognition**: Handles reasoning and response generation
- **Memory**: Manages context and knowledge persistence
- **Processor**: Controls tools and actions (ToolManager, Parser (ActionManager), and utils)
- **Task**: Coordinates projects and tasks
- **Diagnostic**: Monitors performance
### System Design
- Core acts as coordinator between systems
- Each system has clear responsibilities
- State management through hierarchical state machines
- Event-based communication between modules
- Memory persistence across sessions
- Tool extensibility through plugin architecture
### Key Components
1. **Cognition System**
- Reasoning and response generation
- Model integration via LiteLLM
- Context management
2. **Memory System**
- Short-term conversation memory
- Long-term knowledge persistence
- Embeddings and vector storage
- Pluggable providers (SQLite, file, FAISS, LanceDB, Chroma)
- Backup and restore utilities
3. **Processor System**
- ToolManager: Central registry and executor for available tools
- ActionExecutor: Parses and routes actions to appropriate handlers
- NotebookExecutor: Handles code execution in IPython environment
4. **Task System**
- Project and task coordination
- Workspace management
- File operations
5. **Diagnostic System**
- Performance monitoring
- Error tracking
- System health checks
### Development Standards (Not implemented yet)
- Comprehensive type annotations
- Detailed docstrings
- High test coverage (90%+)
- Robust exception handling
- Extensive logging
For detailed technical documentation, visit our [docs](https://penguin-rho.vercel.app).
## Contributing
We welcome contributions! Penguin is open source and benefits from community involvement.
### Quick Start for Contributors
```bash
# 1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/penguin.git
cd penguin/penguin
# 2. Set up development environment
pip install -e .[dev,test] # Install in development mode
pip install pre-commit && pre-commit install # Set up code formatting
# 3. Run tests to ensure everything works
pytest tests/
# 4. Make your changes and test
# 5. Submit a pull request
```
### How to Contribute
- **🐛 Bug Reports**: [Open an issue](https://github.com/Maximooch/penguin/issues) with details and reproduction steps
- **💡 Feature Requests**: [Discuss ideas](https://github.com/Maximooch/penguin/discussions) before implementing
- **📖 Documentation**: Help improve docs, examples, and guides
- **🧪 Testing**: Add test coverage for new features and edge cases
- **🎨 UI/UX**: Design improvements for CLI and web interfaces
### Development Guidelines
- Follow [PEP 8](https://pep8.org/) style guidelines (enforced by `black` and `ruff`)
- Add docstrings for public functions and classes
- Include tests for new functionality
- Update documentation for user-facing changes
- Use semantic commit messages
### Community
- [GitHub Discussions](https://github.com/Maximooch/penguin/discussions) - Questions and ideas
- [Issues](https://github.com/Maximooch/penguin/issues) - Bug reports and feature requests
- [Roadmap](https://github.com/Maximooch/penguin/projects) - Development progress
For major changes, please open an issue first to discuss your approach.
## Support & Help
### Documentation & Resources
- **[Official Documentation](https://penguin-rho.vercel.app)** - Complete user guide and API reference
- **[GitHub Discussions](https://github.com/Maximooch/penguin/discussions)** - Community Q&A and ideas
- **[Examples & Tutorials](https://penguin-rho.vercel.app/docs/usage/)** - Step-by-step guides
- **[Roadmap](https://github.com/Maximooch/penguin/projects)** - Development progress and planned features
### Issues & Bug Reports
- **[Report a Bug](https://github.com/Maximooch/penguin/issues/new?template=bug_report.md)** - Something not working?
- **[Request a Feature](https://github.com/Maximooch/penguin/issues/new?template=feature_request.md)** - Ideas for improvements
- **[Performance Issues](https://github.com/Maximooch/penguin/blob/main/test_startup_performance.py)** - Use our performance test script
### Project Status
- **Current Version**: v0.3.1 (Phase 3 Complete)
- **Active Development**: Phase 3 - Performance & Benchmarking
- **Stability**: Core features stable, performance optimization in progress
- **Python Support**: 3.9+ (3.10+ recommended for best performance)
### Changelog & Releases
- **[Release Notes](https://github.com/Maximooch/penguin/releases)** - What's new in each version
- **[Development Blog](https://penguin-rho.vercel.app/blog)** - Technical deep-dives and progress updates
## License
### Open Source License
Penguin is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
Key points:
- You must disclose source code when you deploy modified versions
- Changes must be shared under the same license
- Network use counts as distribution
- Include copyright and license notices
For the complete license text, see:
- [LICENSE](LICENSE) file in this repository
- [GNU AGPL v3](https://www.gnu.org/licenses/agpl-3.0.en.html) official text
### Enterprise License
An enterprise license without the copyleft requirements is under consideration for organizations that need different licensing terms. This would allow:
- Proprietary modifications and integrations
- No obligation to share source code changes
- Commercial redistribution rights
- Priority support and consulting services
**Interested in enterprise licensing?** Please contact the maintainer to discuss your requirements and explore available options.
## Acknowledgments
Built upon insights from:
- [CodeAct](https://arxiv.org/abs/2402.01030)
- [Claude-Engineer](https://github.com/Doriandarko/claude-engineer)
- [Aider](https://github.com/paul-gauthier/aider)
- [RawDog](https://github.com/AbanteAI/rawdog)
Raw data
{
"_id": null,
"home_page": null,
"name": "penguin-ai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Maximus Putnam <MaximusPutnam@gmail.com>",
"keywords": "ai, agent, ai-agent, llm, llm-agent, assistant, cognitive-architecture, code-generation, developer-tool",
"author": null,
"author_email": "Maximus Putnam <MaximusPutnam@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b5/ab/140bf67ce5d6aa003abf0f31c7ee0ba500d8a025f96745ad01472c9007bd/penguin_ai-0.3.2.2.tar.gz",
"platform": null,
"description": "[](https://github.com/maximooch/penguin)\n[](https://www.python.org/downloads/)\n[](https://pypi.org/project/penguin-ai/)\n[](https://www.gnu.org/licenses/agpl-3.0)\n[](https://github.com/Maximooch/penguin/actions)\n[](https://penguin-rho.vercel.app)\n[](https://pypi.org/project/penguin-ai/)\n[](https://github.com/psf/black)\n\n[](https://deepwiki.com/Maximooch/penguin)\n\n\n\n## Table of Contents\n- [Overview](#overview)\n- [Quick Start](#quick-start)\n- [Development Status](#development-status) \n- [Key Features](#key-features)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Architecture](#architecture)\n- [Contributing](#contributing)\n- [Support & Help](#support--help)\n- [License](#license)\n- [Acknowledgments](#acknowledgments)\n\n## Overview\n\nPenguin is an autonomous software engineering agent that goes beyond code completion\u2014it manages entire projects from planning to execution. Unlike other AI coding assistants that require constant supervision, Penguin features built-in project management, autonomous task execution, and a modular architecture that handles everything from writing code to coordinating complex development workflows. Think of it as your AI software engineer that can take a project spec and deliver working software, not just code snippets.\n\n## Quick Start\n```bash\n# Install with CLI tools (recommended for most users)\npip install penguin-ai\n\n# Optional: Install with web interface \npip install penguin-ai[web]\n\n# Set up your API key (OpenRouter recommended)\nexport OPENROUTER_API_KEY=\"your_api_key\" # On Windows: set OPENROUTER_API_KEY=...\n\n# Run the setup wizard\npenguin config setup\n\n# Start using Penguin\npenguin # Interactive CLI chat\npenguin-web # Web API server (if [web] installed)\n```\n\n## Development Status\n\n### \u2705 **Phase 2 Complete: Developer Preview (v0.2.x)**\n- **Core Architecture**: Modular namespaces (`penguin.cli`, `penguin.web`, `penguin.project`)\n- **CLI Interface**: Full project/task management with 20+ commands\n- **Multi-Model Support**: OpenRouter, Anthropic, OpenAI via LiteLLM \n- **Project Management**: SQLite ACID transactions with dependency tracking\n- **Hybrid Dependencies**: Smart defaults + optional extras ([web], [memory_*], [browser])\n- **Web API**: Production FastAPI/WebSocket backend with OpenAPI docs\n- **Automated Publishing**: GitHub Actions with trusted PyPI publishing\n\n### \ud83d\udea7 **Phase 3 Active: Performance & Benchmarking (v0.3.x)**\n\n**Current Performance Work:**\n- **Fast Startup Mode**: Deferred memory indexing reducing cold start by 60-80%\n- **Lazy Loading**: Memory providers and tools loaded on-demand vs upfront\n- **Background Processing**: Memory indexing moved to separate threads\n- **Profiling Integration**: Built-in performance monitoring with detailed reports\n- **Resource Optimization**: Memory usage tracking and garbage collection tuning\n\n**Benchmarking Pipeline (In Progress):**\n- **SWE-bench Integration**: Automated coding task evaluation\n- **HumanEval Testing**: Code generation accuracy benchmarks \n- **Startup Performance**: Sub-250ms P95 target for CLI initialization\n- **Memory Footprint**: <200MB baseline memory usage optimization\n- **Token Efficiency**: Cost optimization with intelligent model routing\n\n**Technical Debt & Architecture:**\n- **Background Memory Daemon**: Separate process for indexing and search\n- **Connection Pooling**: Database and API connection optimization\n- **Async Optimization**: Converting blocking I/O to async patterns\n- **Error Recovery**: Graceful degradation and circuit breaker patterns\n\n### \ud83d\udcc5 **Planned: Advanced Features (v0.4.x+)**\n- **Rich Web UI**: React-based interface with real-time updates\n- **Advanced Memory**: Vector search, knowledge graphs, cross-session learning\n- **Multi-Agent Systems**: Coordinated AI agents for complex projects \n- **Plugin Ecosystem**: Third-party tool integration and marketplace\n\n[View Full Roadmap \u2192](https://penguin-rho.vercel.app/docs/advanced/roadmap) \u2022 [Performance Tracking \u2192](https://github.com/maximooch/penguin/blob/main/test_startup_performance.py)\n\n<!-- For now link roadmap to future considerations, or the Penguin super roadmap file. Then later on have a github projects roadmap? -->\n\n# Penguin AI Assistant\n\nPenguin is a modular, extensible AI coding assistant powered by LLMs, enabling support for multiple AI models thanks to LiteLLM. It functions as an intelligent software engineer that can assist with coding tasks while maintaining its own code execution, memory tools, and workspace environment.\n\n## Key Features\n\n### **Cognitive Architecture**\nPenguin implements a sophisticated multi-system cognitive architecture:\n\n- **Reasoning & Response Generation**: Advanced prompt engineering with context-aware decision making\n- **Persistent Memory Management**: Conversation history with cross-session knowledge retention \n- **Pluggable Memory Providers**: Support for SQLite, FAISS, LanceDB, and ChromaDB backends\n- **Tool & Action Processing**: Modular system with 15+ built-in tools and extensible action handlers\n- **Task Coordination**: SQLite-backed project management with dependency tracking\n- **Performance Monitoring**: Built-in diagnostics, error tracking, and execution metrics\n\n### **Development Capabilities**\nComprehensive coding assistance and automation:\n\n- **Code Execution**: IPython notebook integration for running, testing, and debugging code\n- **Project Scaffolding**: Automated project structure generation with best practices\n- **Code Generation**: Documentation, unit tests, and architectural recommendations\n- **File System Operations**: Complete file management (create, read, write, search, organize)\n- **Web Search Integration**: Real-time information retrieval during conversations\n- **Browser Use**: PyDoll integration for web interaction and Chrome debugging\n- **Debugging & Analysis**: Intelligent error detection and resolution suggestions\n\n### **Project Management**\nEnterprise-grade project coordination:\n\n- **SQLite-backed Storage**: ACID transactions for reliable project and task data\n- **Task Dependencies**: Complex workflow management with dependency graphs\n- **Progress Tracking**: Real-time status updates and detailed execution history\n- **Resource Management**: Token budgets, time limits, and tool constraints per task\n- **Workspace Organization**: Structured file and project management\n- **Memory Search**: Semantic search across conversations and project history\n\n### **Multi-Interface Support**\nFlexible interaction methods:\n\n- **Interactive CLI**: Full-featured command-line with project/task management commands\n- **Web API**: Production-ready REST/WebSocket backend (FastAPI-powered)\n- **Python Library**: Rich programmatic API for integration and automation\n- **Multi-Model Support**: OpenAI, Anthropic, OpenRouter, and local models via LiteLLM\n\n### **Advanced Features**\n- **Automatic Checkpoints**: Conversation branching and rollback capabilities *(planned)*\n- **Plugin Architecture**: Extensible tool system for third-party integrations *(in development)*\n- **Team Collaboration**: Multi-user workspaces and shared projects *(planned)*\n- **Rich Web UI**: Complete browser interface with real-time updates *(in development)*\n\n## Prerequisites\n\n- [Python 3.9+](https://www.python.org/downloads/) (3.10+ recommended for best performance)\n- Valid API key(s) for your chosen AI model provider(s)\n- [UV package manager](https://docs.astral.sh/uv/getting-started/installation/) (optional, for development)\n\n## Installation\n\n### Recommended: PyPI Installation\n\n```bash\n# Core installation (includes CLI tools)\npip install penguin-ai\n\n# With web interface\npip install penguin-ai[web]\n\n# With memory providers\npip install penguin-ai[memory_faiss] # FAISS + sentence-transformers \npip install penguin-ai[memory_lance] # LanceDB\npip install penguin-ai[memory_chroma] # ChromaDB\n\n# Full installation (all features)\npip install penguin-ai[all]\n```\n\n### Development Installation\n\nFor contributing or using latest features:\n\n```bash\ngit clone https://github.com/maximooch/penguin.git\ncd penguin/penguin\npip install -e . # Editable install\n# OR with UV (faster)\npip install uv && python uv_setup.py # Automated UV setup\n```\n\n### Available Extras\n\n| Extra | Description | \n|-------|-------------|\n| `[web]` | FastAPI server + WebSocket support |\n| `[memory_faiss]` | FAISS vector search + embeddings |\n| `[memory_lance]` | LanceDB vector database |\n| `[memory_chroma]` | ChromaDB integration |\n| `[browser]` | Browser automation (Python 3.11+ only) |\n| `[all]` | Everything above |\n\n## Usage\n\n```bash\n# Interactive chat\npenguin\n\n# Run setup wizard\npenguin config setup\n\n# Project management\npenguin project create \"My Project\"\npenguin project task create PROJECT_ID \"Task description\"\n\n# Web API server (requires [web] extra)\npenguin-web\n```\n\nFor detailed usage, see the [documentation](https://penguin-rho.vercel.app).\n\n<!-- ## \ud83c\udfac Demo & Screenshots\n\n### CLI Interface\n```bash\n# Interactive chat with project context\n$ penguin\n\ud83d\udc27 Penguin AI Assistant v0.2.3\n\ud83d\udcc1 Workspace: /path/to/your/project\n\ud83d\udcad Type your message or use /help for commands\n\nYou: Create a FastAPI app with user authentication\n\ud83e\udd16 I'll help you create a FastAPI application with user authentication...\n```\n\n### Project Management\n```bash\n# Create and manage projects\n$ penguin project create \"E-commerce API\" -d \"REST API for online store\"\n\u2713 Created project: E-commerce API (ID: abc123)\n\n$ penguin project task create abc123 \"Setup FastAPI project structure\"\n\u2713 Created task: Setup FastAPI project structure (ID: task456)\n\n$ penguin project task start task456\n\ud83d\ude80 Starting task: Setup FastAPI project structure\n```\n\n### Web API Interface\n```bash\n# Start the web server\n$ penguin-web\n\ud83c\udf10 Starting Penguin Web API...\n\ud83d\udce1 Server running at http://localhost:8000\n\ud83d\udcda API docs: http://localhost:8000/docs\n```\n\n> \ud83d\udcf8 **Coming Soon**: Screenshots and GIFs demonstrating the full interface -->\n\n## Architecture\n\nPenguin uses a modular architecture with these key systems:\n- **Core**: Central coordinator between systems\n- **Cognition**: Handles reasoning and response generation\n- **Memory**: Manages context and knowledge persistence\n- **Processor**: Controls tools and actions (ToolManager, Parser (ActionManager), and utils)\n- **Task**: Coordinates projects and tasks\n- **Diagnostic**: Monitors performance\n\n\n### System Design\n- Core acts as coordinator between systems\n- Each system has clear responsibilities\n- State management through hierarchical state machines\n- Event-based communication between modules\n- Memory persistence across sessions\n- Tool extensibility through plugin architecture\n\n### Key Components\n1. **Cognition System**\n - Reasoning and response generation\n - Model integration via LiteLLM\n - Context management\n\n2. **Memory System**\n - Short-term conversation memory\n - Long-term knowledge persistence\n - Embeddings and vector storage\n - Pluggable providers (SQLite, file, FAISS, LanceDB, Chroma)\n - Backup and restore utilities\n\n3. **Processor System**\n - ToolManager: Central registry and executor for available tools\n - ActionExecutor: Parses and routes actions to appropriate handlers\n - NotebookExecutor: Handles code execution in IPython environment\n\n4. **Task System**\n - Project and task coordination\n - Workspace management\n - File operations\n\n5. **Diagnostic System**\n - Performance monitoring\n - Error tracking\n - System health checks\n\n### Development Standards (Not implemented yet)\n- Comprehensive type annotations\n- Detailed docstrings\n- High test coverage (90%+)\n- Robust exception handling\n- Extensive logging\n\nFor detailed technical documentation, visit our [docs](https://penguin-rho.vercel.app).\n\n## Contributing\n\nWe welcome contributions! Penguin is open source and benefits from community involvement.\n\n### Quick Start for Contributors\n\n```bash\n# 1. Fork and clone the repository\ngit clone https://github.com/YOUR_USERNAME/penguin.git\ncd penguin/penguin\n\n# 2. Set up development environment \npip install -e .[dev,test] # Install in development mode\npip install pre-commit && pre-commit install # Set up code formatting\n\n# 3. Run tests to ensure everything works\npytest tests/\n\n# 4. Make your changes and test\n# 5. Submit a pull request\n```\n\n### How to Contribute\n\n- **\ud83d\udc1b Bug Reports**: [Open an issue](https://github.com/Maximooch/penguin/issues) with details and reproduction steps\n- **\ud83d\udca1 Feature Requests**: [Discuss ideas](https://github.com/Maximooch/penguin/discussions) before implementing\n- **\ud83d\udcd6 Documentation**: Help improve docs, examples, and guides\n- **\ud83e\uddea Testing**: Add test coverage for new features and edge cases\n- **\ud83c\udfa8 UI/UX**: Design improvements for CLI and web interfaces\n\n### Development Guidelines\n\n- Follow [PEP 8](https://pep8.org/) style guidelines (enforced by `black` and `ruff`)\n- Add docstrings for public functions and classes\n- Include tests for new functionality\n- Update documentation for user-facing changes\n- Use semantic commit messages\n\n### Community\n\n- [GitHub Discussions](https://github.com/Maximooch/penguin/discussions) - Questions and ideas\n- [Issues](https://github.com/Maximooch/penguin/issues) - Bug reports and feature requests \n- [Roadmap](https://github.com/Maximooch/penguin/projects) - Development progress\n\nFor major changes, please open an issue first to discuss your approach.\n\n## Support & Help\n\n### Documentation & Resources\n- **[Official Documentation](https://penguin-rho.vercel.app)** - Complete user guide and API reference\n- **[GitHub Discussions](https://github.com/Maximooch/penguin/discussions)** - Community Q&A and ideas\n- **[Examples & Tutorials](https://penguin-rho.vercel.app/docs/usage/)** - Step-by-step guides\n- **[Roadmap](https://github.com/Maximooch/penguin/projects)** - Development progress and planned features\n\n### Issues & Bug Reports\n- **[Report a Bug](https://github.com/Maximooch/penguin/issues/new?template=bug_report.md)** - Something not working?\n- **[Request a Feature](https://github.com/Maximooch/penguin/issues/new?template=feature_request.md)** - Ideas for improvements\n- **[Performance Issues](https://github.com/Maximooch/penguin/blob/main/test_startup_performance.py)** - Use our performance test script\n\n### Project Status\n- **Current Version**: v0.3.1 (Phase 3 Complete) \n- **Active Development**: Phase 3 - Performance & Benchmarking\n- **Stability**: Core features stable, performance optimization in progress\n- **Python Support**: 3.9+ (3.10+ recommended for best performance)\n\n### Changelog & Releases\n- **[Release Notes](https://github.com/Maximooch/penguin/releases)** - What's new in each version\n- **[Development Blog](https://penguin-rho.vercel.app/blog)** - Technical deep-dives and progress updates\n\n## License\n\n### Open Source License\n\nPenguin is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.\n\nKey points:\n- You must disclose source code when you deploy modified versions\n- Changes must be shared under the same license\n- Network use counts as distribution\n- Include copyright and license notices\n\nFor the complete license text, see:\n- [LICENSE](LICENSE) file in this repository\n- [GNU AGPL v3](https://www.gnu.org/licenses/agpl-3.0.en.html) official text\n\n### Enterprise License\n\nAn enterprise license without the copyleft requirements is under consideration for organizations that need different licensing terms. This would allow:\n- Proprietary modifications and integrations\n- No obligation to share source code changes\n- Commercial redistribution rights\n- Priority support and consulting services\n\n**Interested in enterprise licensing?** Please contact the maintainer to discuss your requirements and explore available options.\n\n\n\n## Acknowledgments\n\nBuilt upon insights from:\n- [CodeAct](https://arxiv.org/abs/2402.01030)\n- [Claude-Engineer](https://github.com/Doriandarko/claude-engineer)\n- [Aider](https://github.com/paul-gauthier/aider)\n- [RawDog](https://github.com/AbanteAI/rawdog)\n\n",
"bugtrack_url": null,
"license": "AGPL-3.0-or-later",
"summary": "Penguin: A modular, extensible AI coding agent and software engineer with its own execution environment.",
"version": "0.3.2.2",
"project_urls": {
"Bug Tracker": "https://github.com/Maximooch/penguin/issues",
"Documentation": "https://penguin-rho.vercel.app",
"Homepage": "https://github.com/Maximooch/penguin",
"Repository": "https://github.com/Maximooch/penguin"
},
"split_keywords": [
"ai",
" agent",
" ai-agent",
" llm",
" llm-agent",
" assistant",
" cognitive-architecture",
" code-generation",
" developer-tool"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e515e1e327ac3a3999f31bead3bbe3e20bbc4539de1e217621f96dd3db3b71cb",
"md5": "450e65b84ba909edbdc5dd1f30c0557c",
"sha256": "47da845ca983f62b078ebae9fbd5198213698a48e9a0baa371fb48d4dc5391a6"
},
"downloads": -1,
"filename": "penguin_ai-0.3.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "450e65b84ba909edbdc5dd1f30c0557c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 541778,
"upload_time": "2025-07-24T00:34:52",
"upload_time_iso_8601": "2025-07-24T00:34:52.603687Z",
"url": "https://files.pythonhosted.org/packages/e5/15/e1e327ac3a3999f31bead3bbe3e20bbc4539de1e217621f96dd3db3b71cb/penguin_ai-0.3.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b5ab140bf67ce5d6aa003abf0f31c7ee0ba500d8a025f96745ad01472c9007bd",
"md5": "d2ebccc9fedc92719067aa3b685a925c",
"sha256": "fb4f37c56debd255b1c26fa8fd7adc1c0ff3e196d3dd4b8eb0b5b7bacec313fc"
},
"downloads": -1,
"filename": "penguin_ai-0.3.2.2.tar.gz",
"has_sig": false,
"md5_digest": "d2ebccc9fedc92719067aa3b685a925c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 510371,
"upload_time": "2025-07-24T00:34:54",
"upload_time_iso_8601": "2025-07-24T00:34:54.287980Z",
"url": "https://files.pythonhosted.org/packages/b5/ab/140bf67ce5d6aa003abf0f31c7ee0ba500d8a025f96745ad01472c9007bd/penguin_ai-0.3.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 00:34:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Maximooch",
"github_project": "penguin",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "penguin-ai"
}
JSON
