agent-gantry 0.1.0__tar.gz

agent_gantry-0.1.0/.github/ISSUE_TEMPLATE/01-advanced-routing-orchestration.md

@@ -0,0 +1,74 @@
+---
+name: "🎯 Advanced Routing & Orchestration"
+about: Feature requests for hierarchical routing, tool chaining, and parameter-aware routing
+title: "[Routing] "
+labels: ["enhancement", "routing", "orchestration"]
+assignees: []
+---
+
+## Feature Area
+<!-- Check the area(s) this feature request relates to -->
+- [ ] Hierarchical / Domain Routing (Router of Routers)
+- [ ] Tool Chaining / Pipelines (Atomic Workflows)
+- [ ] Parameter-Aware Routing (Contextual Feasibility)
+
+## Problem Statement
+<!-- Describe the current limitation or problem this feature would solve -->
+
+**Current Behavior:**
+<!-- What happens now? -->
+
+**Desired Behavior:**
+<!-- What should happen instead? -->
+
+## Proposed Solution
+
+### Overview
+<!-- High-level description of your proposed solution -->
+
+### Technical Details
+<!-- Technical implementation details, if applicable -->
+
+### Example Usage
+<!-- Provide a code example or pseudocode showing how this would work -->
+
+```python
+# Example usage
+```
+
+## Use Case
+<!-- Describe a real-world scenario where this feature would be valuable -->
+
+**Example Scenario:**
+
+
+**Expected Benefit:**
+
+
+## Context: Current Architecture
+
+Currently, Agent-Gantry excels at "Flat" Semantic Retrieval (finding the best tool for a query). This feature request aims to expand beyond that foundation.
+
+### Hierarchical / Domain Routing
+- **Goal**: As tool counts grow from 100 to 10,000, implement a "Router of Routers" pattern
+- **Example**: First route to "Finance Domain", then to "Tax Calculator"
+- **Benefit**: Improved scalability and reduced noise in vector search
+
+### Tool Chaining / Pipelines
+- **Goal**: Support Atomic Workflows—pre-defined chains of tools exposed as a single "Meta-Tool"
+- **Example**: `onboard_employee` executes `create_email` → `create_slack` → `send_welcome`
+- **Benefit**: Reduce LLM complexity by handling multi-step workflows internally
+
+### Parameter-Aware Routing
+- **Goal**: Enhance router to check Contextual Feasibility beyond semantic similarity
+- **Example**: If a tool requires `order_id` and no such entity exists in conversation history, penalize that tool's score
+- **Benefit**: More accurate tool selection based on available context
+
+## Additional Context
+<!-- Add any other context, screenshots, or references -->
+
+## Related Issues
+<!-- Link to related issues or PRs -->
+
+---
+**Note**: This feature aligns with the strategic roadmap for scaling Agent-Gantry to handle enterprise-scale tool inventories and complex orchestration patterns.

agent_gantry-0.1.0/.github/ISSUE_TEMPLATE/02-enterprise-security-governance.md

@@ -0,0 +1,92 @@
+---
+name: "🔒 Enterprise Security & Governance"
+about: Feature requests for HITL, PII redaction, rate limiting, and compliance features
+title: "[Security] "
+labels: ["enhancement", "security", "governance", "compliance"]
+assignees: []
+---
+
+## Feature Area
+<!-- Check the area(s) this feature request relates to -->
+- [ ] Human-in-the-Loop (HITL) Protocol
+- [ ] PII Redaction / Data Loss Prevention (DLP)
+- [ ] Rate Limiting & Quotas
+- [ ] Other Compliance/Governance Feature
+
+## Problem Statement
+<!-- Describe the current security or governance gap this feature would address -->
+
+**Current Behavior:**
+<!-- What security/governance mechanisms exist today? -->
+
+**Desired Behavior:**
+<!-- What additional safeguards are needed? -->
+
+## Proposed Solution
+
+### Overview
+<!-- High-level description of your proposed solution -->
+
+### Security Model
+<!-- Describe the security model, threat model, or compliance requirement -->
+
+### Technical Details
+<!-- Technical implementation details, if applicable -->
+
+### Example Usage
+<!-- Provide a code example showing how this would work -->
+
+```python
+# Example usage
+```
+
+## Use Case
+<!-- Describe a real-world scenario where this security feature is critical -->
+
+**Example Scenario:**
+
+
+**Risk Mitigation:**
+
+
+## Context: Current Security Features
+
+Agent-Gantry currently provides:
+- ✅ Zero-Trust architecture with capability-based permissions
+- ✅ Circuit breakers for automatic failure detection
+- ✅ Tool-level health tracking and observability
+
+This feature request aims to enhance compliance and governance capabilities.
+
+### Human-in-the-Loop (HITL) Protocol
+- **Goal**: Standardized hook for "Sensitive Tools" requiring human approval
+- **Example**: Instead of executing `delete_production_db` immediately, return `PendingApproval` status requiring secondary confirmation
+- **Benefit**: Prevent catastrophic actions through mandatory human oversight
+
+### PII Redaction / DLP
+- **Goal**: Middleware to automatically detect and redact sensitive information
+- **Example**: Strip credit cards, API keys, PII from tool inputs/outputs before logging to telemetry
+- **Benefit**: Compliance with GDPR, HIPAA, and other data protection regulations
+
+### Rate Limiting & Quotas
+- **Goal**: Per-tool or per-user rate limits
+- **Example**: "The `send_sms` tool can only be called 10 times per hour"
+- **Benefit**: Prevent abuse, control costs, and ensure fair resource usage
+
+## Compliance Requirements
+<!-- List any specific compliance standards this feature would help meet -->
+- [ ] GDPR (General Data Protection Regulation)
+- [ ] HIPAA (Health Insurance Portability and Accountability Act)
+- [ ] SOC 2
+- [ ] ISO 27001
+- [ ] PCI DSS
+- [ ] Other: 
+
+## Additional Context
+<!-- Add any other context, security considerations, or references -->
+
+## Related Issues
+<!-- Link to related issues or PRs -->
+
+---
+**Note**: This feature aligns with the strategic goal of making Agent-Gantry production-ready for enterprise deployments with strict compliance requirements.

agent_gantry-0.1.0/.github/ISSUE_TEMPLATE/03-frictionless-onboarding.md

@@ -0,0 +1,107 @@
+---
+name: "🚀 Frictionless Onboarding (Importers)"
+about: Feature requests for automatic tool import from various sources (OpenAPI, databases, etc.)
+title: "[Importer] "
+labels: ["enhancement", "importer", "dx", "onboarding"]
+assignees: []
+---
+
+## Feature Area
+<!-- Check the area(s) this feature request relates to -->
+- [ ] OpenAPI / Swagger Ingestion
+- [ ] Database Introspection
+- [ ] Other Tool Source Integration
+
+## Problem Statement
+<!-- Describe the current onboarding friction this feature would eliminate -->
+
+**Current Behavior:**
+<!-- How do users currently register tools from this source? -->
+
+**Desired Behavior:**
+<!-- What one-line import experience should exist? -->
+
+## Proposed Solution
+
+### Overview
+<!-- High-level description of the importer -->
+
+### Import Source
+<!-- Describe the source system, format, or protocol -->
+
+### Technical Details
+<!-- Technical implementation details, if applicable -->
+
+### Example Usage
+<!-- Provide a code example showing the one-line import -->
+
+```python
+# Example usage
+from agent_gantry import AgentGantry
+
+gantry = AgentGantry()
+
+# One-line import example
+```
+
+## Use Case
+<!-- Describe a real-world scenario where this importer would be valuable -->
+
+**Example Scenario:**
+
+
+**Expected Benefit:**
+
+
+## Context: Current Tool Registration
+
+Currently, Agent-Gantry supports tool registration from:
+- ✅ Python functions (via `@gantry.register` decorator)
+- ✅ MCP servers (via `add_mcp_server`)
+- ✅ A2A agents (via `add_a2a_agent`)
+
+This feature request aims to expand "one-line import" capabilities for additional sources.
+
+### OpenAPI / Swagger Ingestion
+- **Goal**: One-line import for existing REST APIs
+- **Example**: `gantry.ingest_openapi("https://api.stripe.com/v1/spec.json")`
+- **Benefit**: Auto-generate tool definitions and schemas for every endpoint
+- **Output**: Creates tools like `stripe_create_charge`, `stripe_list_customers`, etc.
+
+### Database Introspection
+- **Goal**: Auto-generate tools for SQL queries based on schema
+- **Example**: `gantry.ingest_postgres(connection_string, tables=["users", "orders"])`
+- **Benefit**: Creates CRUD tools like `search_users`, `get_user_by_id`, `update_order_status`
+- **Output**: Type-safe tools based on database schema
+
+### Other Integration Ideas
+- GraphQL schema introspection
+- gRPC service definitions
+- Kubernetes API resources
+- Cloud provider APIs (AWS, GCP, Azure)
+- SaaS APIs (Slack, GitHub, Jira, etc.)
+
+## Schema Mapping
+<!-- Describe how the source schema would map to Agent-Gantry tool definitions -->
+
+**Source Schema:**
+```
+<!-- Example of source format -->
+```
+
+**Generated Tool:**
+```python
+# Example of generated AgentGantry tool
+```
+
+## Authentication & Configuration
+<!-- How would authentication and configuration be handled? -->
+
+## Additional Context
+<!-- Add any other context, API documentation links, or references -->
+
+## Related Issues
+<!-- Link to related issues or PRs -->
+
+---
+**Note**: This feature aligns with the strategic goal of reducing friction in tool onboarding and accelerating time-to-value for Agent-Gantry users.

agent_gantry-0.1.0/.github/ISSUE_TEMPLATE/04-developer-experience-ui.md

@@ -0,0 +1,109 @@
+---
+name: "🎨 Developer Experience & UI"
+about: Feature requests for Gantry Dashboard, visualization, testing, and debugging tools
+title: "[DX] "
+labels: ["enhancement", "dx", "ui", "tooling"]
+assignees: []
+---
+
+## Feature Area
+<!-- Check the area(s) this feature request relates to -->
+- [ ] Gantry Dashboard (Web UI)
+- [ ] Simulation & Replay (Snapshot Testing)
+- [ ] Visualization Tools
+- [ ] Debugging Tools
+- [ ] Other DX Enhancement
+
+## Problem Statement
+<!-- Describe the current DX limitation this feature would solve -->
+
+**Current Behavior:**
+<!-- What developer workflow exists today? -->
+
+**Desired Behavior:**
+<!-- What improved workflow should exist? -->
+
+## Proposed Solution
+
+### Overview
+<!-- High-level description of your proposed solution -->
+
+### User Interface
+<!-- If this involves a UI, describe the interface or provide mockups -->
+
+### Technical Details
+<!-- Technical implementation details, if applicable -->
+
+### Example Usage
+<!-- Provide examples or screenshots showing how this would work -->
+
+```python
+# Example usage or CLI command
+```
+
+## Use Case
+<!-- Describe a real-world developer workflow this would improve -->
+
+**Example Scenario:**
+
+
+**Expected Benefit:**
+
+
+## Context: Current Developer Tools
+
+Agent-Gantry currently provides:
+- ✅ CLI for listing and searching tools (`agent-gantry list`, `agent-gantry search`)
+- ✅ Structured logging and telemetry
+- ✅ OpenTelemetry integration for tracing
+
+This feature request aims to enhance the developer experience with additional tooling.
+
+### Gantry Dashboard (Web UI)
+- **Goal**: Lightweight local web server for development and debugging
+- **Technology**: Streamlit, FastUI, or similar
+- **Features**:
+  - Visualize the Vector Space (see how tools cluster)
+  - Monitor Circuit Breaker status (manually reset tripped breakers)
+  - View Traces/Logs in real-time
+  - Manually test tools without an LLM
+  - Inspect tool registrations and metadata
+  - Performance metrics and health dashboard
+
+### Simulation & Replay
+- **Goal**: Record and replay tool execution sessions for testing
+- **Features**:
+  - Record a session of tool executions
+  - Replay sessions against new tool code
+  - Detect regressions (Snapshot Testing for Agents)
+  - Compare behavior before/after changes
+- **Use Case**: Ensure tool changes don't break existing agent workflows
+
+### Visualization Tools
+- **Ideas**:
+  - Tool similarity heatmaps
+  - Routing decision trees
+  - Token usage analytics
+  - Tool execution timelines
+
+### Debugging Tools
+- **Ideas**:
+  - Interactive tool tester
+  - Schema validator
+  - Embedding inspector
+  - Query analyzer (why was this tool ranked high/low?)
+
+## UI/UX Considerations
+<!-- Describe any specific UI/UX requirements or considerations -->
+
+## Technical Stack Preferences
+<!-- Any preferences for frameworks, libraries, or approaches? -->
+
+## Additional Context
+<!-- Add any other context, mockups, or references -->
+
+## Related Issues
+<!-- Link to related issues or PRs -->
+
+---
+**Note**: This feature aligns with the strategic goal of providing a best-in-class developer experience for building and debugging agent systems.

agent_gantry-0.1.0/.github/ISSUE_TEMPLATE/05-smart-learning.md

@@ -0,0 +1,121 @@
+---
+name: "🧠 Smart Learning"
+about: Feature requests for feedback loops, RLHF for tools, and adaptive routing
+title: "[Learning] "
+labels: ["enhancement", "learning", "rlhf", "adaptive"]
+assignees: []
+---
+
+## Feature Area
+<!-- Check the area(s) this feature request relates to -->
+- [ ] Feedback Loop (RLHF for Tools)
+- [ ] Adaptive Embeddings
+- [ ] Tool Performance Learning
+- [ ] User Preference Learning
+- [ ] Other Learning Feature
+
+## Problem Statement
+<!-- Describe the current limitation in learning/adaptation this feature would address -->
+
+**Current Behavior:**
+<!-- How does routing/selection work today? -->
+
+**Desired Behavior:**
+<!-- How should the system learn and adapt? -->
+
+## Proposed Solution
+
+### Overview
+<!-- High-level description of the learning mechanism -->
+
+### Learning Mechanism
+<!-- Describe how feedback is collected and applied -->
+
+### Technical Details
+<!-- Technical implementation details, if applicable -->
+
+### Example Usage
+<!-- Provide a code example showing how this would work -->
+
+```python
+# Example usage
+from agent_gantry import AgentGantry
+
+gantry = AgentGantry()
+
+# Example of feedback collection and learning
+```
+
+## Use Case
+<!-- Describe a real-world scenario where learning would improve outcomes -->
+
+**Example Scenario:**
+
+
+**Expected Improvement:**
+
+
+## Context: Current Routing Behavior
+
+Agent-Gantry currently uses:
+- ✅ Semantic similarity (vector search)
+- ✅ Intent classification
+- ✅ MMR diversity
+- ✅ Static health metrics (success rate, circuit breaker state)
+
+This feature request aims to add **adaptive learning** capabilities that improve over time.
+
+### Feedback Loop (RLHF for Tools)
+- **Goal**: Learn from tool selection feedback to improve future routing
+- **Mechanism**:
+  - If an LLM tries to use a tool and fails (or user explicitly says "wrong tool")
+  - Record this negative feedback in a feedback store
+  - Adjust embeddings or routing weights to penalize Tool A for Query X
+  - Even if semantically similar, learn that Tool A is bad for this query type
+- **Example**:
+  ```python
+  # User corrects tool selection
+  await gantry.record_feedback(
+      query="cancel my subscription",
+      selected_tool="pause_subscription",  # Wrong
+      correct_tool="cancel_subscription",  # Correct
+      feedback_type="tool_selection_error"
+  )
+  
+  # Future queries automatically improve
+  tools = await gantry.retrieve_tools("cancel my subscription")
+  # Now correctly ranks cancel_subscription higher
+  ```
+
+### Adaptive Embeddings
+- **Goal**: Fine-tune embeddings based on actual usage patterns
+- **Approach**: 
+  - Collect positive/negative pairs from tool execution outcomes
+  - Periodically retrain or adjust embeddings
+  - Learn domain-specific semantics
+
+### Tool Performance Learning
+- **Goal**: Learn which tools work well together, which fail frequently, etc.
+- **Metrics**: Track correlation between tool pairs, failure patterns, timing
+
+### User Preference Learning
+- **Goal**: Learn per-user or per-team tool preferences
+- **Example**: Team A prefers `slack_notify` over `email_notify`
+
+## Feedback Collection Strategy
+<!-- How would feedback be collected? Manual, automatic, both? -->
+
+## Privacy & Data Considerations
+<!-- Any privacy concerns with collecting feedback data? -->
+
+## Evaluation Metrics
+<!-- How would you measure if the learning is working? -->
+
+## Additional Context
+<!-- Add any other context, research papers, or references -->
+
+## Related Issues
+<!-- Link to related issues or PRs -->
+
+---
+**Note**: This feature aligns with the strategic goal of creating a self-improving tool orchestration system that gets better with use.

agent_gantry-0.1.0/.github/ISSUE_TEMPLATE/06-state-management.md

@@ -0,0 +1,146 @@
+---
+name: "💾 State Management"
+about: Feature requests for session memory, context persistence, and stateful tools
+title: "[State] "
+labels: ["enhancement", "state", "memory", "session"]
+assignees: []
+---
+
+## Feature Area
+<!-- Check the area(s) this feature request relates to -->
+- [ ] Session Memory / Context Store
+- [ ] Cross-Tool State Sharing
+- [ ] Persistent State Storage
+- [ ] State Scoping (user, session, global)
+- [ ] Other State Management Feature
+
+## Problem Statement
+<!-- Describe the current limitation in state management this feature would address -->
+
+**Current Behavior:**
+<!-- How is state currently handled? -->
+
+**Desired Behavior:**
+<!-- What state management capabilities are needed? -->
+
+## Proposed Solution
+
+### Overview
+<!-- High-level description of the state management solution -->
+
+### State Model
+<!-- Describe the state model, scope, and lifecycle -->
+
+### Technical Details
+<!-- Technical implementation details, if applicable -->
+
+### Example Usage
+<!-- Provide a code example showing how state would be accessed -->
+
+```python
+# Example usage
+from agent_gantry import AgentGantry
+
+gantry = AgentGantry()
+
+@gantry.register
+async def read_file(filename: str, ctx) -> str:
+    """Read a file and remember it."""
+    # Store in session memory
+    content = read_from_disk(filename)
+    ctx.memory["last_file"] = filename
+    ctx.memory["file_content"] = content
+    return content
+
+@gantry.register
+async def summarize_last_file(ctx) -> str:
+    """Summarize the last file that was read."""
+    # Access from session memory
+    filename = ctx.memory.get("last_file")
+    content = ctx.memory.get("file_content")
+    return f"Summary of {filename}: {generate_summary(content)}"
+```
+
+## Use Case
+<!-- Describe a real-world scenario where state management would be valuable -->
+
+**Example Scenario:**
+
+
+**Expected Benefit:**
+
+
+## Context: Current State Handling
+
+Currently, Agent-Gantry is largely stateless:
+- ✅ Tools are pure functions or async callables
+- ✅ Context is passed via LLM conversation history
+- ⚠️ No built-in mechanism for tools to share state
+- ⚠️ Tools must pass state via arguments every time
+
+This feature request aims to add **session-scoped state management** for tools.
+
+### Session Memory
+- **Goal**: Tools can persist state within a session without external DBs
+- **Example**: "What file was I reading?" without passing filename every time
+- **Scope**: Per-session, per-user, or per-conversation
+- **Storage**: In-memory by default, pluggable backends (Redis, etc.)
+
+### Use Cases
+1. **Multi-Step Workflows**: Tool A stores intermediate results for Tool B
+2. **File Operations**: Remember "current working directory" or "active file"
+3. **Conversation Context**: Track entities, IDs, or references mentioned in conversation
+4. **Caching**: Store expensive computation results within a session
+5. **User Preferences**: Remember user choices within a session
+
+### State API Design Considerations
+```python
+# Option 1: Context parameter
+@gantry.register
+async def my_tool(arg: str, ctx: ExecutionContext) -> str:
+    ctx.memory["key"] = "value"
+    return ctx.memory.get("other_key", default="")
+
+# Option 2: Session object
+@gantry.register(stateful=True)
+async def my_tool(arg: str, session: Session) -> str:
+    await session.set("key", "value")
+    return await session.get("other_key")
+
+# Option 3: Decorator-based
+@gantry.register
+@gantry.with_memory(scope="session")
+async def my_tool(arg: str, memory: dict) -> str:
+    memory["key"] = "value"
+    return memory.get("other_key", "")
+```
+
+## State Scoping
+<!-- Define different scope levels for state -->
+- [ ] **Session-scoped**: State persists for a single agent session
+- [ ] **User-scoped**: State persists across sessions for a user
+- [ ] **Global-scoped**: State shared across all users (with proper isolation)
+- [ ] **Tool-scoped**: Each tool instance has its own state
+
+## Persistence Strategy
+<!-- How should state be persisted? -->
+- [ ] In-memory only (lost on restart)
+- [ ] Redis/Memcached
+- [ ] Database (PostgreSQL, SQLite)
+- [ ] File-based
+- [ ] Pluggable backend
+
+## Thread Safety & Concurrency
+<!-- How should concurrent access be handled? -->
+
+## TTL & Expiration
+<!-- Should state expire automatically? -->
+
+## Additional Context
+<!-- Add any other context, architecture diagrams, or references -->
+
+## Related Issues
+<!-- Link to related issues or PRs -->
+
+---
+**Note**: This feature aligns with the strategic goal of supporting stateful tool patterns and multi-step agent workflows without requiring external state management.