agent-mini 0.1.0__tar.gz → 0.2.0__tar.gz

{agent_mini-0.1.0 → agent_mini-0.2.0}/.github/workflows/publish.yml

@@ -26,3 +26,5 @@ jobs:
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

{agent_mini-0.1.0 → agent_mini-0.2.0}/.gitignore

@@ -34,3 +34,5 @@ node_modules/
 config.json
 .pytest_cache/
 .ruff_cache/
+
+archived

{agent_mini-0.1.0 → agent_mini-0.2.0}/CONTRIBUTING.md

@@ -86,8 +86,7 @@ src/agent_mini/
 ├── providers/
 │   ├── base.py         # Provider interface + tool call parsing
 │   ├── ollama.py       # Ollama provider
-│   ├── gemini.py       # Google Gemini provider
-│   ├── github_copilot.py  # GitHub Copilot (OAuth device flow)
+│   ├── openai.py       # OpenAI provider
 │   └── local.py        # Any OpenAI-compatible endpoint
 └── channels/
     ├── base.py         # Channel interface

agent_mini-0.2.0/PKG-INFO

@@ -0,0 +1,331 @@
+Metadata-Version: 2.4
+Name: agent-mini
+Version: 0.2.0
+Summary: Ultra-lightweight personal AI agent — shell, files, web, memory — powered by local or cloud LLMs
+Project-URL: Homepage, https://github.com/mohsinkaleem/agent-mini
+Project-URL: Repository, https://github.com/mohsinkaleem/agent-mini
+Project-URL: Issues, https://github.com/mohsinkaleem/agent-mini/issues
+Author-email: Mohsin Kaleem <mohsin.kaleem512@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,cli,llm,local,ollama,telegram
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.0
+Provides-Extra: all
+Requires-Dist: python-telegram-bot>=21.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: telegram
+Requires-Dist: python-telegram-bot>=21.0; extra == 'telegram'
+Description-Content-Type: text/markdown
+
+# Agent Mini
+
+[![PyPI version](https://img.shields.io/pypi/v/agent-mini)](https://pypi.org/project/agent-mini/)
+[![CI](https://github.com/mohsinkaleem/agent-mini/actions/workflows/ci.yml/badge.svg)](https://github.com/mohsinkaleem/agent-mini/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+A minimal, local-first AI agent you can actually understand and extend.
+
+- **~3,000 lines of Python** — read the whole thing in an afternoon
+- **Local-first** — Ollama as default, OpenAI if you want cloud, or any OpenAI-compatible server
+- **Zero frameworks** — pure `httpx` + `asyncio`, no LangChain, no LiteLLM
+- **Built-in tools** — shell, files, web search, persistent memory
+- **Extensible** — drop a Python file in `~/.agent-mini/plugins/` and it's a tool
+- **Small-model optimized** — token-aware context pruning, tool call repair, model-tier tuning
+
+## Quick Start
+
+```bash
+pip install agent-mini
+agent-mini init
+agent-mini chat
+```
+
+The `init` wizard walks you through picking a provider, model, and basic settings. It creates `~/.agent-mini/config.json` — you're ready to chat.
+
+## Providers
+
+Agent Mini ships with three providers. Set `"provider"` in your config:
+
+### Ollama (default) — Local Models
+
+```bash
+ollama pull llama3.1
+```
+
+```json
+{
+  "provider": "ollama",
+  "providers": {
+    "ollama": {
+      "baseUrl": "http://localhost:11434",
+      "model": "llama3.1",
+      "think": false
+    }
+  }
+}
+```
+
+`think` controls thinking mode — `false`, `true`, or `"low"` / `"medium"` / `"high"`.
+
+### OpenAI
+
+```json
+{
+  "provider": "openai",
+  "providers": {
+    "openai": {
+      "apiKey": "sk-...",
+      "model": "gpt-4o"
+    }
+  }
+}
+```
+
+### Local — Any OpenAI-Compatible Server
+
+Works with LM Studio, vLLM, llama.cpp, text-generation-webui, etc.
+
+```json
+{
+  "provider": "local",
+  "providers": {
+    "local": {
+      "baseUrl": "http://localhost:8080/v1",
+      "apiKey": "no-key",
+      "model": "my-model"
+    }
+  }
+}
+```
+
+All providers support **streaming** and **tool calling**.
+
+---
+
+## Tools
+
+Available out of the box — no API keys needed:
+
+| Tool | Description |
+|------|-------------|
+| `shell_exec` | Run shell commands |
+| `read_file` | Read file contents |
+| `write_file` | Create / overwrite files |
+| `append_file` | Append to files |
+| `code_edit` | Find-and-replace in files |
+| `list_directory` | Browse filesystem |
+| `search_files` | Grep / ripgrep across files |
+| `web_search` | DuckDuckGo search (free, no key) |
+| `web_fetch` | Fetch any URL as plain text |
+| `memory_store` | Save to persistent memory |
+| `memory_recall` | Fuzzy search memory (TF-IDF) |
+
+### Plugins
+
+Extend with custom tools — drop a `.py` file in `~/.agent-mini/plugins/`:
+
+```python
+# ~/.agent-mini/plugins/timestamp.py
+from datetime import datetime, timezone
+
+TOOL_DEF = {
+    "type": "function",
+    "function": {
+        "name": "get_timestamp",
+        "description": "Get the current UTC timestamp.",
+        "parameters": {"type": "object", "properties": {}, "required": []},
+    },
+}
+
+async def handler(arguments: dict) -> str:
+    return datetime.now(timezone.utc).isoformat()
+```
+
+---
+
+## Chat Commands
+
+```
+/clear              Reset conversation
+/model <name>       Switch provider/model (e.g. ollama/llama3.1)
+/tools              List available tools
+/memory [query]     Browse or search memories
+/status             Show config and token usage
+/save [file]        Export conversation as Markdown
+/sessions           List saved sessions
+/load <id>          Resume a session
+/help               Show commands
+```
+
+Multi-line input: wrap with `"""` or `'''`. Line continuation: end with `\`.
+
+---
+
+## Telegram Gateway
+
+1. Create a bot via [@BotFather](https://t.me/BotFather)
+2. Run `agent-mini init` and enable Telegram during setup, or edit config:
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allowFrom": ["YOUR_USER_ID"],
+      "streamResponses": true
+    }
+  }
+}
+```
+
+3. `agent-mini gateway`
+
+---
+
+## Sandbox & Security
+
+Control tool access:
+
+| Level | Description |
+|-------|-------------|
+| `unrestricted` | All tools, all paths |
+| `workspace` | All tools, paths restricted to workspace (default) |
+| `readonly` | Read-only — no shell, write, edit |
+
+```json
+{ "tools": { "sandboxLevel": "readonly" } }
+```
+
+Dangerous shell commands (`rm -rf`, `sudo`, `mkfs`, etc.) are blocked by default.
+
+---
+
+## Sessions
+
+Conversations auto-save after each turn. Resume:
+
+```bash
+agent-mini chat -s 20260307_143022
+```
+
+Or inside the REPL: `/sessions` to list, `/load <id>` to resume.
+
+---
+
+## How It Works
+
+Agent Mini is a **ReAct loop** — the LLM reasons, picks a tool, observes the result, and repeats until it has an answer.
+
+Key design choices for small/local models:
+
+- **Token-aware context** — estimates token usage and prunes old tool results when approaching the model's effective context window
+- **Model tier classification** — auto-detects tiny/small/medium/cloud models and adjusts context budgets, iteration limits, and output caps
+- **Tool call repair** — fixes malformed JSON from small models (trailing commas, single quotes, unquoted keys)
+- **Loop detection** — catches repeated identical tool calls and nudges the LLM to try a different approach
+- **History summarization** — compresses long conversations to stay within context
+
+---
+
+## Configuration Reference
+
+```json
+{
+  "provider": "ollama",
+  "providers": {
+    "ollama": { "baseUrl": "http://localhost:11434", "model": "llama3.1", "think": false },
+    "openai": { "apiKey": "", "model": "gpt-4o" },
+    "local":  { "baseUrl": "http://localhost:8080/v1", "apiKey": "no-key", "model": "local-model" }
+  },
+  "agent": {
+    "maxIterations": 20,
+    "temperature": 0.7,
+    "systemPrompt": ""
+  },
+  "channels": {
+    "telegram": { "enabled": false, "token": "", "allowFrom": [], "streamResponses": true }
+  },
+  "tools": { "restrictToWorkspace": false, "sandboxLevel": "workspace", "blockedCommands": [] },
+  "memory": { "enabled": true, "maxEntries": 1000 },
+  "workspace": "~/.agent-mini/workspace"
+}
+```
+
+Key paths:
+- Config: `~/.agent-mini/config.json`
+- Workspace: `~/.agent-mini/workspace/`
+- Memory: `~/.agent-mini/memory.json`
+- Plugins: `~/.agent-mini/plugins/`
+- Sessions: `~/.agent-mini/sessions/`
+
+---
+
+## CLI
+
+| Command | Description |
+|---------|-------------|
+| `agent-mini init` | Interactive setup wizard |
+| `agent-mini chat` | Interactive chat |
+| `agent-mini chat -m "..."` | Single message |
+| `agent-mini gateway` | Start Telegram bot |
+| `agent-mini status` | Show config status |
+
+---
+
+## Project Structure
+
+```
+src/agent_mini/
+├── cli.py                  # CLI commands (Click)
+├── config.py               # Typed config
+├── bus.py                  # Message routing
+├── sessions.py             # Session persistence
+├── agent/
+│   ├── loop.py             # ReAct agent loop
+│   ├── context.py          # System prompt builder
+│   ├── memory.py           # JSON memory + TF-IDF search
+│   ├── tools.py            # Built-in tools + plugin loader
+│   ├── token_estimator.py  # Token counting + model tiers
+│   └── vision.py           # Image detection + encoding
+├── providers/
+│   ├── base.py             # Provider interface
+│   ├── ollama.py           # Ollama
+│   ├── openai.py           # OpenAI
+│   └── local.py            # OpenAI-compatible
+└── channels/
+    ├── base.py             # Channel interface
+    └── telegram.py         # Telegram bot
+```
+
+## Development
+
+```bash
+git clone https://github.com/mohsinkaleem/agent-mini.git
+cd agent-mini
+uv sync --extra dev
+uv run pytest tests/ -v
+uv run ruff check src/ tests/
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT

agent_mini-0.2.0/README.md

@@ -0,0 +1,296 @@
+# Agent Mini
+
+[![PyPI version](https://img.shields.io/pypi/v/agent-mini)](https://pypi.org/project/agent-mini/)
+[![CI](https://github.com/mohsinkaleem/agent-mini/actions/workflows/ci.yml/badge.svg)](https://github.com/mohsinkaleem/agent-mini/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+A minimal, local-first AI agent you can actually understand and extend.
+
+- **~3,000 lines of Python** — read the whole thing in an afternoon
+- **Local-first** — Ollama as default, OpenAI if you want cloud, or any OpenAI-compatible server
+- **Zero frameworks** — pure `httpx` + `asyncio`, no LangChain, no LiteLLM
+- **Built-in tools** — shell, files, web search, persistent memory
+- **Extensible** — drop a Python file in `~/.agent-mini/plugins/` and it's a tool
+- **Small-model optimized** — token-aware context pruning, tool call repair, model-tier tuning
+
+## Quick Start
+
+```bash
+pip install agent-mini
+agent-mini init
+agent-mini chat
+```
+
+The `init` wizard walks you through picking a provider, model, and basic settings. It creates `~/.agent-mini/config.json` — you're ready to chat.
+
+## Providers
+
+Agent Mini ships with three providers. Set `"provider"` in your config:
+
+### Ollama (default) — Local Models
+
+```bash
+ollama pull llama3.1
+```
+
+```json
+{
+  "provider": "ollama",
+  "providers": {
+    "ollama": {
+      "baseUrl": "http://localhost:11434",
+      "model": "llama3.1",
+      "think": false
+    }
+  }
+}
+```
+
+`think` controls thinking mode — `false`, `true`, or `"low"` / `"medium"` / `"high"`.
+
+### OpenAI
+
+```json
+{
+  "provider": "openai",
+  "providers": {
+    "openai": {
+      "apiKey": "sk-...",
+      "model": "gpt-4o"
+    }
+  }
+}
+```
+
+### Local — Any OpenAI-Compatible Server
+
+Works with LM Studio, vLLM, llama.cpp, text-generation-webui, etc.
+
+```json
+{
+  "provider": "local",
+  "providers": {
+    "local": {
+      "baseUrl": "http://localhost:8080/v1",
+      "apiKey": "no-key",
+      "model": "my-model"
+    }
+  }
+}
+```
+
+All providers support **streaming** and **tool calling**.
+
+---
+
+## Tools
+
+Available out of the box — no API keys needed:
+
+| Tool | Description |
+|------|-------------|
+| `shell_exec` | Run shell commands |
+| `read_file` | Read file contents |
+| `write_file` | Create / overwrite files |
+| `append_file` | Append to files |
+| `code_edit` | Find-and-replace in files |
+| `list_directory` | Browse filesystem |
+| `search_files` | Grep / ripgrep across files |
+| `web_search` | DuckDuckGo search (free, no key) |
+| `web_fetch` | Fetch any URL as plain text |
+| `memory_store` | Save to persistent memory |
+| `memory_recall` | Fuzzy search memory (TF-IDF) |
+
+### Plugins
+
+Extend with custom tools — drop a `.py` file in `~/.agent-mini/plugins/`:
+
+```python
+# ~/.agent-mini/plugins/timestamp.py
+from datetime import datetime, timezone
+
+TOOL_DEF = {
+    "type": "function",
+    "function": {
+        "name": "get_timestamp",
+        "description": "Get the current UTC timestamp.",
+        "parameters": {"type": "object", "properties": {}, "required": []},
+    },
+}
+
+async def handler(arguments: dict) -> str:
+    return datetime.now(timezone.utc).isoformat()
+```
+
+---
+
+## Chat Commands
+
+```
+/clear              Reset conversation
+/model <name>       Switch provider/model (e.g. ollama/llama3.1)
+/tools              List available tools
+/memory [query]     Browse or search memories
+/status             Show config and token usage
+/save [file]        Export conversation as Markdown
+/sessions           List saved sessions
+/load <id>          Resume a session
+/help               Show commands
+```
+
+Multi-line input: wrap with `"""` or `'''`. Line continuation: end with `\`.
+
+---
+
+## Telegram Gateway
+
+1. Create a bot via [@BotFather](https://t.me/BotFather)
+2. Run `agent-mini init` and enable Telegram during setup, or edit config:
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allowFrom": ["YOUR_USER_ID"],
+      "streamResponses": true
+    }
+  }
+}
+```
+
+3. `agent-mini gateway`
+
+---
+
+## Sandbox & Security
+
+Control tool access:
+
+| Level | Description |
+|-------|-------------|
+| `unrestricted` | All tools, all paths |
+| `workspace` | All tools, paths restricted to workspace (default) |
+| `readonly` | Read-only — no shell, write, edit |
+
+```json
+{ "tools": { "sandboxLevel": "readonly" } }
+```
+
+Dangerous shell commands (`rm -rf`, `sudo`, `mkfs`, etc.) are blocked by default.
+
+---
+
+## Sessions
+
+Conversations auto-save after each turn. Resume:
+
+```bash
+agent-mini chat -s 20260307_143022
+```
+
+Or inside the REPL: `/sessions` to list, `/load <id>` to resume.
+
+---
+
+## How It Works
+
+Agent Mini is a **ReAct loop** — the LLM reasons, picks a tool, observes the result, and repeats until it has an answer.
+
+Key design choices for small/local models:
+
+- **Token-aware context** — estimates token usage and prunes old tool results when approaching the model's effective context window
+- **Model tier classification** — auto-detects tiny/small/medium/cloud models and adjusts context budgets, iteration limits, and output caps
+- **Tool call repair** — fixes malformed JSON from small models (trailing commas, single quotes, unquoted keys)
+- **Loop detection** — catches repeated identical tool calls and nudges the LLM to try a different approach
+- **History summarization** — compresses long conversations to stay within context
+
+---
+
+## Configuration Reference
+
+```json
+{
+  "provider": "ollama",
+  "providers": {
+    "ollama": { "baseUrl": "http://localhost:11434", "model": "llama3.1", "think": false },
+    "openai": { "apiKey": "", "model": "gpt-4o" },
+    "local":  { "baseUrl": "http://localhost:8080/v1", "apiKey": "no-key", "model": "local-model" }
+  },
+  "agent": {
+    "maxIterations": 20,
+    "temperature": 0.7,
+    "systemPrompt": ""
+  },
+  "channels": {
+    "telegram": { "enabled": false, "token": "", "allowFrom": [], "streamResponses": true }
+  },
+  "tools": { "restrictToWorkspace": false, "sandboxLevel": "workspace", "blockedCommands": [] },
+  "memory": { "enabled": true, "maxEntries": 1000 },
+  "workspace": "~/.agent-mini/workspace"
+}
+```
+
+Key paths:
+- Config: `~/.agent-mini/config.json`
+- Workspace: `~/.agent-mini/workspace/`
+- Memory: `~/.agent-mini/memory.json`
+- Plugins: `~/.agent-mini/plugins/`
+- Sessions: `~/.agent-mini/sessions/`
+
+---
+
+## CLI
+
+| Command | Description |
+|---------|-------------|
+| `agent-mini init` | Interactive setup wizard |
+| `agent-mini chat` | Interactive chat |
+| `agent-mini chat -m "..."` | Single message |
+| `agent-mini gateway` | Start Telegram bot |
+| `agent-mini status` | Show config status |
+
+---
+
+## Project Structure
+
+```
+src/agent_mini/
+├── cli.py                  # CLI commands (Click)
+├── config.py               # Typed config
+├── bus.py                  # Message routing
+├── sessions.py             # Session persistence
+├── agent/
+│   ├── loop.py             # ReAct agent loop
+│   ├── context.py          # System prompt builder
+│   ├── memory.py           # JSON memory + TF-IDF search
+│   ├── tools.py            # Built-in tools + plugin loader
+│   ├── token_estimator.py  # Token counting + model tiers
+│   └── vision.py           # Image detection + encoding
+├── providers/
+│   ├── base.py             # Provider interface
+│   ├── ollama.py           # Ollama
+│   ├── openai.py           # OpenAI
+│   └── local.py            # OpenAI-compatible
+└── channels/
+    ├── base.py             # Channel interface
+    └── telegram.py         # Telegram bot
+```
+
+## Development
+
+```bash
+git clone https://github.com/mohsinkaleem/agent-mini.git
+cd agent-mini
+uv sync --extra dev
+uv run pytest tests/ -v
+uv run ruff check src/ tests/
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT

agent_mini-0.2.0/SECURITY.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.1.x   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it responsibly:
+
+1. **Do not** open a public issue.
+2. Email **mohsin.kaleem512@gmail.com** with details of the vulnerability.
+3. Include steps to reproduce if possible.
+
+You should receive a response within 48 hours. We'll work with you to understand the issue and coordinate a fix before any public disclosure.
+
+## Security Considerations
+
+Agent Mini executes shell commands and file operations on behalf of the user. The built-in sandbox levels (`unrestricted`, `workspace`, `readonly`) control access:
+
+- **Always use `workspace` or `readonly` mode** in shared or untrusted environments.
+- **Never expose the agent to untrusted input** without enabling `restrictToWorkspace`.
+- Dangerous commands (`rm -rf /`, `sudo`, `mkfs`, etc.) are blocked by default.
+- API keys are stored in `~/.agent-mini/config.json` — ensure this file has appropriate permissions (`chmod 600`).

{agent_mini-0.1.0 → agent_mini-0.2.0}/config.example.json

@@ -6,12 +6,8 @@
       "model": "llama3.1",
       "think": false
     },
-    "gemini": {
+    "openai": {
       "apiKey": "",
-      "model": "gemini-2.0-flash"
-    },
-    "github_copilot": {
-      "token": "",
       "model": "gpt-4o"
     },
     "local": {