agyqueue 0.1.0__py3-none-any.whl

agyqueue-0.1.0.dist-info/METADATA

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: agyqueue
+Version: 0.1.0
+Summary: A pluggable, non-blocking asynchronous task queue and MCP server for AI Agents
+Author: Jitendra Gupta
+License: Apache-2.0
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: redis>=5.0.0
+Requires-Dist: starlette>=0.30.0
+Requires-Dist: uvicorn>=0.20.0
+Requires-Dist: psycopg2-binary>=2.9.0
+
+# AgyQueue: Non-Blocking Asynchronous Task Execution for AI Agents
+
+![Run on Google Cloud](https://deploy.cloud.run/button.svg)
+
+AgyQueue is a lightweight, non-blocking asynchronous task execution framework built for AI agents. It allows agents to offload long-running operations—such as code generation, compilation, testing, and validation—to background workers while keeping client conversation threads responsive.
+
+---
+
+## 🚀 Core Capabilities
+
+1. **Asynchronous Task Offloading**: Agents submit tasks via MCP tool calls or REST API requests and immediately receive a `task_id`, returning execution control back to the user chat session.
+2. **Resilience & Reconnection**: Task status is saved in a persistent database store, allowing clients to query progress or fetch final outputs even after network drops or worker crashes.
+3. **Interactive Console UI**: Built-in dark mode dashboard that visualizes enqueued runs, progress bars, vertical event history timelines (e.g. `WorkflowExecutionStarted`, `WorkflowTaskScheduled`), and aggregated markdown reports.
+4. **Well-Architected Architecture**:
+   * **Threaded Connection Pooling**: Uses `ThreadedConnectionPool` for PostgreSQL backend tasks, preventing socket exhaust under high concurrent query volumes.
+   * **Graceful Shutdown**: Catches `SIGTERM` / `SIGINT` signals, allowing workers to finish their active task run cleanly before eviction.
+   * **Workspace Isolation**: Spawns copy-on-write scratch worktree folders for subprocess executions, ensuring zero file-system cross-interference.
+5. **Configurable Multi-Channel Notifications**: Real-time push notifications over Slack webhook and SMTP Email when tasks hit terminal states.
+6. **Model Context Protocol (MCP) Support**: Serves as a standard stdio/sse MCP server compatible with Cursor, Claude Desktop, Claude Code, and Copilot CLI.
+
+---
+
+## 🛠️ Architecture
+
+AgyQueue supports both hybrid cloud-agnostic execution flows and fully-managed Google Cloud configurations:
+
+### 1. Cloud-Agnostic Core Flow
+![AgyQueue Cloud-Agnostic Architecture](agyqueue_architecture.jpg)
+
+### 2. Google Cloud Native Production Deployment
+![AgyQueue GCP System Architecture](agyqueue_gcp_architecture.jpg)
+
+### Google Cloud & Google AI Managed Services Mapping
+
+When migrating from local development/fallback to production cloud scaling, AgyQueue integrates natively with Google Cloud managed services:
+
+| Component | Dev Fallback | Production GCP Service |
+| :--- | :--- | :--- |
+| **Agent Reasoning Core** | Local LLM | **Vertex AI Gemini API** (Gemini 2.5 Flash / Pro) |
+| **API Server Compute** | Local Python Process | **Google Cloud Run** (Event-driven serverless container) |
+| **Worker Node Compute** | Local Daemon Process | **Google Kubernetes Engine (GKE)** or **Cloud Run Jobs** |
+| **Task Message Broker** | SQLite (FIFO Table) | **Google Cloud Pub/Sub** or **Cloud Memorystore for Redis** |
+| **Persistent Task Store** | SQLite Database | **Google Cloud SQL for PostgreSQL** or **Cloud Spanner** |
+| **Workspace Repos** | Local Directory | **Google Cloud Storage (GCS)** Buckets |
+| **Traffic Router** | Direct Port Binding | **Google Cloud Load Balancing** (HTTPS Layer 7 Router) |
+
+---
+
+## 📦 Installation & Setup
+
+### Install as Python Package (Local Development)
+You can install AgyQueue locally in editable mode for development and testing:
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+cp .env.example .env
+```
+
+### Install from PyPI
+Once published, users can install AgyQueue directly from PyPI:
+```bash
+pip install agyqueue
+```
+
+---
+
+## 🏁 Quick Start
+
+### 1. Run Standalone Dev Demo
+Spins up a local server, enqueues an SRE compliance check and FastAPI code generator workflow, executes it in isolated directories, and outputs the final report:
+```bash
+python examples/demo.py
+```
+
+### 2. Open the Web Console Dashboard
+Start the standalone SSE server and background worker:
+```bash
+# Terminal 1: Start Server
+export AGYQUEUE_TRANSPORT=sse
+python -m agyqueue.mcp_server
+
+# Terminal 2: Start Worker
+python -m agyqueue.worker
+```
+Navigate to [http://localhost:8000/dashboard](http://localhost:8000/dashboard) to submit runs, inspect progress, and view timeline event history logs.
+
+---
+
+## 📁 Examples & Client Integrations
+
+The [examples/](file:///Users/jitendragupta/Documents/github-repo/agyqueue/examples/) folder contains detailed client scripts for every connection method:
+
+* **Antigravity 2.0 SDK**: [examples/antigravity_agent_sdk.py](file:///Users/jitendragupta/Documents/github-repo/agyqueue/examples/antigravity_agent_sdk.py) shows how to bind tools to a `google.antigravity` agent.
+* **Google ADK Agents**: [examples/google_adk_agent.py](file:///Users/jitendragupta/Documents/github-repo/agyqueue/examples/google_adk_agent.py) demonstrates tool binding in the `google.adk.agents` framework.
+* **StdIO MCP Client**: [examples/mcp_stdio_client.py](file:///Users/jitendragupta/Documents/github-repo/agyqueue/examples/mcp_stdio_client.py) connects programmatically via stdin/stdout subprocesses.
+* **SSE MCP Client**: [examples/mcp_sse_client.py](file:///Users/jitendragupta/Documents/github-repo/agyqueue/examples/mcp_sse_client.py) connects over network Server-Sent Events.
+* **Direct REST SDK**: [examples/rest_client_sdk_demo.py](file:///Users/jitendragupta/Documents/github-repo/agyqueue/examples/rest_client_sdk_demo.py) performs calls using the lightweight `AgyQueueClient` Python client.
+
+---
+
+## 🔌 Connecting to Agentic Frameworks
+
+### 1. Google Agent Development Kit (ADK) & Agent Engine
+The Google **ADK** allows Python-defined agents to be deployed to **Agent Engine** (Vertex AI Reasoning Engine). Import and register AgyQueue's functional tools directly:
+
+```python
+from google.adk.agents import Agent
+from agyqueue.client import submit_async_task, check_task_progress, get_task_output, cancel_running_task
+
+# Define the coordinator agent
+orchestrator_agent = Agent(
+    name="deployment_coordinator",
+    model="gemini-2.5-flash",
+    instruction=(
+        "You coordinate SRE compliance checks and API code generation workloads. "
+        "Use submit_async_task to spawn background jobs. Do not wait for jobs in a loop. "
+        "Return the task_id to the user/orchestrator so that progress can be tracked asynchronously."
+    ),
+    tools=[
+        submit_async_task,
+        check_task_progress,
+        get_task_output,
+        cancel_running_task
+    ]
+)
+```
+
+### 2. Registering with Gemini Enterprise & Agent Registry
+Expose the deployed URL to Gemini Enterprise using the `agents-cli` tool:
+```bash
+agents-cli publish gemini-enterprise \
+  --name "agyqueue-service" \
+  --description "Exposes asynchronous background task execution, cancellation, and progress tracking tools." \
+  --url "https://agyqueue-server-dev-xxxx-uc.a.run.app/sse" \
+  --type "mcp"
+```
+
+---
+
+## 💻 Local IDE Integration (MCP)
+
+### Claude Desktop Configuration
+Add the following to your `claude_desktop_config.json` (located in `~/Library/Application Support/Claude/` on macOS):
+```json
+{
+  "mcpServers": {
+    "agyqueue": {
+      "command": "python",
+      "args": ["-m", "agyqueue.mcp_server"],
+      "env": {
+        "PYTHONPATH": "/absolute/path/to/your/agyqueue/repo",
+        "AGYQUEUE_TRANSPORT": "stdio",
+        "AGYQUEUE_DB_PATH": "/absolute/path/to/your/agyqueue/repo/agyqueue.db"
+      }
+    }
+  }
+}
+```
+
+### Cursor Configuration
+1. Open Cursor Settings -> Features -> MCP.
+2. Click **+ Add New MCP Server**.
+3. Configure:
+   * **Name**: `AgyQueue`
+   * **Type**: `command`
+   * **Command**: `PYTHONPATH=. .venv/bin/python -m agyqueue.mcp_server` (relative to your repo path).
+
+### VS Code Configuration (Cline / Roo Code Extensions)
+Append the AgyQueue stdio server configuration to `cline_mcp_settings.json`:
+```json
+{
+  "mcpServers": {
+    "agyqueue": {
+      "command": "python",
+      "args": ["-m", "agyqueue.mcp_server"],
+      "env": {
+        "PYTHONPATH": "/absolute/path/to/your/agyqueue/repo",
+        "AGYQUEUE_TRANSPORT": "stdio",
+        "AGYQUEUE_DB_PATH": "/absolute/path/to/your/agyqueue/repo/agyqueue.db"
+      }
+    }
+  }
+}
+```
+
+### Claude Code CLI Integration
+Add AgyQueue as a local tool under the `"mcpServers"` dictionary in `~/.config/claude-code/mcp.json`.
+
+---
+
+## 🌳 Multi-Agent Tree-Based Orchestration Pattern
+
+AgyQueue natively supports **parent-child task aggregation**. When an orchestrator agent splits a large request into parallel child workloads, it submits the subtasks with a `parent_id` parameter:
+
+1. **Task Submission**:
+   * The orchestrator spawns subagents by submitting child tasks referencing the parent ID.
+   * The parent task status transitions to `WAITING`.
+2. **Worker Isolation**:
+   * Background workers pick up and execute child tasks in isolated workspaces (`git_worktree` or copy-on-write temp folders) in parallel.
+3. **Automatic Resumption**:
+   * As soon as the final sibling completes, the worker recognizes that all siblings are done and automatically re-queues the parent task.
+   * The orchestrator wakes up, reads the logs of all completed subtasks, aggregates the results, and marks the parent task as `COMPLETED`.
+
+---
+
+## 🐳 Docker Compose Deployment (Redis + SSE Mode)
+
+To run the complete system with Redis queues and PostgreSQL stores:
+1. **Build and Run**:
+   ```bash
+   docker compose up --build
+   ```
+2. **Verify over SSE**:
+   ```bash
+   python examples/mcp_sse_client.py
+   ```
+
+---
+
+## ☁️ Cloud Deployment (Cloud Run & GKE)
+
+For Google Cloud production environments, configuration templates are located in [deployment/](file:///Users/jitendragupta/Documents/github-repo/agyqueue/deployment/):
+* **Cloud Run**: Serverless container setups with Memorystore Redis and Cloud SQL PostgreSQL.
+* **GKE**: Scalable Kubernetes microservices with Horizontal Pod Autoscalers (HPA).
+
+---
+
+## 🔔 Slack & Email Notifications
+
+To configure alerts on task completion or failure, set the following environment variables:
+```bash
+# Enable channels (comma-separated list)
+export AGYQUEUE_NOTIFICATIONS="slack,email"
+
+# 1. Slack Webhook Configuration
+export SLACK_WEBHOOK_URL="https://example.com/slack-webhook-url"
+
+# 2. Email SMTP Configuration
+export SMTP_HOST="smtp.gmail.com"
+export SMTP_PORT="587"
+export SMTP_USER="your-email@gmail.com"
+export SMTP_PASSWORD="your-app-password"
+export SMTP_FROM="noreply@agyqueue.internal"
+export SMTP_TO="recipient-alert-inbox@domain.com"
+```
+
+---
+
+## 🚀 Publishing to PyPI
+
+### Step 1: Install Build Tools
+```bash
+pip install --upgrade build twine
+```
+
+### Step 2: Build the Distribution Package
+```bash
+python -m build
+```
+
+### Step 3: Upload to PyPI
+Run twine to securely publish to PyPI under your profile:
+```bash
+python -m twine upload dist/*
+```
+Once uploaded, anyone can install and run the AgyQueue CLI globally:
+```bash
+pip install agyqueue
+```

agyqueue-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+agyqueue/__init__.py,sha256=Cw2u8BU9kJuaMrBNhUiwy_n9NabQSL97gDYd5tFXt40,34
+agyqueue/client.py,sha256=ZzavScN7pCBNJkrcASKyqHxUBogR9mafFHKsRbZGY_U,5085
+agyqueue/config.py,sha256=mHA6VRxoxcOuwM03CaY5IYwSiIXkqBtTjszgv_c3m-g,1966
+agyqueue/dashboard.html,sha256=dsNAxdBWILkbfDY2vGYPXv5E2pcy52MzlGbnbQ1dWoA,42629
+agyqueue/mcp_server.py,sha256=XNirkItZwjfIYYYWnNuEAKqkhp4-lSOqWkFwoEW8i4A,16674
+agyqueue/models.py,sha256=CQq3FnRQZpda3kTgFq5LJjyhYW6Odmy0nAIOBAcFp94,1156
+agyqueue/notifications.py,sha256=jcRvMtpJAce7CliyZEglPTykGuaWRWmDdiMDILo0J-Q,7476
+agyqueue/storage.py,sha256=eZnbIt6dqJWO1-wpfUnWYL9dOkasC0GmVloYX1zqo-Y,15822
+agyqueue/task_queue.py,sha256=y7jHuBswguTWyb8XkiAmzQ7z0BXavoEdyyRQefBIUKE,4261
+agyqueue/worker.py,sha256=e0fIZLnUHp9RLyC1LqkB5IYJ8LGU-mAz5OaqHHruTyE,24382
+agyqueue-0.1.0.dist-info/METADATA,sha256=ojKi4XpkRkg7GVaXDl14Q80YpldupxtnXZngrAcFDd8,11412
+agyqueue-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agyqueue-0.1.0.dist-info/entry_points.txt,sha256=OiRh55kSov3dY6UDwPeFHZ0U4PrdtsMvhVnKLy8vW1U,54
+agyqueue-0.1.0.dist-info/top_level.txt,sha256=2T5VJ8b9nD7kRcz6TueRlCBdCNdgKkHak2QhmKsBgFU,9
+agyqueue-0.1.0.dist-info/RECORD,,

agyqueue-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agyqueue-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agyqueue = agyqueue.mcp_server:main

agyqueue-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agyqueue