pulumi tool

Author: phenobarbital

.agent/CONTEXT.md

@@ -1,20 +1,130 @@
-# 🧠 AI-Optimized Project Context: Antigravity Workspace
+# AI-Parrot — Architectural Context
 
-## 1. Executive Summary & Core Mission
+## What is AI-Parrot
+Async-first Python framework for building AI Agents and Chatbots.
+Vendor-agnostic: supports OpenAI, Anthropic, Google GenAI, Groq, VertexAI,
+HuggingFace via a unified `AbstractClient` interface.
 
-**Core Philosophy: "Cognitive-First" & "Artifact-First"**
-The agent must not just execute tasks but *think* like a senior engineer. This is achieved through a mandatory "Think-Act-Reflect" loop.
+---
+
+## Core Abstractions (always inherit from these)
+
+### AbstractClient
+Unified interface for all LLM providers.
+Location: `parrot/clients/abstract_client.py`
+- Never call provider SDKs directly — always go through AbstractClient
+- Implement `async def completion()`, `async def stream()`, `async def embed()`
+
+### AbstractBot / Chatbot / Agent
+Location: `parrot/bots/`
+- `AbstractBot` — base class for all bots
+- `Chatbot` — conversational, stateful, single-LLM
+- `Agent` — tool-using, ReAct-style reasoning loop
+
+### AbstractTool / @tool decorator
+Location: `parrot/tools/`
+- Simple functions: use `@tool` decorator
+- Complex collections: inherit `AbstractToolkit`
+- Every tool MUST have a docstring — it becomes the LLM's tool description
+
+### AgentCrew
+Location: `parrot/bots/orchestration/crew.py`
+Three execution modes:
+- `run_sequential()` — agents in chain, output feeds next
+- `run_parallel()` — agents run concurrently, results merged
+- `run_flow()` — DAG-based, dependencies declared via `task_flow()`
+
+### Loaders
+Location: `parrot/loaders/`
+Transform documents (PDF, HTML, DOCX, etc.) into text chunks for RAG.
+Inherit `BaseLoader`, implement `async def load() -> list[Document]`
+
+### Vector Stores
+- PgVector: `parrot/vectorstores/pgvector.py` — primary store
+- ArangoDB: graph-based, in development
+
+---
+
+## Key Patterns to Follow
+
+### Registering a new component
+New bots/tools/clients are registered via decorators:
+```python
+from parrot.registry import register_agent
+
+@register_agent("my-agent")
+class MyAgent(Agent):
+    ...
+```
+
+### Async everywhere
+```python
+# CORRECT
+async def process(self, data: str) -> Result:
+    result = await self.client.completion(data)
+    return result
+
+# WRONG — never block the event loop
+def process(self, data: str) -> Result:
+    return requests.post(...)
+```
+
+### Logging pattern
+```python
+import logging
+
+class MyComponent:
+    def __init__(self):
+        self.logger = logging.getLogger(__name__)
+    
+    async def method(self):
+        self.logger.info("Starting operation")
+        self.logger.debug("Detail: %s", detail)
+```
+
+### Pydantic for all structured data
+```python
+from pydantic import BaseModel, Field
+
+class ToolInput(BaseModel):
+    query: str = Field(..., description="Used as tool description for LLM")
+    top_k: int = Field(default=5, ge=1, le=20)
+```
+
+---
+
+## What Lives Where
+```
+parrot/
+├── clients/          # LLM provider wrappers (AbstractClient subclasses)
+├── bots/             # Bot and Agent implementations
+│   └── orchestration/  # AgentCrew, DAG execution
+├── tools/            # Tool definitions and toolkits
+├── loaders/          # Document loaders for RAG
+├── vectorstores/     # PgVector, ArangoDB
+├── handlers/         # HTTP handlers (aiohttp-based)
+├── memory/           # Conversation memory (Redis-backed)
+└── integrations/     # Telegram, MS Teams, Slack, MCP
+```
+
+---
 
-1.  **Think (Plan):** Before any complex coding, the agent MUST generate a plan in `artifacts/plan_[task_id].md`. This enforces structured thinking.
-2.  **Act (Execute):** Write clean, modular, and well-documented code following the project's strict standards.
-3.  **Reflect (Verify):** The agent is responsible for verifying its work, primarily by running `pytest` after making changes. All evidence (logs, test results) is stored in `artifacts/logs/`.
+## What NOT to Do
+- Never use `requests` or `httpx` — use `aiohttp`
+- Never subclass LangChain components — LangChain is removed
+- Never store secrets in code — use environment variables
+- Never add synchronous blocking code in async methods
+- Never modify `abstract_client.py` without discussing first — it's the foundation
 
 ---
 
-## 2. Environment, DevOps, and Project Structure
+## Current Active Development
+Branch: `finance-agents`
+Main: `main`
 
-*   `.agent/`: Core AI rules and persona. **(Crucial for agent behavior)**.
-    *   `rules.md`: The Agent's Constitution and Directive.
-    *   `rules/python-development.md`: Specific standards for Python development (uv, venv, libraries).
-*   `artifacts/`: All agent-generated outputs (plans, logs, screenshots).
-*   `tests/`: The `pytest` test suite.
+Active areas (check these before modifying):
+- `parrot/bots/orchestration/` — AgentCrew DAG execution
+- `parrot/memory/` — Redis-based conversation memory
+- `parrot/integrations/mcp/` — MCP server implementation
+- `parrot/tools/` — Tool definitions and toolkits
+- `parrot/integrations/` — Platform integrations (Whatsapp, Telegram, Slack, MS Teams)

parrot/auth/__init__.py

@@ -0,0 +1,46 @@
+"""Authentication and authorization module for AI-Parrot.
+
+This module provides granular permission control for tools and toolkits.
+
+Public API:
+    Data Models:
+    - UserSession: Immutable session with user identity and role claims
+    - PermissionContext: Request-scoped wrapper for permission checking
+
+    Resolvers:
+    - AbstractPermissionResolver: ABC for custom permission implementations
+    - DefaultPermissionResolver: RBAC implementation with hierarchy and caching
+    - AllowAllResolver: Development/testing resolver (allows everything)
+    - DenyAllResolver: Lockdown resolver (denies restricted tools)
+
+Example:
+    >>> from parrot.auth import UserSession, PermissionContext, DefaultPermissionResolver
+    >>> session = UserSession(
+    ...     user_id="user-123",
+    ...     tenant_id="acme-corp",
+    ...     roles=frozenset({'jira.write', 'github.read'})
+    ... )
+    >>> ctx = PermissionContext(session=session, request_id="req-456")
+    >>> resolver = DefaultPermissionResolver(role_hierarchy={'jira.write': {'jira.read'}})
+    >>> await resolver.can_execute(ctx, "create_issue", {'jira.write'})
+    True
+"""
+
+from .permission import PermissionContext, UserSession
+from .resolver import (
+    AbstractPermissionResolver,
+    AllowAllResolver,
+    DefaultPermissionResolver,
+    DenyAllResolver,
+)
+
+__all__ = [
+    # Data models
+    "UserSession",
+    "PermissionContext",
+    # Resolvers
+    "AbstractPermissionResolver",
+    "DefaultPermissionResolver",
+    "AllowAllResolver",
+    "DenyAllResolver",
+]

parrot/auth/permission.py

@@ -0,0 +1,143 @@
+"""Permission data models for granular tool/toolkit access control.
+
+This module provides foundational data structures for the permission system:
+- UserSession: Immutable session carrying user identity and role claims
+- PermissionContext: Request-scoped wrapper with session and metadata
+
+These are lightweight structures that flow through the execution chain,
+enabling Layer 1 (filtering) and Layer 2 (enforcement) permission checks.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass(frozen=True)
+class UserSession:
+    """Minimal session carrying identity and role claims.
+
+    Immutable and hashable — safe for use as cache keys in permission resolvers.
+
+    Attributes:
+        user_id: Unique identifier for the user.
+        tenant_id: Tenant/organization identifier for multi-tenant deployments.
+        roles: Set of role claims (e.g., frozenset({'jira.manage', 'github.read'})).
+            Uses frozenset for immutability and hashability.
+        metadata: Optional additional session metadata (e.g., auth provider info).
+            Note: metadata dict contents should be immutable for cache safety.
+
+    Example:
+        >>> session = UserSession(
+        ...     user_id="user-123",
+        ...     tenant_id="acme-corp",
+        ...     roles=frozenset({'jira.write', 'github.read'})
+        ... )
+        >>> 'jira.write' in session.roles
+        True
+        >>> hash(session)  # Hashable for cache keys
+        -1234567890
+    """
+
+    user_id: str
+    tenant_id: str
+    roles: frozenset[str]
+    metadata: dict[str, Any] = field(default_factory=dict, hash=False, compare=False)
+
+    def __post_init__(self) -> None:
+        """Validate that roles is a frozenset."""
+        if not isinstance(self.roles, frozenset):
+            # Convert to frozenset if necessary (for convenience)
+            object.__setattr__(self, 'roles', frozenset(self.roles))
+
+    def has_role(self, role: str) -> bool:
+        """Check if session has a specific role.
+
+        Args:
+            role: Role name to check.
+
+        Returns:
+            True if the role is present in the session's roles.
+        """
+        return role in self.roles
+
+    def has_any_role(self, roles: set[str] | frozenset[str]) -> bool:
+        """Check if session has any of the specified roles.
+
+        Args:
+            roles: Set of role names to check.
+
+        Returns:
+            True if at least one role is present.
+        """
+        return bool(self.roles & roles)
+
+
+@dataclass
+class PermissionContext:
+    """Request-scoped wrapper grouping session with extra context.
+
+    This is the primary object passed through the permission checking pipeline.
+    It wraps an immutable UserSession with mutable request-specific metadata.
+
+    Attributes:
+        session: The underlying UserSession with identity and roles.
+        request_id: Optional request/correlation ID for tracing.
+        extra: Additional request-scoped metadata (e.g., source IP, API version).
+
+    Example:
+        >>> session = UserSession(
+        ...     user_id="user-123",
+        ...     tenant_id="acme-corp",
+        ...     roles=frozenset({'admin'})
+        ... )
+        >>> ctx = PermissionContext(
+        ...     session=session,
+        ...     request_id="req-456",
+        ...     extra={"source": "api", "version": "v2"}
+        ... )
+        >>> ctx.user_id
+        'user-123'
+        >>> ctx.roles
+        frozenset({'admin'})
+    """
+
+    session: UserSession
+    request_id: Optional[str] = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def user_id(self) -> str:
+        """Get the user ID from the underlying session."""
+        return self.session.user_id
+
+    @property
+    def tenant_id(self) -> str:
+        """Get the tenant ID from the underlying session."""
+        return self.session.tenant_id
+
+    @property
+    def roles(self) -> frozenset[str]:
+        """Get the roles from the underlying session."""
+        return self.session.roles
+
+    def has_role(self, role: str) -> bool:
+        """Check if session has a specific role.
+
+        Args:
+            role: Role name to check.
+
+        Returns:
+            True if the role is present.
+        """
+        return self.session.has_role(role)
+
+    def has_any_role(self, roles: set[str] | frozenset[str]) -> bool:
+        """Check if session has any of the specified roles.
+
+        Args:
+            roles: Set of role names to check.
+
+        Returns:
+            True if at least one role is present.
+        """
+        return self.session.has_any_role(roles)