agens 0.1.0__tar.gz

agens-0.1.0/.dockerignore

@@ -0,0 +1,36 @@
+.git
+.agents
+.codex
+.venv
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+wheels/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+.env
+*.local
+logs/
+data/
+app.db
+
+frontend/node_modules/
+frontend/dist/
+frontend/dist-ssr/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+.DS_Store
+.idea/
+.vscode/
+todos/
+test.py
+example.py

agens-0.1.0/Dockerfile

@@ -0,0 +1,51 @@
+# syntax=docker/dockerfile:1.7
+
+FROM node:24-bookworm-slim AS frontend-builder
+WORKDIR /app/frontend
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm ci
+COPY frontend/ ./
+RUN npm run build
+
+FROM python:3.13-slim AS wheel-builder
+ENV PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+WORKDIR /app
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends build-essential \
+    && rm -rf /var/lib/apt/lists/*
+COPY pyproject.toml MANIFEST.in README.md ./
+COPY src/ ./src/
+COPY --from=frontend-builder /app/src/interfaces/web/dist ./src/interfaces/web/dist
+RUN pip wheel --wheel-dir /wheels .
+
+FROM python:3.13-slim AS runtime
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PRODUCTION=true \
+    WEB_HOST=0.0.0.0 \
+    WEB_PORT=8000 \
+    XDG_CONFIG_HOME=/data/config \
+    DATABASE_URL=sqlite+aiosqlite:////data/db/agens.db \
+    WORKSPACE_ROOT=/workspace
+
+RUN groupadd --system --gid 10001 agens \
+    && useradd --system --uid 10001 --gid agens --home-dir /home/agens --create-home agens \
+    && mkdir -p /data/config /data/db /data/memories /data/runtime /workspace \
+    && chown -R agens:agens /data /workspace /home/agens
+
+WORKDIR /app
+COPY --from=wheel-builder /wheels /wheels
+RUN pip install --no-index --find-links=/wheels agens \
+    && rm -rf /wheels
+
+USER agens
+EXPOSE 8000
+VOLUME ["/data/config", "/data/db", "/data/memories", "/data/runtime", "/workspace"]
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+    CMD python -c "from urllib.request import urlopen; urlopen('http://127.0.0.1:8000/health', timeout=3).read()" || exit 1
+
+CMD ["agens", "_run-interfaces", "web"]

agens-0.1.0/Dockerfile.dev

@@ -0,0 +1,41 @@
+# syntax=docker/dockerfile:1.7
+
+FROM python:3.13-slim AS dev
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PRODUCTION=false \
+    WEB_HOST=0.0.0.0 \
+    WEB_PORT=8000 \
+    FRONTEND_LINK=http://localhost:5173 \
+    XDG_CONFIG_HOME=/data/config \
+    DATABASE_URL=sqlite+aiosqlite:////data/db/agens.db \
+    WORKSPACE_ROOT=/workspace
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends curl ca-certificates nodejs npm build-essential \
+    && rm -rf /var/lib/apt/lists/* \
+    && groupadd --system --gid 10001 agens \
+    && useradd --system --uid 10001 --gid agens --home-dir /home/agens --create-home agens \
+    && mkdir -p /app /data/config /data/db /data/memories /data/runtime /workspace \
+    && chown -R agens:agens /app /data /workspace /home/agens
+
+WORKDIR /app
+COPY pyproject.toml MANIFEST.in README.md ./
+COPY src/ ./src/
+RUN pip install -e .
+
+WORKDIR /app/frontend
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm ci
+
+WORKDIR /app
+COPY frontend/ ./frontend/
+
+USER agens
+EXPOSE 8000 5173
+VOLUME ["/data/config", "/data/db", "/data/memories", "/data/runtime", "/workspace"]
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+    CMD python -c "from urllib.request import urlopen; urlopen('http://127.0.0.1:8000/health', timeout=3).read()" || exit 1
+
+CMD ["sh", "-c", "cd /app/frontend && npm run dev -- --host 0.0.0.0 & cd /app && agens _run-interfaces web"]

agens-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kayesFerdous
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agens-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include Dockerfile Dockerfile.dev docker-compose.yml .dockerignore
+graft docs
+graft scripts
+graft src
+prune src/**/__pycache__
+global-exclude __pycache__/*
+global-exclude *.py[cod]

agens-0.1.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: agens
+Version: 0.1.0
+Summary: An interface-agnostic AI agent platform that executes complex system-level and web tasks through a centralized ReAct orchestration engine.
+Author: kayesFerdous
+License: MIT License
+        
+        Copyright (c) 2026 kayesFerdous
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/kayesFerdous/agens
+Project-URL: Repository, https://github.com/kayesFerdous/agens.git
+Project-URL: Bug Tracker, https://github.com/kayesFerdous/agens/issues
+Project-URL: Documentation, https://github.com/kayesFerdous/agens#readme
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: alembic>=1.13.0
+Requires-Dist: beautifulsoup4>=4.14.3
+Requires-Dist: cryptography>=46.0.5
+Requires-Dist: ddgs>=9.14.4
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: markdown>=3.10.2
+Requires-Dist: openai>=2.37.0
+Requires-Dist: platformdirs>=4.9.6
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pydantic-settings>=2.13.1
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: python-telegram-bot>=22.7
+Requires-Dist: sqlalchemy[asyncio]>=2.0.48
+Requires-Dist: textual>=0.60.0
+Requires-Dist: typer>=0.25.1
+Requires-Dist: uvicorn[standard]>=0.34.0
+Provides-Extra: dev
+Requires-Dist: black>=24.0.0; extra == "dev"
+Requires-Dist: ruff>=0.3.0; extra == "dev"
+Requires-Dist: mypy>=1.9.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Requires-Dist: validate-pyproject>=0.16; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+<img src="frontend/src/assets/logo.svg" alt="Agens Logo" width="180" />
+
+# Agens
+
+**An interface-agnostic AI agent platform that executes complex system-level and web tasks through a centralized ReAct orchestration engine.**
+
+[![PyPI](https://img.shields.io/badge/pypi-placeholder-blue?style=flat-square&logo=pypi&logoColor=white)](https://pypi.org/project/agens/)
+[![Python](https://img.shields.io/badge/python-%3E%3D3.13-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square)](./LICENSE)
+[![Interfaces](https://img.shields.io/badge/interfaces-CLI%20%7C%20TUI%20%7C%20Web%20%7C%20Telegram-f97316?style=flat-square)](#interface-overview)
+
+</div>
+
+<div align="center">
+  <img src="assets/demo.gif" alt="Agens Multi-Tool Live Demo" width="700" style="border-radius: 8px; box-shadow: 0 4px 20px rgba(0,0,0,0.2); margin: 20px 0;" />
+</div>
+
+---
+
+Agens decouples stateful AI reasoning from delivery channels. A centralized agent engine (`agent.py`) coordinates session histories, tool execution routing, and provider-fallback logic — exposing a unified interface to thin transport-layer adapters. All client interfaces share the same SQLite database, memory, and configuration with zero context drift.
+
+> **Agens is completely free to use.** The platform itself costs nothing — you only need a personal API key from any supported provider (Gemini, OpenAI, Groq, Cerebras, SiliconFlow, DeepSeek).
+
+---
+
+## Why Agens?
+
+*   🧠 **Centralized Intelligence**: Decoupled Ports & Adapters (Hexagonal) architecture. All client interfaces share a single database, settings, and memories with zero context drift.
+*   🔒 **Zero-Trust Key Security**: API keys are Fernet-encrypted at rest and decrypted purely in-memory. They are never saved in plaintext configuration files.
+*   🔄 **Automatic Rate-Limit Cooldown**: Transparent key rotation and failover. If an API key hits a `429 Rate Limit`, Agens automatically shifts to the next available key and retries the request seamlessly.
+*   🌐 **Free Native Tools**: Built-in DuckDuckGo web search and HTML page retrieval — zero external paid search API subscriptions required.
+*   🛡️ **Layered Safety Controls**: Built-in Safety Mode gates dangerous subprocess executions, while local Textual TUI collects `sudo` credentials securely on-the-fly.
+
+---
+
+## 📚 Documentation Hub
+
+Explore the detailed technical manuals and operational guides:
+
+*   🚀 **[Installation & Setup](docs/installation.md)**: Native and containerized setups across Linux, macOS, and Windows.
+*   🏗️ **[Architecture Deep Dive](docs/architecture.md)**: Learn about the Hexagonal Ports & Adapters layout, the ReAct stream loop, and key database connection designs.
+*   🛠️ **[Tool System & Custom Tools](docs/tools.md)**: Explore the core tool directory, layered safety rules, and step-by-step custom tool development tutorials.
+*   ⚙️ **[Configuration & Key Management](docs/configuration.md)**: Deep dive into environments, user memory settings, encrypted API credentials, and automatic rate-limit cooldown algorithms.
+*   💻 **[Developer & Contributor Manual](docs/development.md)**: Workspace setup guides, release packaging commands, custom interface implementation, and open-source contribution rules.
+
+---
+
+## Quick Start
+
+### 1. Install Agens
+```bash
+pipx install agens
+```
+
+### 2. Register an API Key
+```bash
+# agens apikey add <label> <provider> <api_key> 
+agens apikey add my-gemini gemini AIzaSyB...
+```
+
+### 3. Launch an Interface
+```bash
+agens web                                              # Web UI (Svelte 5) → http://localhost:8000
+agens tui                                             # Terminal UI Dashboard (Textual)
+agens chat "List the contents of my workspace"        # Single-line Typer CLI query
+```
+
+---
+
+## Interface Overview
+
+All interface adapters communicate with the exact same central brain and write to the same database. Prompt behavior and safety policies dynamically adjust depending on the interface:
+
+| Interface | Launch Command | Core Capabilities | Concurrency Model |
+| :--- | :--- | :--- | :--- |
+| **CLI** | `agens chat "<msg>"` | One-shot queries, API key administration, safety overrides | Ephemeral process; runs one ReAct loop and exits |
+| **Terminal UI (TUI)** | `agens tui [--session <id>]` | **Full feature parity with Web UI** (session handling, dynamic API key administration, provider model selection, granular tool group toggles) + secure local `sudo` password collection | Stateful Textual app; blocks terminal during execution |
+| **Web UI** | `agens web` | Svelte 5 + FastAPI SPA with SSE streaming, interactive model picker, encrypted key management, granular tool settings & status blocks | Client-server; tokens stream live via Server-Sent Events |
+| **Telegram Bot** | `agens telegram` | Remote message-based assistant via `python-telegram-bot`, polling + webhooks | Long-polling or webhook updater; edits messages sequentially to stay within Telegram rate limits |
+
+---
+
+## 🎨 Visual Showcase
+
+Experience Agens' premium, interface-agnostic design with absolute feature parity:
+
+### 🌐 Web UI Dashboard (`agens web`)
+The modern Web UI features real-time SSE streaming, interactive model selection, active key management, and fine-grained tool settings.
+
+<div align="center">
+  <table border="0">
+    <tr>
+      <td width="50%" align="center">
+        <b>Workspace Chat</b><br/>
+        <img src="assets/web-home.png" alt="Web UI Home" width="100%" style="border-radius: 8px; box-shadow: 0 4px 15px rgba(0,0,0,0.15);" />
+      </td>
+      <td width="50%" align="center">
+        <b>Streaming Message with Tool Output</b><br/>
+        <img src="assets/web-message.png" alt="Web Streaming & Tool Execution" width="100%" style="border-radius: 8px; box-shadow: 0 4px 15px rgba(0,0,0,0.15);" />
+      </td>
+    </tr>
+    <tr>
+      <td width="50%" align="center">
+        <b>Decoupled Provider Model Selection</b><br/>
+        <img src="assets/web-model-selection.png" alt="Interactive Model Selector" width="100%" style="border-radius: 8px; box-shadow: 0 4px 15px rgba(0,0,0,0.15);" />
+      </td>
+      <td width="50%" align="center">
+        <b>Granular Tool Control Panel</b><br/>
+        <img src="assets/web-tool-group.png" alt="Tool Permissions Dashboard" width="100%" style="border-radius: 8px; box-shadow: 0 4px 15px rgba(0,0,0,0.15);" />
+      </td>
+    </tr>
+  </table>
+</div>
+
+### 💻 Terminal UI (TUI) Dashboard (`agens tui`)
+For developers working in terminal or remote SSH environments, the Textual-powered TUI provides **absolute feature parity with the Web UI**. It supports the complete suite of administration controls (adding/managing Fernet-encrypted API keys, selecting providers and fallback models, toggling granular tool group permissions, and safety controls) alongside dynamic tool status animations and secure local `sudo` handling.
+
+<div align="center">
+  <table border="0">
+    <tr>
+      <td width="50%" align="center">
+        <b>Interactive TUI Home Dashboard</b><br/>
+        <img src="assets/tui-home.png" alt="TUI Dashboard" width="100%" style="border-radius: 8px; box-shadow: 0 4px 15px rgba(0,0,0,0.15);" />
+      </td>
+      <td width="50%" align="center">
+        <b>Stateful TUI Chat Session</b><br/>
+        <img src="assets/tui-message.png" alt="TUI Conversation" width="100%" style="border-radius: 8px; box-shadow: 0 4px 15px rgba(0,0,0,0.15);" />
+      </td>
+    </tr>
+  </table>
+</div>
+
+---
+
+## Architecture Diagram
+
+```mermaid
+graph TD
+    Input["User Input<br/>(Web · TUI · Telegram · CLI)"]
+    Adapter["Interface Adapter<br/>src/interfaces/"]
+    Agent["Agent Orchestrator<br/>src/agent/agent.py"]
+    DB[("Local SQLite<br/>src/db/")]
+    PromptBuilder["Prompt Builder<br/>src/planner/prompt_builder.py"]
+    LLMClient["LLM Client & Router<br/>src/llm/"]
+    ToolRegistry["Tool Registry<br/>src/core/registry.py"]
+    Tools["Tool Execution<br/>src/tools/"]
+
+    Input -->|triggers| Adapter
+    Adapter -->|".chat(message, session_id, channel)"| Agent
+    Agent -->|loads session history| DB
+    Agent -->|requests system prompt| PromptBuilder
+    PromptBuilder -->|reads settings & memories| DB
+    Agent -->|invokes ReAct loop| LLMClient
+    LLMClient -->|"chunks / tool_calls"| Agent
+    Agent -->|routes tool call| ToolRegistry
+    ToolRegistry -->|executes| Tools
+    Tools -->|returns result dict| Agent
+    Agent -->|"yields StreamEvent"| Adapter
+    Adapter -->|renders live output| Input
+```
+
+---
+
+## License
+
+Agens is distributed under the [MIT License](LICENSE).

agens-0.1.0/README.md

@@ -0,0 +1,168 @@
+<div align="center">
+
+<img src="frontend/src/assets/logo.svg" alt="Agens Logo" width="180" />
+
+# Agens
+
+**An interface-agnostic AI agent platform that executes complex system-level and web tasks through a centralized ReAct orchestration engine.**
+
+[![PyPI](https://img.shields.io/badge/pypi-placeholder-blue?style=flat-square&logo=pypi&logoColor=white)](https://pypi.org/project/agens/)
+[![Python](https://img.shields.io/badge/python-%3E%3D3.13-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square)](./LICENSE)
+[![Interfaces](https://img.shields.io/badge/interfaces-CLI%20%7C%20TUI%20%7C%20Web%20%7C%20Telegram-f97316?style=flat-square)](#interface-overview)
+
+</div>
+
+<div align="center">
+  <img src="assets/demo.gif" alt="Agens Multi-Tool Live Demo" width="700" style="border-radius: 8px; box-shadow: 0 4px 20px rgba(0,0,0,0.2); margin: 20px 0;" />
+</div>
+
+---
+
+Agens decouples stateful AI reasoning from delivery channels. A centralized agent engine (`agent.py`) coordinates session histories, tool execution routing, and provider-fallback logic — exposing a unified interface to thin transport-layer adapters. All client interfaces share the same SQLite database, memory, and configuration with zero context drift.
+
+> **Agens is completely free to use.** The platform itself costs nothing — you only need a personal API key from any supported provider (Gemini, OpenAI, Groq, Cerebras, SiliconFlow, DeepSeek).
+
+---
+
+## Why Agens?
+
+*   🧠 **Centralized Intelligence**: Decoupled Ports & Adapters (Hexagonal) architecture. All client interfaces share a single database, settings, and memories with zero context drift.
+*   🔒 **Zero-Trust Key Security**: API keys are Fernet-encrypted at rest and decrypted purely in-memory. They are never saved in plaintext configuration files.
+*   🔄 **Automatic Rate-Limit Cooldown**: Transparent key rotation and failover. If an API key hits a `429 Rate Limit`, Agens automatically shifts to the next available key and retries the request seamlessly.
+*   🌐 **Free Native Tools**: Built-in DuckDuckGo web search and HTML page retrieval — zero external paid search API subscriptions required.
+*   🛡️ **Layered Safety Controls**: Built-in Safety Mode gates dangerous subprocess executions, while local Textual TUI collects `sudo` credentials securely on-the-fly.
+
+---
+
+## 📚 Documentation Hub
+
+Explore the detailed technical manuals and operational guides:
+
+*   🚀 **[Installation & Setup](docs/installation.md)**: Native and containerized setups across Linux, macOS, and Windows.
+*   🏗️ **[Architecture Deep Dive](docs/architecture.md)**: Learn about the Hexagonal Ports & Adapters layout, the ReAct stream loop, and key database connection designs.
+*   🛠️ **[Tool System & Custom Tools](docs/tools.md)**: Explore the core tool directory, layered safety rules, and step-by-step custom tool development tutorials.
+*   ⚙️ **[Configuration & Key Management](docs/configuration.md)**: Deep dive into environments, user memory settings, encrypted API credentials, and automatic rate-limit cooldown algorithms.
+*   💻 **[Developer & Contributor Manual](docs/development.md)**: Workspace setup guides, release packaging commands, custom interface implementation, and open-source contribution rules.
+
+---
+
+## Quick Start
+
+### 1. Install Agens
+```bash
+pipx install agens
+```
+
+### 2. Register an API Key
+```bash
+# agens apikey add <label> <provider> <api_key> 
+agens apikey add my-gemini gemini AIzaSyB...
+```
+
+### 3. Launch an Interface
+```bash
+agens web                                              # Web UI (Svelte 5) → http://localhost:8000
+agens tui                                             # Terminal UI Dashboard (Textual)
+agens chat "List the contents of my workspace"        # Single-line Typer CLI query
+```
+
+---
+
+## Interface Overview
+
+All interface adapters communicate with the exact same central brain and write to the same database. Prompt behavior and safety policies dynamically adjust depending on the interface:
+
+| Interface | Launch Command | Core Capabilities | Concurrency Model |
+| :--- | :--- | :--- | :--- |
+| **CLI** | `agens chat "<msg>"` | One-shot queries, API key administration, safety overrides | Ephemeral process; runs one ReAct loop and exits |
+| **Terminal UI (TUI)** | `agens tui [--session <id>]` | **Full feature parity with Web UI** (session handling, dynamic API key administration, provider model selection, granular tool group toggles) + secure local `sudo` password collection | Stateful Textual app; blocks terminal during execution |
+| **Web UI** | `agens web` | Svelte 5 + FastAPI SPA with SSE streaming, interactive model picker, encrypted key management, granular tool settings & status blocks | Client-server; tokens stream live via Server-Sent Events |
+| **Telegram Bot** | `agens telegram` | Remote message-based assistant via `python-telegram-bot`, polling + webhooks | Long-polling or webhook updater; edits messages sequentially to stay within Telegram rate limits |
+
+---
+
+## 🎨 Visual Showcase
+
+Experience Agens' premium, interface-agnostic design with absolute feature parity:
+
+### 🌐 Web UI Dashboard (`agens web`)
+The modern Web UI features real-time SSE streaming, interactive model selection, active key management, and fine-grained tool settings.
+
+<div align="center">
+  <table border="0">
+    <tr>
+      <td width="50%" align="center">
+        <b>Workspace Chat</b><br/>
+        <img src="assets/web-home.png" alt="Web UI Home" width="100%" style="border-radius: 8px; box-shadow: 0 4px 15px rgba(0,0,0,0.15);" />
+      </td>
+      <td width="50%" align="center">
+        <b>Streaming Message with Tool Output</b><br/>
+        <img src="assets/web-message.png" alt="Web Streaming & Tool Execution" width="100%" style="border-radius: 8px; box-shadow: 0 4px 15px rgba(0,0,0,0.15);" />
+      </td>
+    </tr>
+    <tr>
+      <td width="50%" align="center">
+        <b>Decoupled Provider Model Selection</b><br/>
+        <img src="assets/web-model-selection.png" alt="Interactive Model Selector" width="100%" style="border-radius: 8px; box-shadow: 0 4px 15px rgba(0,0,0,0.15);" />
+      </td>
+      <td width="50%" align="center">
+        <b>Granular Tool Control Panel</b><br/>
+        <img src="assets/web-tool-group.png" alt="Tool Permissions Dashboard" width="100%" style="border-radius: 8px; box-shadow: 0 4px 15px rgba(0,0,0,0.15);" />
+      </td>
+    </tr>
+  </table>
+</div>
+
+### 💻 Terminal UI (TUI) Dashboard (`agens tui`)
+For developers working in terminal or remote SSH environments, the Textual-powered TUI provides **absolute feature parity with the Web UI**. It supports the complete suite of administration controls (adding/managing Fernet-encrypted API keys, selecting providers and fallback models, toggling granular tool group permissions, and safety controls) alongside dynamic tool status animations and secure local `sudo` handling.
+
+<div align="center">
+  <table border="0">
+    <tr>
+      <td width="50%" align="center">
+        <b>Interactive TUI Home Dashboard</b><br/>
+        <img src="assets/tui-home.png" alt="TUI Dashboard" width="100%" style="border-radius: 8px; box-shadow: 0 4px 15px rgba(0,0,0,0.15);" />
+      </td>
+      <td width="50%" align="center">
+        <b>Stateful TUI Chat Session</b><br/>
+        <img src="assets/tui-message.png" alt="TUI Conversation" width="100%" style="border-radius: 8px; box-shadow: 0 4px 15px rgba(0,0,0,0.15);" />
+      </td>
+    </tr>
+  </table>
+</div>
+
+---
+
+## Architecture Diagram
+
+```mermaid
+graph TD
+    Input["User Input<br/>(Web · TUI · Telegram · CLI)"]
+    Adapter["Interface Adapter<br/>src/interfaces/"]
+    Agent["Agent Orchestrator<br/>src/agent/agent.py"]
+    DB[("Local SQLite<br/>src/db/")]
+    PromptBuilder["Prompt Builder<br/>src/planner/prompt_builder.py"]
+    LLMClient["LLM Client & Router<br/>src/llm/"]
+    ToolRegistry["Tool Registry<br/>src/core/registry.py"]
+    Tools["Tool Execution<br/>src/tools/"]
+
+    Input -->|triggers| Adapter
+    Adapter -->|".chat(message, session_id, channel)"| Agent
+    Agent -->|loads session history| DB
+    Agent -->|requests system prompt| PromptBuilder
+    PromptBuilder -->|reads settings & memories| DB
+    Agent -->|invokes ReAct loop| LLMClient
+    LLMClient -->|"chunks / tool_calls"| Agent
+    Agent -->|routes tool call| ToolRegistry
+    ToolRegistry -->|executes| Tools
+    Tools -->|returns result dict| Agent
+    Agent -->|"yields StreamEvent"| Adapter
+    Adapter -->|renders live output| Input
+```
+
+---
+
+## License
+
+Agens is distributed under the [MIT License](LICENSE).

agens-0.1.0/docker-compose.yml

@@ -0,0 +1,89 @@
+services:
+  agens:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: agens:latest
+    restart: unless-stopped
+    ports:
+      - "${AGENS_WEB_PORT:-8000}:8000"
+    environment:
+      PRODUCTION: "true"
+      WEB_HOST: "0.0.0.0"
+      WEB_PORT: "8000"
+      XDG_CONFIG_HOME: "/data/config"
+      DATABASE_URL: "sqlite+aiosqlite:////data/db/agens.db"
+      WORKSPACE_ROOT: "/workspace"
+      AGENS_ENV_FILE: "${AGENS_ENV_FILE:-}"
+      DEFAULT_PROVIDER: "${DEFAULT_PROVIDER:-gemini}"
+      DEFAULT_MODEL: "${DEFAULT_MODEL:-gemini-2.5-flash-lite}"
+    volumes:
+      - agens_config:/data/config
+      - agens_database:/data/db
+      - agens_memories:/data/memories
+      - agens_runtime:/data/runtime
+      - agens_workspace:/workspace
+    healthcheck:
+      test:
+        [
+          "CMD",
+          "python",
+          "-c",
+          "from urllib.request import urlopen; urlopen('http://127.0.0.1:8000/health', timeout=3).read()",
+        ]
+      interval: 30s
+      timeout: 5s
+      start_period: 20s
+      retries: 3
+
+  agens-dev:
+    profiles: ["dev"]
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    image: agens:dev
+    command:
+      [
+        "sh",
+        "-c",
+        "cd /app/frontend && npm run dev -- --host 0.0.0.0 & cd /app && agens _run-interfaces web",
+      ]
+    ports:
+      - "${AGENS_WEB_PORT:-8000}:8000"
+      - "${AGENS_FRONTEND_PORT:-5173}:5173"
+    environment:
+      PRODUCTION: "false"
+      WEB_HOST: "0.0.0.0"
+      WEB_PORT: "8000"
+      FRONTEND_LINK: "http://localhost:5173"
+      XDG_CONFIG_HOME: "/data/config"
+      DATABASE_URL: "sqlite+aiosqlite:////data/db/agens.db"
+      WORKSPACE_ROOT: "/workspace"
+    volumes:
+      - .:/app
+      - /app/.venv
+      - /app/frontend/node_modules
+      - agens_config:/data/config
+      - agens_database:/data/db
+      - agens_memories:/data/memories
+      - agens_runtime:/data/runtime
+      - agens_workspace:/workspace
+    healthcheck:
+      test:
+        [
+          "CMD",
+          "python",
+          "-c",
+          "from urllib.request import urlopen; urlopen('http://127.0.0.1:8000/health', timeout=3).read()",
+        ]
+      interval: 30s
+      timeout: 5s
+      start_period: 20s
+      retries: 3
+
+volumes:
+  agens_config:
+  agens_database:
+  agens_memories:
+  agens_runtime:
+  agens_workspace: