parishad 0.1.0__py3-none-any.whl

parishad/tools/base.py

@@ -0,0 +1,57 @@
+"""
+Base classes and interfaces for Parishad tools.
+Tools enable the agent to interact with the external world (Perception and Action).
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional, Type
+from pydantic import BaseModel, Field
+
+
+class ToolResult(BaseModel):
+    """Standardized output from a tool execution."""
+    success: bool
+    data: Any  # The actual result (text, json, file path, etc.)
+    error: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class BaseTool(ABC):
+    """Abstract base class for all tools."""
+
+    name: str = "base_tool"
+    description: str = "Base tool description"
+    
+    def __init__(self, **kwargs):
+        """Initialize the tool."""
+        pass
+
+    @property
+    def schema(self) -> Dict[str, Any]:
+        """Return the JSON schema for this tool's input."""
+        # By default, can infer from the `run` method type hints if using Pydantic V2
+        # For now, subclasses should define this explicitly or we use a decorator helper
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": {
+                "type": "object",
+                "properties": {},
+            }
+        }
+
+    @abstractmethod
+    def run(self, **kwargs) -> ToolResult:
+        """Execute the tool."""
+        pass
+
+    def __call__(self, **kwargs) -> ToolResult:
+        """Syntactic sugar for running the tool."""
+        try:
+            return self.run(**kwargs)
+        except Exception as e:
+            return ToolResult(
+                success=False,
+                data=None,
+                error=str(e)
+            )

parishad/tools/fs.py

@@ -0,0 +1,110 @@
+"""
+File System Action Tool.
+Allows the agent to read, write, and navigate the file system.
+"""
+
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional, Literal
+
+from .base import BaseTool, ToolResult
+
+
+class FileSystemTool(BaseTool):
+    """
+    Tool for interacting with the file system.
+    Capabilities: read, write, list.
+    """
+    
+    name = "file_system"
+    description = "Read, write, and list files in the file system. Use this to modify code or read documentation."
+    
+    def __init__(self, working_directory: Optional[str] = None):
+        """
+        Initialize FileSystemTool.
+        
+        Args:
+            working_directory: Root directory to limit operations to (optional).
+                               If NOT set, operations are unrestricted (use with caution).
+        """
+        super().__init__()
+        self.working_directory = Path(working_directory).resolve() if working_directory else Path.cwd()
+
+    @property
+    def schema(self) -> Dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "operation": {
+                        "type": "string",
+                        "enum": ["read", "write", "list"],
+                        "description": "Operation to perform"
+                    },
+                    "path": {
+                        "type": "string",
+                        "description": "Path to the file or directory"
+                    },
+                    "content": {
+                        "type": "string",
+                        "description": "Content to write (for 'write' operation only)"
+                    }
+                },
+                "required": ["operation", "path"]
+            }
+        }
+
+    def run(self, operation: Literal["read", "write", "list"], path: str, content: Optional[str] = None) -> ToolResult:
+        """Execute file system operation."""
+        try:
+            target_path = Path(path).resolve()
+            
+            # Basic security check: ensure path is relative to working directory if strict mode desired
+            # For now, we allow absolute paths to be powerful agents, but we log usage.
+            
+            if operation == "read":
+                if not target_path.exists():
+                     return ToolResult(success=False, data=None, error=f"File not found: {path}")
+                if not target_path.is_file():
+                     return ToolResult(success=False, data=None, error=f"Not a file: {path}")
+                
+                try:
+                    text = target_path.read_text(encoding="utf-8")
+                    return ToolResult(success=True, data=text)
+                except UnicodeDecodeError:
+                    return ToolResult(success=False, data=None, error="Binary file reading not supported yet.")
+
+            elif operation == "write":
+                if content is None:
+                    return ToolResult(success=False, data=None, error="Content required for write operation.")
+                
+                # Ensure directory exists
+                target_path.parent.mkdir(parents=True, exist_ok=True)
+                target_path.write_text(content, encoding="utf-8")
+                return ToolResult(success=True, data=f"Successfully wrote {len(content)} bytes to {path}")
+
+            elif operation == "list":
+                if not target_path.exists():
+                     return ToolResult(success=False, data=None, error=f"Directory not found: {path}")
+                
+                items = []
+                if target_path.is_dir():
+                    for item in target_path.iterdir():
+                        kind = "DIR" if item.is_dir() else "FILE"
+                        items.append(f"[{kind}] {item.name}")
+                else:
+                    return ToolResult(success=False, data=None, error=f"Not a directory: {path}")
+                
+                return ToolResult(success=True, data="\n".join(sorted(items)))
+
+            else:
+                return ToolResult(success=False, data=None, error=f"Unknown operation: {operation}")
+
+        except Exception as e:
+            return ToolResult(
+                success=False,
+                data=None,
+                error=f"FileSystem error ({operation}): {str(e)}"
+            )

parishad/tools/perception.py

@@ -0,0 +1,96 @@
+"""
+Unified Perception Tool (The Eyes & Ears).
+Uses MarkItDown to convert Documents, Images, and Audio to text.
+Lightweight, no heavy model downloads.
+"""
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .base import BaseTool, ToolResult
+
+
+class PerceptionTool(BaseTool):
+    """
+    Unified tool for perceiving the world (Docs, Images, Audio).
+    Powered by Microsoft MarkItDown.
+    """
+    
+    name = "perception"
+    description = "Convert files (PDF, Docx, Images, Audio) into text. Use for reading docs or seeing images."
+    
+    def __init__(self):
+        super().__init__()
+        self._markitdown = None
+
+    def _get_markitdown(self):
+        """Lazy import."""
+        if self._markitdown is None:
+            try:
+                from markitdown import MarkItDown
+                # Initialize without LLM client by default to keep it local/free.
+                # Image description will be basic (OCR/Metadata) unless LLM is provided later.
+                self._markitdown = MarkItDown()
+            except ImportError:
+                raise ImportError(
+                    "markitdown dependency is missing. "
+                    "Install with: pip install parishad[perception]"
+                )
+        return self._markitdown
+
+    @property
+    def schema(self) -> Dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "file_path": {
+                        "type": "string",
+                        "description": "Absolute path to the file (pdf, docx, jpg, mp3, etc.)"
+                    }
+                },
+                "required": ["file_path"]
+            }
+        }
+
+    def run(self, file_path: str) -> ToolResult:
+        """Convert file to text."""
+        try:
+            path = Path(file_path)
+            if not path.exists():
+                return ToolResult(
+                    success=False,
+                    data=None,
+                    error=f"File not found: {file_path}"
+                )
+            
+            md = self._get_markitdown()
+            
+            # Convert
+            result = md.convert(str(path))
+            
+            if result and hasattr(result, "text_content"):
+                return ToolResult(
+                    success=True,
+                    data=result.text_content,
+                    metadata={
+                        "source": str(path),
+                        "format": path.suffix,
+                        "title": result.title if hasattr(result, "title") else None
+                    }
+                )
+            else:
+                 return ToolResult(
+                    success=False,
+                    data=None,
+                    error="Conversion returned empty result."
+                )
+
+        except Exception as e:
+            return ToolResult(
+                success=False,
+                data=None,
+                error=f"Perception failed: {str(e)}"
+            )

parishad/tools/retrieval.py

@@ -0,0 +1,74 @@
+"""
+Retrieval Tool (Memory Access).
+Allows agents to query the Vector Store (RDMA).
+"""
+
+from typing import Any, Dict
+
+from .base import BaseTool, ToolResult
+from ..memory import VectorStore
+
+class RetrievalTool(BaseTool):
+    """
+    Tool for searching the Agent's Long-Term Memory (Vector Store).
+    """
+    
+    name = "memory_retrieval"
+    description = "Search the council's long-term memory (codebase, docs) for relevant context."
+    
+    def __init__(self, collection_name: str = "parishad_memory"):
+        super().__init__()
+        # Initialize store
+        # Note: We share the persist_dir convention
+        self.store = VectorStore(collection_name=collection_name)
+
+    @property
+    def schema(self) -> Dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "query": {
+                        "type": "string",
+                        "description": "The search query (e.g. 'How does the ShellTool work?')"
+                    },
+                    "limit": {
+                        "type": "integer",
+                        "description": "Number of results to return (default: 5)"
+                    }
+                },
+                "required": ["query"]
+            }
+        }
+
+    def run(self, query: str, limit: int = 5) -> ToolResult:
+        """Execute retrieval."""
+        try:
+            results = self.store.query(query, n_results=limit)
+            
+            if not results:
+                return ToolResult(success=True, data="No relevant memories found.", metadata={"count": 0})
+            
+            # Format results into a readable string
+            formatted = []
+            for i, res in enumerate(results):
+                content = res['content']
+                meta = res['metadata']
+                dist = res['distance']
+                source = meta.get('source', 'unknown')
+                formatted.append(f"[{i+1}] (Source: {source}, Dist: {dist:.3f})\n{content}\n")
+                
+            return ToolResult(
+                success=True,
+                data="\n".join(formatted),
+                metadata={"count": len(results)}
+            )
+
+        except Exception as e:
+            return ToolResult(
+                success=False,
+                data=None,
+                error=f"Retrieval failed: {str(e)}"
+            )

parishad/tools/shell.py

@@ -0,0 +1,103 @@
+"""
+Shell Execution Tool.
+Allows the agent to execute system commands.
+"""
+
+import subprocess
+import shlex
+import os
+from typing import Any, Dict, Optional
+
+from .base import BaseTool, ToolResult
+
+
+class ShellTool(BaseTool):
+    """
+    Tool for executing shell commands.
+    Capabilities: run_command.
+    """
+    
+    name = "shell"
+    description = "Execute shell commands in the terminal."
+    
+    def __init__(self, timeout: int = 60, safe_mode: bool = False):
+        """
+        Initialize ShellTool.
+        
+        Args:
+            timeout: Maximum execution time in seconds.
+            safe_mode: If True, disallows potentially destructive commands (mock implementation).
+        """
+        super().__init__()
+        self.timeout = timeout
+        self.safe_mode = safe_mode
+
+    @property
+    def schema(self) -> Dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "command": {
+                        "type": "string",
+                        "description": "Shell command to execute"
+                    },
+                    "cwd": {
+                        "type": "string",
+                        "description": "Directory to execute command in (optional)"
+                    }
+                },
+                "required": ["command"]
+            }
+        }
+
+    def run(self, command: str, cwd: Optional[str] = None) -> ToolResult:
+        """Run a shell command."""
+        try:
+            if self.safe_mode:
+                # Basic blacklist (very naive, purely illustrative)
+                forbidden = ["rm -rf /", ":(){ :|:& };:"]
+                if any(f in command for f in forbidden):
+                    return ToolResult(success=False, data=None, error="Command blocked by safe mode.")
+
+            # Resolve cwd
+            working_dir = os.path.abspath(cwd) if cwd else os.getcwd()
+
+            # Execute
+            # Using shell=True is dangerous but necessary for complex commands (pipes, etc.) often used by agents
+            result = subprocess.run(
+                command,
+                shell=True,
+                cwd=working_dir,
+                capture_output=True,
+                text=True,
+                timeout=self.timeout
+            )
+            
+            output = result.stdout
+            if result.stderr:
+                output += f"\nSTDERR:\n{result.stderr}"
+            
+            if result.returncode == 0:
+                return ToolResult(success=True, data=output.strip())
+            else:
+                 return ToolResult(
+                    success=False, 
+                    data=output.strip(), 
+                    error=f"Command failed with exit code {result.returncode}"
+                )
+
+        except subprocess.TimeoutExpired:
+            return ToolResult(
+                success=False,
+                data=None,
+                error=f"Command timed out after {self.timeout}s"
+            )
+        except Exception as e:
+            return ToolResult(
+                success=False,
+                data=None,
+                error=f"Shell execution failed: {str(e)}"
+            )

parishad/utils/__init__.py

@@ -0,0 +1,7 @@
+"""Utility functions for Parishad."""
+
+from .logging import setup_logging, get_logger, truncate_for_log
+from .tracing import TraceManager
+
+
+__all__ = ["setup_logging", "get_logger", "truncate_for_log", "TraceManager"]

parishad/utils/hardware.py

@@ -0,0 +1,122 @@
+"""
+Hardware detection utility for Parishad.
+Detects system capabilities (RAM, GPU, VRAM) to populate config.json.
+"""
+import platform
+import psutil
+import subprocess
+import logging
+from dataclasses import dataclass, asdict
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+@dataclass
+class GPUInfo:
+    name: str
+    vram_gb: float
+    type: str  # "apple_silicon", "cuda", "cpu"
+
+@dataclass
+class SystemInfo:
+    os: str
+    arch: str
+    ram_gb: float
+    gpu: GPUInfo
+
+    def to_dict(self):
+        return asdict(self)
+
+def get_system_info() -> SystemInfo:
+    """Detect all system information."""
+    
+    # 1. OS & Arch
+    os_name = platform.system()
+    arch = platform.machine()
+    
+    # 2. RAM
+    try:
+        ram_bytes = psutil.virtual_memory().total
+        ram_gb = round(ram_bytes / (1024**3), 1)
+    except:
+        ram_gb = 8.0 # Fallback
+        
+    # 3. GPU Detection
+    gpu = _detect_gpu(os_name, arch, ram_gb)
+    
+    return SystemInfo(
+        os=os_name,
+        arch=arch,
+        ram_gb=ram_gb,
+        gpu=gpu
+    )
+
+def _detect_gpu(os_name: str, arch: str, system_ram_gb: float) -> GPUInfo:
+    """Detect GPU specifics."""
+    
+    # A. Apple Silicon
+    if os_name == "Darwin" and "arm" in arch.lower():
+        # Try to get specific chip name via sysctl
+        try:
+            cmd = ["sysctl", "-n", "machdep.cpu.brand_string"]
+            result = subprocess.run(cmd, capture_output=True, text=True)
+            chip_name = result.stdout.strip()
+        except:
+            chip_name = "Apple Silicon"
+            
+        return GPUInfo(
+            name=chip_name,
+            vram_gb=system_ram_gb * 0.7, # Unified memory heuristic (approx usable)
+            type="apple_silicon"
+        )
+        
+    # B. NVIDIA (Priority: Torch -> nvidia-smi)
+    
+    # 1. Try Torch execution (Most reliable for Python environment)
+    try:
+        import torch
+        if torch.cuda.is_available():
+             vram_gb = torch.cuda.get_device_properties(0).total_memory / (1024**3)
+             return GPUInfo(
+                name=torch.cuda.get_device_name(0),
+                vram_gb=round(vram_gb, 1),
+                type="cuda"
+            )
+    except ImportError:
+        pass
+
+    # 2. Try nvidia-smi (System level)
+    try:
+        # Check standard paths on Windows if not in PATH
+        smi_cmd = "nvidia-smi"
+        if os_name == "Windows":
+             import shutil
+             if not shutil.which("nvidia-smi"):
+                 # Common install path
+                 candidate = r"C:\Windows\System32\nvidia-smi.exe"
+                 if os.path.exists(candidate):
+                     smi_cmd = candidate
+        
+        # Query details
+        cmd = [smi_cmd, "--query-gpu=name,memory.total", "--format=csv,noheader,nounits"]
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        if result.returncode == 0:
+            lines = result.stdout.strip().split('\n')
+            if lines:
+                parts = lines[0].split(',')
+                name = parts[0].strip()
+                vram_mb = float(parts[1].strip())
+                return GPUInfo(
+                    name=name,
+                    vram_gb=round(vram_mb / 1024, 1),
+                    type="cuda"
+                )
+    except Exception as e:
+        logger.debug(f"nvidia-smi check failed: {e}")
+        
+    # C. Fallback CPU
+    return GPUInfo(
+        name="CPU",
+        vram_gb=0.0,
+        type="cpu"
+    )

parishad/utils/logging.py

@@ -0,0 +1,79 @@
+"""Logging configuration for Parishad."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Optional
+
+
+# Default truncation limits for memory-efficient logging
+DEFAULT_TRUNCATE_LENGTH = 512
+MAX_TRUNCATE_LENGTH = 2048
+
+
+def truncate_for_log(text: str, max_length: int = DEFAULT_TRUNCATE_LENGTH) -> str:
+    """
+    Truncate a string for logging to avoid large memory allocations.
+    
+    Args:
+        text: The text to truncate
+        max_length: Maximum length before truncation (default: 512)
+        
+    Returns:
+        Truncated string with ellipsis if over limit, original otherwise
+    """
+    if len(text) <= max_length:
+        return text
+    return text[:max_length] + f"... [truncated, {len(text)} total chars]"
+
+
+def setup_logging(
+    level: str = "INFO",
+    log_file: Optional[str] = None,
+    format_string: Optional[str] = None
+) -> None:
+    """
+    Set up logging for Parishad.
+    
+    Args:
+        level: Logging level (DEBUG, INFO, WARNING, ERROR)
+        log_file: Optional file path to write logs to
+        format_string: Optional custom format string
+    """
+    if format_string is None:
+        format_string = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    
+    # Create formatter
+    formatter = logging.Formatter(format_string)
+    
+    # Get root logger for parishad
+    logger = logging.getLogger("parishad")
+    logger.setLevel(getattr(logging, level.upper()))
+    
+    # Clear existing handlers
+    logger.handlers.clear()
+    
+    # Console handler
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setFormatter(formatter)
+    logger.addHandler(console_handler)
+    
+    # File handler if specified
+    if log_file:
+        file_handler = logging.FileHandler(log_file)
+        file_handler.setFormatter(formatter)
+        logger.addHandler(file_handler)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Get a logger for a Parishad module.
+    
+    Args:
+        name: Module name (e.g., "orchestrator", "roles.refiner")
+        
+    Returns:
+        Logger instance
+    """
+    return logging.getLogger(f"parishad.{name}")