parishad 0.1.0__py3-none-any.whl

parishad/roles/dandadhyaksha.py

@@ -0,0 +1,163 @@
+"""
+Dandadhyaksha (Enforcer/Safety Checker) role for the Parishad council.
+Checks for safety violations, PII, and policy compliance.
+"""
+
+from typing import Any, Optional
+
+from .base import (
+    Role,
+    RoleInput,
+    RoleOutput,
+    Slot,
+    Verdict,
+    CheckerFlag,
+)
+
+
+CHECKER_SAFETY_SYSTEM_PROMPT = """You are Dandadhyaksha, the Enforcer in the Parishad council. Your job is to verify the output is safe, policy-compliant, and free of sensitive information.
+
+Your responsibilities:
+1. Check for harmful, offensive, or inappropriate content
+2. Identify any personally identifiable information (PII)
+3. Verify compliance with content policies
+4. Flag potential safety or ethical concerns
+5. Suggest redactions or modifications for safety issues
+
+You must ALWAYS respond with a valid JSON object in the following format:
+```json
+{
+  "flags": [
+    {
+      "type": "safety_violation|pii_detected|policy_violation|unsafe_code",
+      "severity": "medium|high|critical",
+      "detail": "Description of the safety issue",
+      "location": "Where it appears",
+      "suggested_fix": "Redaction or modification"
+    }
+  ],
+  "must_fix": true,
+  "safe": false,
+  "summary": "Safety assessment summary"
+}
+```
+
+If "safe" is false, "must_fix" MUST be true.
+Be extremely vigilant about PII (names, emails, phones, keys) and harmful content."""
+
+
+CHECKER_SAFETY_USER_TEMPLATE = """Perform a safety check on the following output.
+
+OUTPUT TO CHECK:
+{candidate}
+
+Analyze for safety/PII violations. Respond with ONLY a valid JSON object."""
+
+
+class Dandadhyaksha(Role):
+    """
+    Dandadhyaksha (Enforcer) checks for safety violations and PII.
+    
+    - Slot: SMALL (2-4B)
+    - Purpose: Safety and policy enforcement
+    - Output: Verdict on safety
+    """
+    
+    name = "dandadhyaksha"
+    default_slot = Slot.SMALL
+    
+    def __init__(
+        self, 
+        model_runner: Any,
+        tools: Optional[list[str]] = None,
+        **kwargs
+    ):
+        super().__init__(
+            model_runner=model_runner,
+            slot=kwargs.get("slot", Slot.SMALL),
+            max_tokens=kwargs.get("max_tokens", 512),
+            temperature=kwargs.get("temperature", 0.1)
+        )
+        self.tools = tools or ["toxicity_detector", "pii_scanner"]
+    
+    @property
+    def system_prompt(self) -> str:
+        return CHECKER_SAFETY_SYSTEM_PROMPT
+    
+    def format_input(self, role_input: RoleInput) -> str:
+        candidate_str = self._format_candidate(role_input.candidate)
+        
+        return CHECKER_SAFETY_USER_TEMPLATE.format(
+            candidate=candidate_str
+        )
+    
+    def _format_candidate(self, candidate: Optional[dict]) -> str:
+        """Format candidate output for checking."""
+        if not candidate:
+            return "No output to verify."
+        
+        content = candidate.get("content", "")
+        # Don't truncate too much for safety check, but respect limit
+        if len(content) > 4000:
+            content = content[:4000] + "... [truncated]"
+        
+        return f"""Content:
+{content}"""
+    
+    def parse_output(self, raw_output: str) -> dict[str, Any]:
+        """Parse LLM output into safety verdict dict."""
+        import json
+        import re
+        
+        # Try to extract JSON from the response
+        json_match = re.search(r'\{[\s\S]*\}', raw_output)
+        if json_match:
+            try:
+                data = json.loads(json_match.group())
+            except json.JSONDecodeError:
+                data = {}
+        else:
+            data = {}
+        
+        # Normalize flags
+        flags = []
+        for flag in data.get("flags", []):
+            flags.append({
+                "type": flag.get("type", "unknown"),
+                "severity": self._normalize_severity(flag.get("severity", "medium")),
+                "detail": flag.get("detail", ""),
+                "location": flag.get("location"),
+                "suggested_fix": flag.get("suggested_fix")
+            })
+        
+        # Determine must_fix
+        must_fix = data.get("must_fix", False)
+        safe = data.get("safe", True)
+        
+        if not safe:
+            must_fix = True
+        
+        # If flags exist, ensure must_fix matches severity
+        if flags and any(f["severity"] in ["high", "critical"] for f in flags):
+            must_fix = True
+            safe = False
+        
+        return {
+            "verdict_safety": {
+                "flags": flags,
+                "must_fix": must_fix,
+                "safe": safe,
+                "summary": data.get("summary", "")
+            },
+            # Compatible with standard Verdict schema
+            "flags": flags,
+            "must_fix": must_fix,
+            "evidence": [],
+            "overall_confidence": 1.0 if safe else 0.0
+        }
+    
+    def _normalize_severity(self, value: str) -> str:
+        """Normalize severity to valid enum value."""
+        valid = {"low", "medium", "high", "critical"}
+        normalized = value.lower().strip()
+        return normalized if normalized in valid else "high"

parishad/roles/darbari.py

@@ -0,0 +1,246 @@
+"""
+Darbari (Communicator/Refiner) role for the Parishad council.
+Normalizes user input into structured task specifications.
+"""
+
+from typing import Any, Optional
+
+from .base import (
+    Role,
+    RoleInput,
+    RoleOutput,
+    Slot,
+    TaskSpec,
+    Difficulty,
+    TaskType,
+    OutputFormat,
+)
+
+
+REFINER_SYSTEM_PROMPT = """You are Darbari, the Communicator in the Parishad council. Your job is to carefully analyze user queries and transform them into clear, structured task specifications.
+
+Your responsibilities:
+1. Understand the user's true intent and goal
+2. Identify constraints (explicit or implicit)
+3. Determine the expected output format
+4. Estimate task difficulty for routing
+5. Classify the task type
+6. Assess safety sensitivity and expected answer length
+
+You must ALWAYS respond with a valid JSON object in the following format:
+```json
+{
+  "problem": "A clear, normalized restatement of what the user wants",
+  "constraints": ["List of constraints or requirements"],
+  "output_format": "code|text|numeric|structured|mixed",
+  "difficulty_guess": "easy|medium|hard",
+  "task_type": "math|code|qa|explanation|creative|analysis|chat",
+  "key_concepts": ["Key concepts or topics involved"],
+  "safety_sensitivity": "low|medium|high",
+  "expected_answer_length": "short|paragraph|long"
+}
+```
+
+Guidelines for difficulty estimation:
+- EASY: Simple, single-step tasks; short answers; basic operations
+- MEDIUM: Multi-step but straightforward; moderate reasoning needed
+- HARD: Complex reasoning; multiple interconnected parts; edge cases; ambiguity
+
+Guidelines for task type:
+- CODE: Writing, debugging, or explaining code
+- MATH: Numerical computation, word problems, proofs
+- QA: Factual questions requiring knowledge retrieval
+- EXPLANATION: Explaining concepts, processes, or ideas
+- CREATIVE: Open-ended generation, writing, brainstorming
+- ANALYSIS: Analyzing data, text, or situations
+- CHAT: Conversational, no specific goal
+
+Guidelines for safety sensitivity:
+- LOW: Neutral topics, no harmful content
+- MEDIUM: Potentially controversial or sensitive topics
+- HIGH: Medical/legal advice, harmful content, misinformation risk
+
+Guidelines for expected answer length:
+- SHORT: 1-3 sentences, concise answer
+- PARAGRAPH: 1-2 paragraphs, moderate detail
+- LONG: Multi-paragraph, comprehensive explanation
+
+Be precise and concise. Focus on extracting the essential requirements."""
+
+
+REFINER_USER_TEMPLATE = """Analyze the following user query and create a structured task specification.
+
+USER QUERY:
+{user_query}
+
+Respond with ONLY a valid JSON object following the required schema."""
+
+
+class Darbari(Role):
+    """
+    Darbari (Communicator) normalizes user input into structured task specifications.
+    
+    - Slot: SMALL (2-4B)
+    - Purpose: First role in pipeline, sets up context for all subsequent roles
+    - Output: TaskSpec with problem, constraints, format, difficulty, type
+    """
+    
+    name = "darbari"
+    default_slot = Slot.SMALL
+    
+    def __init__(self, model_runner: Any, **kwargs):
+        super().__init__(
+            model_runner=model_runner,
+            slot=kwargs.get("slot", Slot.SMALL),
+            max_tokens=kwargs.get("max_tokens", 512),
+            temperature=kwargs.get("temperature", 0.3)
+        )
+    
+    @property
+    def system_prompt(self) -> str:
+        return REFINER_SYSTEM_PROMPT
+    
+    def format_input(self, role_input: RoleInput) -> str:
+        return REFINER_USER_TEMPLATE.format(
+            user_query=role_input.user_query
+        )
+    
+    def parse_output(self, raw_output: str) -> dict[str, Any]:
+        """Parse LLM output into TaskSpec dict with routing metadata and robust fallback."""
+        raw = raw_output.strip()
+        
+        # Handle empty output
+        if not raw:
+            logger.warning("Darbari received empty output from model")
+            return {
+                "problem": "",
+                "constraints": [],
+                "output_format": "text",
+                "difficulty_guess": "medium",
+                "task_type": "qa",
+                "key_concepts": [],
+                "difficulty": "medium",
+                "safety_sensitivity": "low",
+                "expected_answer_length": "paragraph",
+                "parse_status": "empty"
+            }
+        
+        try:
+            data = self._extract_json(raw)
+            
+            # Check if JSON parsing succeeded or fell back to raw_output
+            has_structure = "problem" in data or "task_type" in data
+            if not has_structure and "raw_output" in data:
+                # Fallback: extract problem from raw text
+                problem_text = data["raw_output"][:500]
+                parse_status = "fallback_text"
+            else:
+                problem_text = data.get("problem", "")
+                parse_status = "json_ok"
+            
+            # Validate and normalize fields
+            output = {
+                "problem": problem_text,
+                "constraints": data.get("constraints", []),
+                "output_format": self._normalize_output_format(data.get("output_format", "text")),
+                "difficulty_guess": self._normalize_difficulty(data.get("difficulty_guess", "medium")),
+                "task_type": self._normalize_task_type(data.get("task_type", "qa")),
+                "key_concepts": data.get("key_concepts", []),
+                # Routing metadata for adaptive pipeline
+                "difficulty": self._normalize_difficulty(data.get("difficulty_guess", "medium")),
+                "safety_sensitivity": self._normalize_safety(data.get("safety_sensitivity", "low")),
+                "expected_answer_length": self._normalize_length(data.get("expected_answer_length", "paragraph")),
+                "parse_status": parse_status,
+                "raw_output": raw
+            }
+            
+            # If problem is still empty, use raw output
+            if not output["problem"]:
+                output["problem"] = raw[:500]
+            
+            return output
+            
+        except Exception as e:
+            logger.exception("Darbari.parse_output: unexpected error during parsing")
+            # Return minimal valid structure
+            return {
+                "problem": raw[:500] if raw else "",
+                "constraints": [],
+                "output_format": "text",
+                "difficulty_guess": "medium",
+                "task_type": "qa",
+                "key_concepts": [],
+                "difficulty": "medium",
+                "safety_sensitivity": "low",
+                "expected_answer_length": "paragraph",
+                "parse_status": "error_fallback",
+                "raw_output": raw
+            }
+    
+    def _normalize_output_format(self, value: str) -> str:
+        """Normalize output format to valid enum value."""
+        valid = {"code", "text", "numeric", "structured", "mixed"}
+        normalized = value.lower().strip()
+        return normalized if normalized in valid else "text"
+    
+    def _normalize_difficulty(self, value: str) -> str:
+        """Normalize difficulty to valid enum value."""
+        valid = {"easy", "medium", "hard"}
+        normalized = value.lower().strip()
+        return normalized if normalized in valid else "medium"
+    
+    def _normalize_task_type(self, value: str) -> str:
+        """Normalize task type to valid enum value."""
+        valid = {"math", "code", "qa", "explanation", "creative", "analysis", "chat"}
+        normalized = value.lower().strip()
+        
+        # Handle common aliases
+        aliases = {
+            "coding": "code",
+            "programming": "code",
+            "mathematics": "math",
+            "calculation": "math",
+            "question": "qa",
+            "factual": "qa",
+            "explain": "explanation",
+            "describe": "explanation",
+            "write": "creative",
+            "generate": "creative",
+            "analyze": "analysis",
+            "evaluate": "analysis",
+            "conversation": "chat",
+            "conversational": "chat"
+        }
+        
+        if normalized in valid:
+            return normalized
+        return aliases.get(normalized, "qa")
+    
+    def _normalize_safety(self, value: str) -> str:
+        """Normalize safety sensitivity to valid value."""
+        valid = {"low", "medium", "high"}
+        normalized = value.lower().strip()
+        return normalized if normalized in valid else "low"
+    
+    def _normalize_length(self, value: str) -> str:
+        """Normalize expected answer length to valid value."""
+        valid = {"short", "paragraph", "long"}
+        normalized = value.lower().strip()
+        return normalized if normalized in valid else "paragraph"
+    
+    def create_task_spec(self, role_input: RoleInput) -> TaskSpec:
+        """
+        Execute Refiner and return a TaskSpec object.
+        """
+        output = self(role_input)
+        
+        if output.status == "error":
+            # Return default task spec on error
+            return TaskSpec(
+                problem=role_input.user_query,
+                difficulty_guess=Difficulty.MEDIUM,
+                task_type=TaskType.QA,
+                output_format=OutputFormat.TEXT
+            )
+        
+        return TaskSpec.from_dict(output.core_output)

parishad/roles/majumdar.py

@@ -0,0 +1,274 @@
+"""
+Majumdar (Planner) role for the Parishad council.
+Decomposes complex tasks into clear, executable steps.
+"""
+
+from typing import Any, Optional
+
+from .base import (
+    Role,
+    RoleInput,
+    RoleOutput,
+    Slot,
+    Plan,
+    PlanStep,
+)
+
+
+PLANNER_SYSTEM_PROMPT = """You are Majumdar, the Planner in the Parishad council. Your job is to decompose complex tasks into clear, executable steps that the Implementor can follow.
+
+Your responsibilities:
+1. Analyze the task specification
+2. Break down the problem into logical, sequential steps
+3. Provide rationale for each step
+4. Identify critical checkpoints where verification is needed
+5. Estimate the complexity of execution
+
+You must ALWAYS respond with a valid JSON object in the following format:
+```json
+{
+  "steps": [
+    {
+      "id": 1,
+      "description": "What to do in this step",
+      "rationale": "Why this step is needed",
+      "expected_output": "What this step should produce",
+      "depends_on": []
+    }
+  ],
+  "checkpoints": [1, 3],
+  "expected_output_type": "python_function|explanation|numeric_answer|structured_data",
+  "complexity_estimate": "trivial|simple|moderate|complex|very_complex",
+  "suggested_approach": "High-level strategy for the Implementor"
+}
+```
+
+Guidelines:
+- Keep steps atomic and actionable
+- Steps should be independent where possible
+- Identify dependencies between steps accurately
+- Mark steps that need verification as checkpoints
+
+For code tasks:
+- Include steps for understanding requirements, implementing, and testing
+- Consider edge cases and error handling
+
+For math tasks:
+- Break down into clear mathematical operations
+- Include verification steps for intermediate results
+
+For QA tasks:
+- Identify what information needs to be retrieved
+- Include steps for synthesizing information into an answer"""
+
+
+PLANNER_USER_TEMPLATE = """Create an execution plan for the following task.
+
+ORIGINAL QUERY:
+{user_query}
+
+TASK SPECIFICATION:
+{task_spec}
+
+Create a detailed step-by-step plan. Respond with ONLY a valid JSON object."""
+
+
+class Majumdar(Role):
+    """
+    Majumdar (Planner) decomposes tasks into executable steps.
+    
+    - Slot: BIG (13-34B), with MID fallback for easy tasks
+    - Purpose: Create structured plan for Implementor to execute
+    - Output: Plan with steps, checkpoints, complexity estimate
+    """
+    
+    name = "majumdar"
+    default_slot = Slot.BIG
+    
+    def __init__(
+        self, 
+        model_runner: Any,
+        fallback_slot: Optional[Slot] = Slot.MID,
+        **kwargs
+    ):
+        super().__init__(
+            model_runner=model_runner,
+            slot=kwargs.get("slot", Slot.BIG),
+            max_tokens=kwargs.get("max_tokens", 1024),
+            temperature=kwargs.get("temperature", 0.5)
+        )
+        self.fallback_slot = fallback_slot
+    
+    @property
+    def system_prompt(self) -> str:
+        return PLANNER_SYSTEM_PROMPT
+    
+    def format_input(self, role_input: RoleInput) -> str:
+        task_spec_str = self._format_task_spec(role_input.task_spec)
+        
+        return PLANNER_USER_TEMPLATE.format(
+            user_query=role_input.user_query,
+            task_spec=task_spec_str
+        )
+    
+    def _format_task_spec(self, task_spec: Optional[dict]) -> str:
+        """Format task spec for inclusion in prompt."""
+        if not task_spec:
+            return "No task specification provided."
+        
+        lines = [
+            f"Problem: {task_spec.get('problem', 'Not specified')}",
+            f"Task Type: {task_spec.get('task_type', 'Unknown')}",
+            f"Output Format: {task_spec.get('output_format', 'text')}",
+            f"Difficulty: {task_spec.get('difficulty_guess', 'medium')}",
+        ]
+        
+        constraints = task_spec.get('constraints', [])
+        if constraints:
+            lines.append(f"Constraints: {', '.join(constraints)}")
+        
+        concepts = task_spec.get('key_concepts', [])
+        if concepts:
+            lines.append(f"Key Concepts: {', '.join(concepts)}")
+        
+        return "\n".join(lines)
+    
+    def parse_output(self, raw_output: str) -> dict[str, Any]:
+        """Parse LLM output into Plan dict with robust fallback."""
+        raw = raw_output.strip()
+        
+        # Handle empty output
+        if not raw:
+            logger.warning("Majumdar received empty output from model")
+            return {
+                "steps": [{
+                    "id": 1,
+                    "description": "Complete the task",
+                    "rationale": "Default step",
+                    "expected_output": "Result",
+                    "depends_on": []
+                }],
+                "checkpoints": [],
+                "expected_output_type": "text",
+                "complexity_estimate": "moderate",
+                "suggested_approach": "",
+                "parse_status": "empty"
+            }
+        
+        try:
+            data = self._extract_json(raw)
+            
+            # Normalize steps
+            steps = []
+            raw_steps = data.get("steps", [])
+            
+            for i, step in enumerate(raw_steps):
+                if isinstance(step, dict):
+                    steps.append({
+                        "id": step.get("id", i + 1),
+                        "description": step.get("description", ""),
+                        "rationale": step.get("rationale", ""),
+                        "expected_output": step.get("expected_output", ""),
+                        "depends_on": step.get("depends_on", [])
+                    })
+                elif isinstance(step, str):
+                    steps.append({
+                        "id": i + 1,
+                        "description": step,
+                        "rationale": "",
+                        "expected_output": "",
+                        "depends_on": []
+                    })
+            
+            # Fallback: if no steps found, create default step
+            if not steps:
+                has_structure = "steps" in data or "checkpoints" in data
+                if not has_structure and "raw_output" in data:
+                    # Model didn't follow format - create simple plan from text
+                    steps = [{
+                        "id": 1,
+                        "description": data["raw_output"][:200],
+                        "rationale": "Extracted from model output",
+                        "expected_output": "Completion",
+                        "depends_on": []
+                    }]
+                    parse_status = "fallback_text"
+                else:
+                    steps = [{
+                        "id": 1,
+                        "description": "Complete the task as specified",
+                        "rationale": "Single-step execution",
+                        "expected_output": "Final result",
+                        "depends_on": []
+                    }]
+                    parse_status = "default_plan"
+            else:
+                parse_status = "json_ok"
+            
+            return {
+                "steps": steps,
+                "checkpoints": data.get("checkpoints", []),
+                "expected_output_type": data.get("expected_output_type", "text"),
+                "complexity_estimate": self._normalize_complexity(
+                    data.get("complexity_estimate", "moderate")
+                ),
+                "suggested_approach": data.get("suggested_approach", ""),
+                "parse_status": parse_status,
+                "raw_output": raw
+            }
+            
+        except Exception as e:
+            logger.exception("Majumdar.parse_output: unexpected error during parsing")
+            # Return minimal valid plan
+            return {
+                "steps": [{
+                    "id": 1,
+                    "description": raw[:200] if raw else "Execute task",
+                    "rationale": "Fallback plan",
+                    "expected_output": "Result",
+                    "depends_on": []
+                }],
+                "checkpoints": [],
+                "expected_output_type": "text",
+                "complexity_estimate": "moderate",
+                "suggested_approach": "",
+                "parse_status": "error_fallback",
+                "raw_output": raw
+            }
+    
+    def _normalize_complexity(self, value: str) -> str:
+        """Normalize complexity to valid enum value."""
+        valid = {"trivial", "simple", "moderate", "complex", "very_complex"}
+        normalized = value.lower().strip().replace(" ", "_")
+        return normalized if normalized in valid else "moderate"
+    
+    def should_use_fallback(self, task_spec: Optional[dict]) -> bool:
+        """Determine if we should use fallback slot based on difficulty."""
+        if not task_spec:
+            return False
+        difficulty = task_spec.get("difficulty_guess", "medium")
+        return difficulty == "easy"
+    
+    def __call__(self, role_input: RoleInput) -> Any:
+        """Execute planner with potential slot fallback."""
+        if self.fallback_slot and self.should_use_fallback(role_input.task_spec):
+            original_slot = self.slot
+            self.slot = self.fallback_slot
+            try:
+                return super().__call__(role_input)
+            finally:
+                self.slot = original_slot
+        
+        return super().__call__(role_input)
+    
+    def create_plan(self, role_input: RoleInput) -> Plan:
+        """Execute planner and return a Plan object."""
+        output = self(role_input)
+        
+        if output.status == "error":
+            return Plan(
+                steps=[PlanStep(id=1, description="Complete the task")],
+                expected_output_type="text"
+            )
+        
+        return Plan.from_dict(output.core_output)