prompture 0.0.50.dev1__py3-none-any.whl → 0.0.51.dev1__py3-none-any.whl

prompture/__init__.py

@@ -8,6 +8,7 @@ from .agent_types import (
     AgentResult,
     AgentState,
     AgentStep,
+    ApprovalRequired,
     GuardrailError,
     ModelRetry,
     RunContext,
@@ -15,6 +16,15 @@ from .agent_types import (
     StreamEvent,
     StreamEventType,
 )
+from .analysis import (
+    CodeAnalysis,
+    CodeFeatures,
+    FeatureExtractor,
+    RiskAssessment,
+    RiskLevel,
+    analyze_python,
+    calculate_risk,
+)
 from .async_agent import AsyncAgent, AsyncAgentIterator, AsyncStreamedAgentResult
 from .async_conversation import AsyncConversation
 from .async_driver import AsyncDriver
@@ -106,6 +116,14 @@ from .groups import (
     RouterAgent,
     SequentialGroup,
 )
+from .history import (
+    calculate_cost_breakdown,
+    export_result_json,
+    filter_steps,
+    get_tool_call_summary,
+    result_to_dict,
+    search_messages,
+)
 from .image import (
     ImageContent,
     ImageInput,
@@ -141,6 +159,20 @@ from .persona import (
     reset_trait_registry,
 )
 from .runner import run_suite_from_spec
+from .sandbox import (
+    ALWAYS_BLOCKED_IMPORTS,
+    ImportRestrictions,
+    ImportViolationError,
+    PathRestrictions,
+    PathViolationError,
+    PythonSandbox,
+    ResourceContext,
+    ResourceLimitError,
+    ResourceLimits,
+    SandboxError,
+    SandboxResult,
+    SandboxTimeoutError,
+)
 from .serialization import (
     EXPORT_VERSION,
     export_conversation,
@@ -183,6 +215,9 @@ except Exception:
     __version__ = "0.0.0"
 
 __all__ = [
+    # Sandbox module
+    "ALWAYS_BLOCKED_IMPORTS",
+    # Core exports
     "EXPORT_VERSION",
     "FIELD_DEFINITIONS",
     "PERSONAS",
@@ -194,6 +229,7 @@ __all__ = [
     "AgentState",
     "AgentStep",
     "AirLLMDriver",
+    "ApprovalRequired",
     "AsyncAgent",
     "AsyncAgentIterator",
     "AsyncConversation",
@@ -205,11 +241,15 @@ __all__ = [
     "AzureDriver",
     "CacheBackend",
     "ClaudeDriver",
+    # Analysis module
+    "CodeAnalysis",
+    "CodeFeatures",
     "Conversation",
     "ConversationStore",
     "Driver",
     "DriverCallbacks",
     "ErrorPolicy",
+    "FeatureExtractor",
     "GoogleDriver",
     "GrokDriver",
     "GroqDriver",
@@ -220,6 +260,8 @@ __all__ = [
     "GuardrailError",
     "ImageContent",
     "ImageInput",
+    "ImportRestrictions",
+    "ImportViolationError",
     "JSONFormatter",
     "LMStudioDriver",
     "LocalHTTPDriver",
@@ -232,12 +274,23 @@ __all__ = [
     "OpenAIDriver",
     "OpenRouterDriver",
     "ParallelGroup",
+    "PathRestrictions",
+    "PathViolationError",
     "Persona",
+    "PythonSandbox",
     "RedisCacheBackend",
+    "ResourceContext",
+    "ResourceLimitError",
+    "ResourceLimits",
     "ResponseCache",
+    "RiskAssessment",
+    "RiskLevel",
     "RouterAgent",
     "RunContext",
     "SQLiteCacheBackend",
+    "SandboxError",
+    "SandboxResult",
+    "SandboxTimeoutError",
     "SequentialGroup",
     "StepType",
     "StreamEvent",
@@ -248,7 +301,11 @@ __all__ = [
     "UsageSession",
     "add_field_definition",
     "add_field_definitions",
+    "analyze_python",
     "ask_for_json",
+    # History module
+    "calculate_cost_breakdown",
+    "calculate_risk",
     "clean_json_text",
     "clean_json_text_with_ai",
     "clean_toon_text",
@@ -258,12 +315,14 @@ __all__ = [
     "configure_cache",
     "configure_logging",
     "export_conversation",
+    "export_result_json",
     "export_usage_session",
     "extract_and_jsonify",
     "extract_from_data",
     "extract_from_pandas",
     "extract_with_model",
     "field_from_registry",
+    "filter_steps",
     "get_available_models",
     "get_cache",
     "get_driver",
@@ -279,6 +338,7 @@ __all__ = [
     "get_recently_used_models",
     "get_registry_snapshot",
     "get_required_fields",
+    "get_tool_call_summary",
     "get_trait",
     "get_trait_names",
     "image_from_base64",
@@ -307,7 +367,9 @@ __all__ = [
     "reset_persona_registry",
     "reset_registry",
     "reset_trait_registry",
+    "result_to_dict",
     "run_suite_from_spec",
+    "search_messages",
     "set_azure_config_resolver",
     "stepwise_extract_with_model",
     "tool_from_function",

prompture/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.50.dev1'
-__version_tuple__ = version_tuple = (0, 0, 50, 'dev1')
+__version__ = version = '0.0.51.dev1'
+__version_tuple__ = version_tuple = (0, 0, 51, 'dev1')
 
 __commit_id__ = commit_id = None

prompture/agent.py

@@ -30,6 +30,7 @@ from .agent_types import (
     AgentResult,
     AgentState,
     AgentStep,
+    ApprovalRequired,
     DepsType,
     ModelRetry,
     RunContext,
@@ -338,6 +339,26 @@ class Agent(Generic[DepsType]):
                             result = _fn(ctx, **kwargs)
                         else:
                             result = _fn(**kwargs)
+                    except ApprovalRequired as exc:
+                        # Handle approval request
+                        if _cb.on_approval_needed:
+                            approved = _cb.on_approval_needed(exc.tool_name, exc.action, exc.details)
+                            if approved:
+                                # Retry the tool call after approval
+                                try:
+                                    if _wants:
+                                        result = _fn(ctx, **kwargs)
+                                    else:
+                                        result = _fn(**kwargs)
+                                except ApprovalRequired:
+                                    # Tool raised ApprovalRequired again - don't loop
+                                    result = f"Error: Tool '{_name}' requires approval but approval was already granted"
+                                except ModelRetry as retry_exc:
+                                    result = f"Error: {retry_exc.message}"
+                            else:
+                                result = f"Error: Tool '{_name}' execution denied - approval required: {exc.action}"
+                        else:
+                            result = f"Error: Tool '{_name}' requires approval but no approval handler is configured"
                     except ModelRetry as exc:
                         result = f"Error: {exc.message}"
                     if _cb.on_tool_end:
@@ -607,12 +628,28 @@ class Agent(Generic[DepsType]):
         all_tool_calls: list[dict[str, Any]],
     ) -> None:
         """Scan conversation messages and populate steps and tool_calls."""
+
         now = time.time()
 
         for msg in messages:
             role = msg.get("role", "")
 
             if role == "assistant":
+                content = msg.get("content", "") or ""
+
+                # Extract thinking content from <think> tags
+                thinking_text = self._extract_thinking(content)
+                if thinking_text and self._agent_callbacks.on_thinking:
+                    self._agent_callbacks.on_thinking(thinking_text)
+                    # Also record as a think step
+                    steps.append(
+                        AgentStep(
+                            step_type=StepType.think,
+                            timestamp=now,
+                            content=thinking_text,
+                        )
+                    )
+
                 tc_list = msg.get("tool_calls", [])
                 if tc_list:
                     # Assistant message with tool calls
@@ -632,7 +669,7 @@ class Agent(Generic[DepsType]):
                             AgentStep(
                                 step_type=StepType.tool_call,
                                 timestamp=now,
-                                content=msg.get("content", ""),
+                                content=content,
                                 tool_name=name,
                                 tool_args=args,
                             )
@@ -644,7 +681,7 @@ class Agent(Generic[DepsType]):
                         AgentStep(
                             step_type=StepType.output,
                             timestamp=now,
-                            content=msg.get("content", ""),
+                            content=content,
                         )
                     )
 
@@ -658,6 +695,28 @@ class Agent(Generic[DepsType]):
                     )
                 )
 
+    def _extract_thinking(self, content: str) -> str | None:
+        """Extract thinking content from <think> tags.
+
+        Some models (like DeepSeek, Qwen) emit chain-of-thought reasoning
+        within <think>...</think> tags. This method extracts that content.
+
+        Args:
+            content: The assistant message content.
+
+        Returns:
+            The thinking text if found, None otherwise.
+        """
+        import re
+
+        # Match <think>...</think> tags (case-insensitive, allows multiline)
+        pattern = r"<think>(.*?)</think>"
+        matches = re.findall(pattern, content, re.DOTALL | re.IGNORECASE)
+        if matches:
+            # Join multiple thinking blocks with newlines
+            return "\n".join(match.strip() for match in matches)
+        return None
+
     def _parse_output(
         self,
         conv: Conversation,

prompture/agent_types.py

@@ -6,8 +6,10 @@ Defines enums, dataclasses, and exceptions used by :class:`~prompture.agent.Agen
 from __future__ import annotations
 
 import enum
+import json
 from collections.abc import Callable
 from dataclasses import dataclass, field
+from datetime import datetime, timezone
 from typing import Any, Generic, TypeVar
 
 DepsType = TypeVar("DepsType")
@@ -51,6 +53,33 @@ class GuardrailError(Exception):
         super().__init__(message)
 
 
+class ApprovalRequired(Exception):
+    """Raised by tools that require human approval before execution.
+
+    When a tool raises this exception, the agent will invoke the
+    ``on_approval_needed`` callback if configured. If the callback
+    returns True, the tool will be executed; if False, the tool
+    execution will be skipped and an error message returned to the LLM.
+
+    Attributes:
+        tool_name: Name of the tool requesting approval.
+        action: Description of the action requiring approval.
+        details: Additional details about what will be executed.
+    """
+
+    def __init__(
+        self,
+        tool_name: str,
+        action: str,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        self.tool_name = tool_name
+        self.action = action
+        self.details = details or {}
+        message = f"Tool '{tool_name}' requires approval: {action}"
+        super().__init__(message)
+
+
 @dataclass
 class RunContext(Generic[DepsType]):
     """Dependency-injection context available to tools and guardrails.
@@ -83,6 +112,19 @@ class AgentCallbacks:
     Fired at the logical agent layer (steps, tool invocations, output),
     separate from :class:`~prompture.callbacks.DriverCallbacks` which
     fires at the HTTP/driver layer.
+
+    Attributes:
+        on_step: Called for each step during execution.
+        on_tool_start: Called before a tool is invoked with (name, args).
+        on_tool_end: Called after a tool completes with (name, result).
+        on_iteration: Called at the start of each iteration with the index.
+        on_output: Called when the agent produces final output.
+        on_thinking: Called when the agent emits thinking/reasoning content.
+            The callback receives the thinking text (e.g., content within
+            <think> tags for models that support chain-of-thought).
+        on_approval_needed: Called when a tool raises ApprovalRequired.
+            The callback receives (tool_name, action, details) and should
+            return True to approve execution or False to deny.
     """
 
     on_step: Callable[[AgentStep], None] | None = None
@@ -90,6 +132,8 @@ class AgentCallbacks:
     on_tool_end: Callable[[str, Any], None] | None = None
     on_iteration: Callable[[int], None] | None = None
     on_output: Callable[[AgentResult], None] | None = None
+    on_thinking: Callable[[str], None] | None = None
+    on_approval_needed: Callable[[str, str, dict[str, Any]], bool] | None = None
 
 
 @dataclass
@@ -130,6 +174,60 @@ class AgentResult:
     state: AgentState = AgentState.idle
     run_usage: dict[str, Any] = field(default_factory=dict)
 
+    def to_dict(self, include_messages: bool = True) -> dict[str, Any]:
+        """Convert this result to a dictionary for serialization.
+
+        Args:
+            include_messages: Whether to include the full message history.
+
+        Returns:
+            Dictionary representation of this result.
+        """
+        data: dict[str, Any] = {
+            "output": str(self.output) if self.output is not None else None,
+            "output_text": self.output_text,
+            "state": self.state.value if hasattr(self.state, "value") else str(self.state),
+            "usage": self.usage,
+            "run_usage": self.run_usage,
+            "steps": [
+                {
+                    "step_type": s.step_type.value if hasattr(s.step_type, "value") else str(s.step_type),
+                    "timestamp": s.timestamp,
+                    "content": s.content,
+                    "tool_name": s.tool_name,
+                    "tool_args": s.tool_args,
+                    "tool_result": s.tool_result,
+                    "duration_ms": s.duration_ms,
+                }
+                for s in self.steps
+            ],
+            "all_tool_calls": self.all_tool_calls,
+            "exported_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        }
+
+        if include_messages:
+            data["messages"] = self.messages
+
+        return data
+
+    def export_json(self, include_messages: bool = True) -> str:
+        """Export this result to a JSON string.
+
+        Args:
+            include_messages: Whether to include the full message history.
+
+        Returns:
+            JSON string representation of this result.
+
+        Example::
+
+            result = agent.run("What is 2+2?")
+            json_str = result.export_json()
+            with open("agent_history.json", "w") as f:
+                f.write(json_str)
+        """
+        return json.dumps(self.to_dict(include_messages=include_messages), indent=2, default=str)
+
 
 class StreamEventType(str, enum.Enum):
     """Classification for events emitted during streaming agent execution."""

prompture/analysis/__init__.py

@@ -0,0 +1,19 @@
+"""Code analysis module for Python code security assessment.
+
+Provides AST-based analysis to detect potentially dangerous operations
+and calculate risk scores for code execution in sandboxed environments.
+"""
+
+from .analyzer import CodeAnalysis, analyze_python
+from .ast_visitors import CodeFeatures, FeatureExtractor
+from .risk_scoring import RiskAssessment, RiskLevel, calculate_risk
+
+__all__ = [
+    "CodeAnalysis",
+    "CodeFeatures",
+    "FeatureExtractor",
+    "RiskAssessment",
+    "RiskLevel",
+    "analyze_python",
+    "calculate_risk",
+]

prompture/analysis/analyzer.py

@@ -0,0 +1,142 @@
+"""Main code analysis interface.
+
+Provides the primary analyze_python() function for code security assessment.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .ast_visitors import CodeFeatures, extract_features
+from .risk_scoring import RiskAssessment, RiskLevel, calculate_risk
+
+
+@dataclass
+class CodeAnalysis:
+    """Complete analysis result for Python code.
+
+    Attributes:
+        source: The original source code analyzed.
+        features: Extracted code features from AST analysis.
+        risk: Risk assessment with level, score, and reasons.
+        is_safe: Whether the code is considered safe for execution.
+        syntax_valid: Whether the code has valid Python syntax.
+        syntax_error: Syntax error message if parsing failed.
+    """
+
+    source: str
+    features: CodeFeatures
+    risk: RiskAssessment
+    is_safe: bool
+    syntax_valid: bool = True
+    syntax_error: str | None = None
+
+    @property
+    def risk_level(self) -> RiskLevel:
+        """Convenience property to access risk level directly."""
+        return self.risk.level
+
+    @property
+    def risk_score(self) -> int:
+        """Convenience property to access risk score directly."""
+        return self.risk.score
+
+    def to_dict(self) -> dict:
+        """Convert analysis to a dictionary for serialization."""
+        return {
+            "source": self.source,
+            "syntax_valid": self.syntax_valid,
+            "syntax_error": self.syntax_error,
+            "is_safe": self.is_safe,
+            "risk": {
+                "level": self.risk.level.value,
+                "score": self.risk.score,
+                "reasons": self.risk.reasons,
+                "warnings": self.risk.warnings,
+                "blocked_imports": list(self.risk.blocked_imports),
+            },
+            "features": {
+                "imports": list(self.features.imports),
+                "file_operations": self.features.file_operations,
+                "network_calls": self.features.network_calls,
+                "system_calls": self.features.system_calls,
+                "exec_eval_usage": self.features.exec_eval_usage,
+                "dangerous_builtins": list(self.features.dangerous_builtins),
+                "function_calls": list(self.features.function_calls),
+                "has_global_statements": self.features.has_global_statements,
+                "has_nonlocal_statements": self.features.has_nonlocal_statements,
+                "class_definitions": list(self.features.class_definitions),
+                "async_operations": self.features.async_operations,
+            },
+        }
+
+
+def analyze_python(
+    source: str,
+    *,
+    safe_threshold: RiskLevel = RiskLevel.MEDIUM,
+) -> CodeAnalysis:
+    """Analyze Python source code for security risks.
+
+    Performs AST-based analysis to detect potentially dangerous operations
+    and calculates a risk score.
+
+    Args:
+        source: Python source code as a string.
+        safe_threshold: Maximum risk level considered safe.
+            Defaults to MEDIUM (allowing LOW and MEDIUM risk code).
+
+    Returns:
+        CodeAnalysis with features, risk assessment, and safety determination.
+
+    Example::
+
+        from prompture.analysis import analyze_python, RiskLevel
+
+        analysis = analyze_python("import subprocess; subprocess.run(['ls'])")
+        print(f"Risk: {analysis.risk_level}")  # RiskLevel.CRITICAL
+        print(f"Safe: {analysis.is_safe}")  # False
+
+        # More permissive threshold
+        analysis = analyze_python("import json", safe_threshold=RiskLevel.HIGH)
+        print(f"Safe: {analysis.is_safe}")  # True
+    """
+    # Try to parse the source code
+    try:
+        features = extract_features(source)
+        syntax_valid = True
+        syntax_error = None
+    except SyntaxError as e:
+        # Return analysis with syntax error
+        features = CodeFeatures()
+        risk = RiskAssessment(
+            level=RiskLevel.CRITICAL,
+            score=100,
+            reasons=[f"Syntax error: {e}"],
+        )
+        return CodeAnalysis(
+            source=source,
+            features=features,
+            risk=risk,
+            is_safe=False,
+            syntax_valid=False,
+            syntax_error=str(e),
+        )
+
+    # Calculate risk
+    risk = calculate_risk(features)
+
+    # Determine safety based on threshold
+    threshold_order = [RiskLevel.LOW, RiskLevel.MEDIUM, RiskLevel.HIGH, RiskLevel.CRITICAL]
+    risk_index = threshold_order.index(risk.level)
+    threshold_index = threshold_order.index(safe_threshold)
+    is_safe = risk_index <= threshold_index
+
+    return CodeAnalysis(
+        source=source,
+        features=features,
+        risk=risk,
+        is_safe=is_safe,
+        syntax_valid=syntax_valid,
+        syntax_error=syntax_error,
+    )