Metadata-Version: 2.5
Name: penguin-agent-package
Version: 0.1.2
Summary: Simple, minimalistic AI-Agent for Linux that runs on almost every device
Author-email: theobalduser <fzierenberg@icloud.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.12
Requires-Dist: animation>=0.0.7
Requires-Dist: annotated-types>=0.8.0
Requires-Dist: anyio>=4.15.1
Requires-Dist: certifi>=2026.7.22
Requires-Dist: dotenv
Requires-Dist: ghostprint>=2.0.0
Requires-Dist: h11>=0.16.0
Requires-Dist: httpcore>=1.0.9
Requires-Dist: httpx>=0.28.1
Requires-Dist: idna>=3.20
Requires-Dist: ollama>=0.6.2
Requires-Dist: prompt-toolkit>=3.0.53
Requires-Dist: pychalk>=2.0.1
Requires-Dist: pydantic-core>=2.46.5
Requires-Dist: pydantic>=2.13.5
Requires-Dist: six>=1.17.0
Requires-Dist: typing-extensions>=4.16.0
Requires-Dist: typing-inspection>=0.4.4
Requires-Dist: wcwidth>=0.9.1
Description-Content-Type: text/markdown

# penguin
Simple, minimalist AI-Agent for Linux that runs on almost every device

![Alt Text](https://github.com/Test1-eu/penguin-agent/blob/main/ressources/bildschirmaufzeichnung-vom-2026-09-26-23-34-26_q3iOhA72%20(online-video-cutter.com).gif)

## LLM
Penguin uses (at the moment) the qwen3.5:2b model with Ollama as inference. The model can run at a good conversation speed on most modern laptops and a bit slower on older machines, the minimum I reached with an eight years old Lenovo Thinkpad(i5, 7th generation?) was 7 t/s. I recommend using an 32k context window, which is enough for most applications you will run with penguin.

## Installing & Quick Start
### One-line install command using pipx:
[pipx](https://github.com/pypa/pipx) is a modern PyPi Installer for CLI applications - like apt but for python. Use it to install the  ```penguin-agent-package``` with a systemwide command  ```penguin-agent-package``` :

```
sudo pipx install penguin-agent-package
```

Then type ```penguin``` in your terminal
### Standard install using pip:
[pip](https://github.com/pypa/pip) is the standard PyPi Installer. Install  ```penguin-agent-package``` using pip in a virtual environment:

```
pip install penguin-agent-package
```


>[!WARNING]
>This will not install the systemwide  ```penguin``` command. You need to add it manually to PATH.

## Features
Penguin is a very, very simple tool:
+ Uses an Ollama backend(see [LLM](#llm))
+ Three basic tools in the agent-loop:
    * execute_bash_command
    * get_memory_entry
    * enter_memory_entry
+ Executes bash commands always at ```~```
+ Uses [prompt_toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit) to manage sessions with history and suggestions
+ Uses memory.json file for managing the agent memory

## Run it
Just type:

```
penguin
```

## How it works
The choice of Ollama is due entirely to its good tool-calling integration in python. Tool schemes are converted by the ollama library to JSON and passed to the native function calling of the model.

## Credits
I heavily used the prompt_toolkit library for the design and the interaction with the tool. Thanks also to the amazing ollama python library that makes it so easy to use LLMs with Python.