tactus 0.31.2__py3-none-any.whl

tactus/dspy/broker_lm.py

@@ -0,0 +1,181 @@
+"""
+DSPy LM implementation backed by the local Tactus broker.
+
+This allows the runtime container to be:
+- networkless (`--network none`)
+- secretless (no API keys in env/mounts/request payload)
+
+while still supporting streaming via DSPy's `streamify()` mechanism.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import dspy
+import litellm
+from asyncer import syncify
+from litellm import ModelResponse, ModelResponseStream
+
+from tactus.broker.client import BrokerClient
+
+
+def _split_provider_model(model: str) -> tuple[str, str]:
+    if "/" not in model:
+        raise ValueError(f"Invalid model format: {model}. Expected 'provider/model'.")
+    provider, model_id = model.split("/", 1)
+    return provider, model_id
+
+
+class BrokeredLM(dspy.BaseLM):
+    """
+    A DSPy-compatible LM that delegates completion calls to the broker.
+
+    The broker connection is configured via `TACTUS_BROKER_SOCKET`.
+    """
+
+    def __init__(
+        self,
+        model: str,
+        *,
+        model_type: str = "chat",
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        cache: bool | None = None,
+        socket_path: str | None = None,
+        **kwargs: Any,
+    ):
+        if model_type != "chat":
+            raise ValueError("BrokeredLM currently supports only model_type='chat'")
+
+        super().__init__(
+            model=model,
+            model_type=model_type,
+            temperature=temperature if temperature is not None else 0.7,
+            max_tokens=max_tokens if max_tokens is not None else 1000,
+            cache=False,
+            **kwargs,
+        )
+
+        if socket_path is not None:
+            self._client = BrokerClient(socket_path)
+            return
+
+        env_client = BrokerClient.from_environment()
+        if env_client is None:
+            raise RuntimeError("BrokerClient not configured (TACTUS_BROKER_SOCKET is missing)")
+        self._client = env_client
+
+    def forward(
+        self, prompt: str | None = None, messages: list[dict[str, Any]] | None = None, **kwargs: Any
+    ):
+        return syncify(self.aforward)(prompt=prompt, messages=messages, **kwargs)
+
+    async def aforward(
+        self, prompt: str | None = None, messages: list[dict[str, Any]] | None = None, **kwargs: Any
+    ):
+        provider, model_id = _split_provider_model(self.model)
+
+        if provider != "openai":
+            raise ValueError(
+                f"BrokeredLM only supports provider 'openai' for now (got {provider!r})"
+            )
+
+        if messages is None:
+            if prompt is None:
+                messages = []
+            else:
+                messages = [{"role": "user", "content": prompt}]
+
+        merged_kwargs = {**self.kwargs, **kwargs}
+        temperature = merged_kwargs.get("temperature")
+
+        # DSPy uses `max_tokens`, while some reasoning models use `max_completion_tokens`.
+        max_tokens = merged_kwargs.get("max_tokens")
+        if max_tokens is None and merged_kwargs.get("max_completion_tokens") is not None:
+            max_tokens = merged_kwargs.get("max_completion_tokens")
+
+        send_stream = dspy.settings.send_stream
+        caller_predict = dspy.settings.caller_predict
+        caller_predict_id = id(caller_predict) if caller_predict else None
+
+        if send_stream is not None:
+            chunks: list[ModelResponseStream] = []
+            async for event in self._client.llm_chat(
+                provider="openai",
+                model=model_id,
+                messages=messages,
+                temperature=temperature,
+                max_tokens=max_tokens,
+                stream=True,
+            ):
+                event_type = event.get("event")
+                if event_type == "delta":
+                    text = (event.get("data") or {}).get("text") or ""
+                    if not text:
+                        continue
+                    chunk = ModelResponseStream(
+                        model=model_id,
+                        choices=[{"index": 0, "delta": {"content": text}}],
+                    )
+                    if caller_predict_id is not None:
+                        chunk.predict_id = caller_predict_id  # type: ignore[attr-defined]
+                    chunks.append(chunk)
+                    await send_stream.send(chunk)
+                    continue
+
+                if event_type == "done":
+                    break
+
+                if event_type == "error":
+                    err = event.get("error") or {}
+                    raise RuntimeError(err.get("message") or "Broker LLM error")
+
+            if chunks:
+                return litellm.stream_chunk_builder(chunks)
+
+            # No streamed chunks; return an empty completion.
+            return ModelResponse(
+                model=model_id,
+                choices=[
+                    {
+                        "index": 0,
+                        "finish_reason": "stop",
+                        "message": {"role": "assistant", "content": ""},
+                    }
+                ],
+                usage={"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0},
+            )
+
+        # Non-streaming path
+        final_text = ""
+        usage = {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
+        async for event in self._client.llm_chat(
+            provider="openai",
+            model=model_id,
+            messages=messages,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            stream=False,
+        ):
+            event_type = event.get("event")
+            if event_type == "done":
+                data = event.get("data") or {}
+                final_text = data.get("text") or ""
+                usage = data.get("usage") or usage
+                break
+            if event_type == "error":
+                err = event.get("error") or {}
+                raise RuntimeError(err.get("message") or "Broker LLM error")
+
+        return ModelResponse(
+            model=model_id,
+            choices=[
+                {
+                    "index": 0,
+                    "finish_reason": "stop",
+                    "message": {"role": "assistant", "content": final_text},
+                }
+            ],
+            usage=usage,
+        )

tactus/dspy/config.py

@@ -0,0 +1,212 @@
+"""
+DSPy configuration for Tactus.
+
+This module handles Language Model configuration using DSPy's LM abstraction,
+which uses LiteLLM under the hood for provider-agnostic LLM access.
+"""
+
+from typing import Optional, Any
+
+import dspy
+
+
+# Global reference to the current LM configuration
+_current_lm: Optional[dspy.BaseLM] = None
+
+
+def configure_lm(
+    model: str,
+    api_key: Optional[str] = None,
+    api_base: Optional[str] = None,
+    temperature: float = 0.7,
+    max_tokens: Optional[int] = None,
+    model_type: Optional[str] = None,
+    **kwargs: Any,
+) -> dspy.BaseLM:
+    """
+    Configure the default Language Model for DSPy operations.
+
+    This uses LiteLLM's model naming convention:
+    - OpenAI: "openai/gpt-4o", "openai/gpt-4o-mini"
+    - Anthropic: "anthropic/claude-3-5-sonnet-20241022"
+    - AWS Bedrock: "bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0"
+    - Google: "gemini/gemini-pro"
+
+    Args:
+        model: Model identifier in LiteLLM format (e.g., "openai/gpt-4o")
+        api_key: API key (optional, can use environment variables)
+        api_base: Custom API base URL (optional)
+        temperature: Sampling temperature (default: 0.7)
+        max_tokens: Maximum tokens in response (optional)
+        model_type: Model type (e.g., "chat", "responses" for reasoning models)
+        **kwargs: Additional LiteLLM parameters
+
+    Returns:
+        Configured dspy.LM instance
+
+    Example:
+        >>> configure_lm("openai/gpt-4o", temperature=0.3)
+        >>> configure_lm("anthropic/claude-3-5-sonnet-20241022")
+        >>> configure_lm("openai/gpt-5-mini", model_type="responses")
+    """
+    global _current_lm
+
+    import os
+
+    # Validate model parameter
+    if model is None or not model:
+        raise ValueError("model is required for LM configuration")
+
+    if not isinstance(model, str) or not model.startswith(
+        ("openai/", "anthropic/", "bedrock/", "gemini/", "ollama/")
+    ):
+        # Check if it's at least formatted correctly
+        if "/" not in model:
+            raise ValueError(
+                f"Invalid model format: {model}. Expected format like 'provider/model-name'"
+            )
+
+    # Build configuration
+    lm_kwargs = {
+        "temperature": temperature,
+        # IMPORTANT: Disable caching to enable streaming. With cache=True (default),
+        # DSPy returns cached responses which breaks streamify()'s ability to stream.
+        "cache": False,
+        **kwargs,
+    }
+
+    if api_key:
+        lm_kwargs["api_key"] = api_key
+    if api_base:
+        lm_kwargs["api_base"] = api_base
+    if max_tokens:
+        lm_kwargs["max_tokens"] = max_tokens
+    if model_type:
+        lm_kwargs["model_type"] = model_type
+
+    # If running inside the secretless runtime container, use the brokered LM.
+    if os.environ.get("TACTUS_BROKER_SOCKET"):
+        from tactus.dspy.broker_lm import BrokeredLM
+
+        # Ensure we don't accidentally pass credentials into the runtime container process.
+        lm_kwargs.pop("api_key", None)
+        lm_kwargs.pop("api_base", None)
+
+        # BrokeredLM reads the socket path from TACTUS_BROKER_SOCKET.
+        lm = BrokeredLM(model, **lm_kwargs)
+    else:
+        # Create and configure the standard DSPy LM (LiteLLM-backed)
+        lm = dspy.LM(model, **lm_kwargs)
+
+    # Set as global default
+    dspy.configure(lm=lm)
+    _current_lm = lm
+
+    return lm
+
+
+def get_current_lm() -> Optional[dspy.BaseLM]:
+    """
+    Get the currently configured Language Model.
+
+    Returns:
+        The current dspy.BaseLM instance, or None if not configured.
+    """
+    return _current_lm
+
+
+def ensure_lm_configured() -> dspy.BaseLM:
+    """
+    Ensure a Language Model is configured, raising an error if not.
+
+    Returns:
+        The current dspy.BaseLM instance.
+
+    Raises:
+        RuntimeError: If no LM has been configured.
+    """
+    if _current_lm is None:
+        raise RuntimeError(
+            "No Language Model configured. "
+            "Call configure_lm() or use LM() primitive in your Tactus code."
+        )
+    return _current_lm
+
+
+def reset_lm_configuration() -> None:
+    """
+    Reset the LM configuration (primarily for testing).
+
+    This clears the global LM state, allowing tests to verify
+    error handling when no LM is configured.
+    """
+    global _current_lm
+    _current_lm = None
+    # Also reset DSPy's global configuration
+    dspy.configure(lm=None)
+
+
+def create_lm(
+    model: str,
+    api_key: Optional[str] = None,
+    api_base: Optional[str] = None,
+    temperature: float = 0.7,
+    max_tokens: Optional[int] = None,
+    model_type: Optional[str] = None,
+    **kwargs: Any,
+) -> dspy.LM:
+    """
+    Create a Language Model instance WITHOUT setting it as global default.
+
+    This is useful for creating LMs in async contexts where dspy.configure()
+    cannot be called (e.g., in different event loops or async tasks).
+
+    Use with dspy.context(lm=...) to set the LM for a specific scope:
+        lm = create_lm("openai/gpt-4o")
+        with dspy.context(lm=lm):
+            # Use DSPy operations here
+
+    Args:
+        model: Model identifier in LiteLLM format (e.g., "openai/gpt-4o")
+        api_key: API key (optional, can use environment variables)
+        api_base: Custom API base URL (optional)
+        temperature: Sampling temperature (default: 0.7)
+        max_tokens: Maximum tokens in response (optional)
+        model_type: Model type (e.g., "chat", "responses" for reasoning models)
+        **kwargs: Additional LiteLLM parameters
+
+    Returns:
+        dspy.LM instance (not configured globally)
+    """
+    # Validate model parameter
+    if model is None or not model:
+        raise ValueError("model is required for LM configuration")
+
+    if not isinstance(model, str) or not model.startswith(
+        ("openai/", "anthropic/", "bedrock/", "gemini/", "ollama/")
+    ):
+        # Check if it's at least formatted correctly
+        if "/" not in model:
+            raise ValueError(
+                f"Invalid model format: {model}. Expected format like 'provider/model-name'"
+            )
+
+    # Build configuration
+    lm_kwargs = {
+        "temperature": temperature,
+        # IMPORTANT: Disable caching to enable streaming
+        "cache": False,
+        **kwargs,
+    }
+
+    if api_key:
+        lm_kwargs["api_key"] = api_key
+    if api_base:
+        lm_kwargs["api_base"] = api_base
+    if max_tokens:
+        lm_kwargs["max_tokens"] = max_tokens
+    if model_type:
+        lm_kwargs["model_type"] = model_type
+
+    # Create LM without setting as global default
+    return dspy.LM(model, **lm_kwargs)

tactus/dspy/history.py

@@ -0,0 +1,196 @@
+"""
+DSPy History integration for Tactus.
+
+This module provides the History primitive that maps to DSPy History,
+enabling multi-turn conversation management in Tactus procedures.
+"""
+
+from typing import Any, Dict, List, Optional
+
+import dspy
+
+
+class TactusHistory:
+    """
+    A Tactus wrapper around DSPy History.
+
+    This class provides a convenient API for managing conversation history
+    that can be passed to DSPy Modules. It maintains a list of messages
+    and provides methods for adding, retrieving, and clearing messages.
+
+    Example usage in Lua:
+        -- Create a history
+        local history = History()
+
+        -- Add messages
+        history.add({ question = "What is 2+2?", answer = "4" })
+        history.add({ question = "And 3+3?", answer = "6" })
+
+        -- Get all messages
+        local messages = history.get()
+
+        -- Pass to a Module
+        local result = qa_module({ question = "What is 4+4?", history = history })
+
+        -- Clear history
+        history.clear()
+    """
+
+    def __init__(self, messages: Optional[List[Dict[str, Any]]] = None):
+        """
+        Initialize a TactusHistory.
+
+        Args:
+            messages: Optional initial list of messages
+        """
+        self._messages: List[Dict[str, Any]] = messages or []
+
+    def add(self, message: Dict[str, Any]) -> None:
+        """
+        Add a message to the history.
+
+        Args:
+            message: A dict with keys 'role' and 'content', or a TactusMessage object
+                    e.g., {"role": "user", "content": "What is 2+2?"}
+                    e.g., Message {role = "user", content = "What is 2+2?"}
+
+        Raises:
+            ValueError: If message lacks required keys or invalid role
+        """
+        # Check if it's a TactusMessage (has to_dict method)
+        if hasattr(message, "to_dict") and callable(message.to_dict):
+            message = message.to_dict()
+        # Convert Lua tables to dict if needed
+        elif hasattr(message, "items"):
+            # It's a Lua table or similar mapping
+            try:
+                message = dict(message.items())
+            except (AttributeError, TypeError):
+                pass
+
+        # Check for required keys
+        if not isinstance(message, dict):
+            raise ValueError("Message must be a dictionary or TactusMessage")
+
+        if "role" not in message:
+            raise ValueError("role is required")
+
+        if "content" not in message:
+            raise ValueError("Message must include 'content' key")
+
+        # Validate role
+        valid_roles = ["system", "user", "assistant"]
+        if message["role"] not in valid_roles:
+            raise ValueError(f"Invalid role. Must be one of {valid_roles}")
+
+        # Convert legacy formats if needed
+        if "question" in message and "answer" in message:
+            message = {
+                "role": "user",
+                "content": message.get("question", ""),
+            }
+        elif "answer" in message:
+            message = {
+                "role": "assistant",
+                "content": message.get("answer", ""),
+            }
+
+        self._messages.append(message)
+
+    def get(
+        self, context_window: Optional[int] = None, token_limit: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
+        """
+        Get messages from history, optionally filtered by context window and token limit.
+
+        Args:
+            context_window: Maximum number of recent messages to retrieve
+            token_limit: Maximum number of tokens to include
+
+        Returns:
+            List of message dictionaries
+        """
+        messages = self._messages.copy()
+
+        # Apply context window
+        if context_window is not None:
+            messages = messages[-context_window:]
+
+        # Simple token estimation (approximation)
+        if token_limit is not None:
+            token_count = 0
+            filtered_messages = []
+            for msg in reversed(messages):
+                # Basic token estimation: 1 token per 4 characters
+                msg_tokens = len(msg.get("content", "")) // 4 + len(msg.get("role", "")) // 4 + 4
+
+                if token_count + msg_tokens <= token_limit:
+                    filtered_messages.insert(0, msg)
+                    token_count += msg_tokens
+                else:
+                    break
+
+            messages = filtered_messages
+
+        return messages
+
+    def clear(self) -> None:
+        """Clear all messages from the history."""
+        self._messages.clear()
+
+    def to_dspy(self) -> dspy.History:
+        """
+        Convert to a DSPy History object.
+
+        Returns:
+            A dspy.History instance suitable for passing to DSPy Modules
+        """
+        return dspy.History(messages=self._messages)
+
+    def count_tokens(self) -> int:
+        """
+        Estimate total tokens in the history.
+
+        Returns:
+            Estimated token count
+        """
+        return sum(
+            len(msg.get("content", "")) // 4 + len(msg.get("role", "")) // 4 + 4
+            for msg in self._messages
+        )
+
+    def __len__(self) -> int:
+        """Return the number of messages in history."""
+        return len(self._messages)
+
+    def __iter__(self):
+        """Iterate over messages in history."""
+        return iter(self._messages)
+
+    @classmethod
+    def from_dspy(cls, dspy_history: dspy.History) -> "TactusHistory":
+        """
+        Create a TactusHistory from a DSPy History.
+
+        Args:
+            dspy_history: A dspy.History instance
+
+        Returns:
+            A TactusHistory instance
+        """
+        return cls(messages=dspy_history.messages)
+
+
+def create_history(messages: Optional[List[Dict[str, Any]]] = None) -> TactusHistory:
+    """
+    Create a new TactusHistory.
+
+    This is the main entry point used by the DSL stubs.
+
+    Args:
+        messages: Optional initial list of messages
+
+    Returns:
+        A TactusHistory instance
+    """
+    return TactusHistory(messages=messages)