zeroshot-agentic-workflows 0.1.5__tar.gz

zeroshot_agentic_workflows-0.1.5/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: zeroshot-agentic-workflows
+Version: 0.1.5
+Summary: Framework-agnostic agent workflow building blocks for Zeroshot Python packages.
+License-Expression: MIT
+Requires-Dist: zeroshot-commons==0.1.5
+Requires-Dist: openai-agents>=0.0.7
+Requires-Dist: pyyaml>=6.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# zeroshot-agentic-workflows
+
+Framework-agnostic agent workflow building blocks for Zeroshot Python packages.

zeroshot_agentic_workflows-0.1.5/README.md

@@ -0,0 +1,3 @@
+# zeroshot-agentic-workflows
+
+Framework-agnostic agent workflow building blocks for Zeroshot Python packages.

zeroshot_agentic_workflows-0.1.5/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "zeroshot-agentic-workflows"
+version = "0.1.5"
+description = "Framework-agnostic agent workflow building blocks for Zeroshot Python packages."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+dependencies = [
+  "zeroshot-commons==0.1.5",
+  "openai-agents>=0.0.7",
+  "pyyaml>=6.0",
+]
+
+[tool.uv.sources]
+zeroshot-commons = { workspace = true }
+
+[build-system]
+requires = ["uv_build>=0.11.8,<0.12"]
+build-backend = "uv_build"

zeroshot_agentic_workflows-0.1.5/src/zeroshot_agentic_workflows/__init__.py

@@ -0,0 +1,67 @@
+"""Agent workflow building blocks for Zeroshot Python packages."""
+
+from .agent_service import (
+    AgentConfig,
+    AgentRunConfig,
+    AgentRunResult,
+    AgentType,
+    AiAgentConfig,
+    AiAgentProvider,
+    AiAgentService,
+    AiAgentServiceLocal,
+    ConsensusRunResult,
+    ConsensusStrategy,
+)
+from .decorators import agent, agentic_workflow, consensus_agent
+from .factory import AiAgentFactory
+from .param_mapper import AgentParameterMapper
+from .prompt_utils import (
+    ParsedPrompt,
+    PromptFrontmatter,
+    generate_tools_reference,
+    parse_prompt_frontmatter,
+)
+from .session import (
+    CONVERSATION_SESSION_REPOSITORY,
+    ConversationItemModel,
+    ConversationMessage,
+    ConversationSessionModel,
+    ConversationSessionRepository,
+    InMemoryConversationSessionRepository,
+    RepositorySession,
+    SessionItem,
+    SessionNotFoundError,
+)
+from .session_factory import AiSessionFactory
+
+__all__ = [
+    "CONVERSATION_SESSION_REPOSITORY",
+    "AgentConfig",
+    "AgentParameterMapper",
+    "AgentRunConfig",
+    "AgentRunResult",
+    "AgentType",
+    "AiAgentConfig",
+    "AiAgentFactory",
+    "AiAgentProvider",
+    "AiAgentService",
+    "AiAgentServiceLocal",
+    "AiSessionFactory",
+    "ConsensusRunResult",
+    "ConsensusStrategy",
+    "ConversationItemModel",
+    "ConversationMessage",
+    "ConversationSessionModel",
+    "ConversationSessionRepository",
+    "InMemoryConversationSessionRepository",
+    "ParsedPrompt",
+    "PromptFrontmatter",
+    "RepositorySession",
+    "SessionItem",
+    "SessionNotFoundError",
+    "agent",
+    "agentic_workflow",
+    "consensus_agent",
+    "generate_tools_reference",
+    "parse_prompt_frontmatter",
+]

zeroshot_agentic_workflows-0.1.5/src/zeroshot_agentic_workflows/agent_service.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any, ClassVar, Protocol, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True, slots=True)
+class AgentRunConfig:
+    input: str
+    context: dict[str, Any] | None = None
+    session: Any | None = None
+    max_turns: int | None = None
+    branch: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class AgentRunResult[T]:
+    output: T
+    success: bool
+    error: str | None = None
+    raw_result: Any | None = None
+    working_dir: str | None = None
+
+
+class ConsensusStrategy(StrEnum):
+    MAJORITY = "majority"
+    UNANIMOUS = "unanimous"
+    JUDGE = "judge"
+
+
+@dataclass(frozen=True, slots=True)
+class ConsensusRunResult(AgentRunResult[T]):
+    runs: list[AgentRunResult[T]] = field(default_factory=list)
+    agreement: float = 0.0
+    total_runs: int = 0
+    successful_runs: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class AgentConfig[T]:
+    name: str
+    instructions: str
+    model: str | None = None
+    tools: list[Any] = field(default_factory=list)
+    output_schema: Any | None = None
+    model_settings: dict[str, Any] | None = None
+    input_guardrails: list[Any] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class AgentType[T]:
+    config: AgentConfig[T]
+
+
+class AiAgentService(Protocol):
+    def create_agent(self, config: AgentConfig[T]) -> AgentType[T]: ...
+
+    async def run_agent(
+        self,
+        agent: AgentType[T],
+        config: AgentRunConfig,
+    ) -> AgentRunResult[T]: ...
+
+    async def create_and_run(
+        self,
+        agent_config: AgentConfig[T],
+        run_config: AgentRunConfig,
+    ) -> AgentRunResult[T]: ...
+
+
+class AiAgentProvider(StrEnum):
+    OPENAI = "openai"
+    OLLAMA = "ollama"
+
+
+@dataclass(frozen=True, slots=True)
+class AiAgentConfig:
+    local: bool
+    provider: AiAgentProvider = AiAgentProvider.OPENAI
+    openai_api_token: str | None = None
+    ollama_base_url: str = "http://localhost:11434"
+    default_model: str | None = None
+
+
+class AiAgentServiceLocal:
+    _instance: ClassVar[AiAgentServiceLocal | None] = None
+    _responses_by_agent_name: ClassVar[dict[str, list[Any]]] = {}
+    _last_response_by_agent_name: ClassVar[dict[str, Any]] = {}
+    _errors_by_agent_name: ClassVar[dict[str, str]] = {}
+    _mock_working_dir: ClassVar[str | None] = None
+
+    @classmethod
+    def get_instance(cls) -> AiAgentServiceLocal:
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+
+    @classmethod
+    def set_response(cls, agent_name: str, output: Any) -> None:
+        cls._responses_by_agent_name.setdefault(agent_name, []).append(output)
+
+    @classmethod
+    def set_responses(cls, agent_name: str, outputs: list[Any]) -> None:
+        cls._responses_by_agent_name.setdefault(agent_name, []).extend(outputs)
+
+    @classmethod
+    def set_mock_working_dir(cls, directory: str | None) -> None:
+        cls._mock_working_dir = directory
+
+    @classmethod
+    def set_error(cls, agent_name: str, error_message: str) -> None:
+        cls._errors_by_agent_name[agent_name] = error_message
+
+    @classmethod
+    def clear_responses(cls) -> None:
+        cls._responses_by_agent_name.clear()
+        cls._last_response_by_agent_name.clear()
+
+    @classmethod
+    def clear_errors(cls) -> None:
+        cls._errors_by_agent_name.clear()
+
+    @classmethod
+    def clear_all_overrides(cls) -> None:
+        cls._responses_by_agent_name.clear()
+        cls._last_response_by_agent_name.clear()
+        cls._errors_by_agent_name.clear()
+        cls._mock_working_dir = None
+
+    def create_agent(self, config: AgentConfig[T]) -> AgentType[T]:
+        return AgentType(config=config)
+
+    async def run_agent(
+        self,
+        agent: AgentType[T],
+        config: AgentRunConfig,
+    ) -> AgentRunResult[T]:
+        return await self._execute_agent(agent.config, config)
+
+    async def create_and_run(
+        self,
+        agent_config: AgentConfig[T],
+        run_config: AgentRunConfig,
+    ) -> AgentRunResult[T]:
+        return await self._execute_agent(agent_config, run_config)
+
+    async def _execute_agent(
+        self,
+        agent_config: AgentConfig[T],
+        run_config: AgentRunConfig,
+    ) -> AgentRunResult[T]:
+        result = await self._get_agent_result(agent_config)
+
+        if run_config.session is not None and result.success:
+            await run_config.session.add_items(
+                [
+                    {"role": "user", "content": run_config.input},
+                    {
+                        "role": "assistant",
+                        "status": "completed",
+                        "content": [
+                            {
+                                "type": "output_text",
+                                "text": (
+                                    result.output
+                                    if isinstance(result.output, str)
+                                    else json.dumps(result.output)
+                                ),
+                            }
+                        ],
+                    },
+                ]
+            )
+
+        return result
+
+    async def _get_agent_result(self, agent_config: AgentConfig[T]) -> AgentRunResult[T]:
+        error = self._errors_by_agent_name.get(agent_config.name)
+        if error is not None:
+            return AgentRunResult(
+                success=False,
+                error=error,
+                output=None,  # type: ignore[arg-type]
+            )
+
+        responses = self._responses_by_agent_name.get(agent_config.name)
+        if responses:
+            response = responses.pop(0)
+            self._last_response_by_agent_name[agent_config.name] = response
+            return AgentRunResult(
+                success=True,
+                output=response,
+                working_dir=self._mock_working_dir,
+            )
+
+        if agent_config.name in self._last_response_by_agent_name:
+            return AgentRunResult(
+                success=True,
+                output=self._last_response_by_agent_name[agent_config.name],
+                working_dir=self._mock_working_dir,
+            )
+
+        return AgentRunResult(
+            success=True,
+            output=self._generate_default_response(agent_config),
+            working_dir=self._mock_working_dir,
+        )
+
+    def _generate_default_response(self, config: AgentConfig[T]) -> T:
+        if config.output_schema is not None:
+            return {}  # type: ignore[return-value]
+        return f"Mock response for {config.name}"  # type: ignore[return-value]

zeroshot_agentic_workflows-0.1.5/src/zeroshot_agentic_workflows/decorators.py

@@ -0,0 +1,302 @@
+from __future__ import annotations
+
+import asyncio
+import functools
+import json
+import logging
+import time
+from collections import Counter
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from .agent_service import (
+    AgentConfig,
+    AgentRunConfig,
+    AgentRunResult,
+    AiAgentService,
+    ConsensusRunResult,
+    ConsensusStrategy,
+)
+from .param_mapper import AgentParameterMapper
+from .prompt_utils import generate_tools_reference, parse_prompt_frontmatter
+
+logger = logging.getLogger(__name__)
+
+
+def agentic_workflow(
+    *,
+    prompts_directory: str,
+    tool_registry: dict[str, str] | None = None,
+) -> Any:
+    """Class decorator that registers prompt directory and tool registry."""
+
+    def decorator(cls: type) -> type:
+        cls._agentic_workflow_options = {  # type: ignore[attr-defined]
+            "prompts_directory": prompts_directory,
+            "tool_registry": tool_registry,
+        }
+        return cls
+
+    return decorator
+
+
+def agent(
+    *,
+    name: str | None = None,
+    tools: list[Any] | Callable[..., list[Any]] | None = None,
+    model: str | None = None,
+    model_settings: dict[str, Any] | None = None,
+    output_schema: Any | None = None,
+    max_turns: int | None = None,
+    branch_param: str | None = None,
+) -> Any:
+    """Method decorator that turns a method into an agent invocation.
+
+    The decorated method's body is replaced. Its parameters are mapped
+    to the agent input JSON, and the prompt is loaded from a markdown file
+    in the class's ``prompts_directory``.
+    """
+
+    def decorator(fn: Any) -> Any:
+        mapper = AgentParameterMapper.from_function(fn)
+
+        @functools.wraps(fn)
+        async def wrapper(self: Any, *args: Any, **kwargs: Any) -> AgentRunResult[Any]:
+            ai_service: AiAgentService = self._ai_agent_service
+            options = getattr(self.__class__, "_agentic_workflow_options", {})
+            prompts_dir = options.get("prompts_directory", "")
+
+            # Load prompt from markdown file
+            prompt_path = Path(prompts_dir) / f"{fn.__name__}.md"
+            if prompt_path.exists():
+                raw_prompt = prompt_path.read_text()
+            else:
+                raw_prompt = ""
+
+            parsed = parse_prompt_frontmatter(raw_prompt)
+            instructions = parsed.content
+
+            # Resolve tools
+            resolved_tools = tools
+            if callable(resolved_tools):
+                resolved_tools = resolved_tools(self)
+            resolved_tools = resolved_tools or []
+
+            # Generate tools reference and prepend
+            tools_ref = generate_tools_reference(resolved_tools)
+            if tools_ref:
+                instructions = tools_ref + "\n" + instructions
+
+            # Map parameters
+            all_args = args
+            mapped = mapper.map_arguments(all_args)
+            session = mapper.find_session(all_args)
+
+            # Determine agent name
+            agent_name = name or f"{self.__class__.__name__}:{fn.__name__}"
+
+            # Get branch if specified
+            branch = None
+            if branch_param:
+                branch = mapper.get_param_value(branch_param, all_args)
+
+            # Determine max_turns
+            effective_max_turns = max_turns
+            if effective_max_turns is None:
+                effective_max_turns = 8 if resolved_tools else 1
+
+            config = AgentConfig(
+                name=agent_name,
+                instructions=instructions,
+                model=model,
+                tools=resolved_tools,
+                output_schema=output_schema,
+                model_settings=model_settings,
+            )
+
+            run_config = AgentRunConfig(
+                input=mapped.input,
+                context=mapped.context,
+                session=session,
+                max_turns=effective_max_turns,
+                branch=branch,
+            )
+
+            start = time.monotonic()
+            result = await ai_service.create_and_run(config, run_config)
+            elapsed = time.monotonic() - start
+            logger.debug(
+                "Agent %s completed in %.2fs (success=%s)",
+                agent_name,
+                elapsed,
+                result.success,
+            )
+
+            return result
+
+        return wrapper
+
+    return decorator
+
+
+def consensus_agent(
+    *,
+    name: str | None = None,
+    tools: list[Any] | Callable[..., list[Any]] | None = None,
+    model: str | None = None,
+    model_settings: dict[str, Any] | None = None,
+    output_schema: Any | None = None,
+    max_turns: int | None = None,
+    runs: int,
+    consensus_strategy: ConsensusStrategy,
+    judge: Callable[..., Any] | None = None,
+    temperature_spread: tuple[float, float] | None = None,
+) -> Any:
+    """Method decorator for consensus-based multi-run agent invocation."""
+
+    if runs % 2 == 0:
+        raise ValueError("runs must be odd")
+    if consensus_strategy == ConsensusStrategy.JUDGE and judge is None:
+        raise ValueError("judge function required for JUDGE strategy")
+
+    def decorator(fn: Any) -> Any:
+        mapper = AgentParameterMapper.from_function(fn)
+
+        @functools.wraps(fn)
+        async def wrapper(self: Any, *args: Any, **kwargs: Any) -> ConsensusRunResult[Any]:
+            ai_service: AiAgentService = self._ai_agent_service
+            options = getattr(self.__class__, "_agentic_workflow_options", {})
+            prompts_dir = options.get("prompts_directory", "")
+
+            prompt_path = Path(prompts_dir) / f"{fn.__name__}.md"
+            raw_prompt = prompt_path.read_text() if prompt_path.exists() else ""
+            parsed = parse_prompt_frontmatter(raw_prompt)
+            instructions = parsed.content
+
+            resolved_tools = tools
+            if callable(resolved_tools):
+                resolved_tools = resolved_tools(self)
+            resolved_tools = resolved_tools or []
+
+            tools_ref = generate_tools_reference(resolved_tools)
+            if tools_ref:
+                instructions = tools_ref + "\n" + instructions
+
+            mapped = mapper.map_arguments(args)
+            session = mapper.find_session(args)
+            agent_name = name or f"{self.__class__.__name__}:{fn.__name__}"
+            effective_max_turns = max_turns or (8 if resolved_tools else 1)
+
+            # Build configs for each run
+            async def single_run(run_index: int) -> AgentRunResult[Any]:
+                ms = dict(model_settings or {})
+                if temperature_spread:
+                    lo, hi = temperature_spread
+                    t = lo + (hi - lo) * run_index / max(runs - 1, 1)
+                    ms["temperature"] = t
+
+                config = AgentConfig(
+                    name=agent_name,
+                    instructions=instructions,
+                    model=model,
+                    tools=resolved_tools,
+                    output_schema=output_schema,
+                    model_settings=ms or None,
+                )
+                run_config = AgentRunConfig(
+                    input=mapped.input,
+                    context=mapped.context,
+                    session=session,
+                    max_turns=effective_max_turns,
+                )
+                return await ai_service.create_and_run(config, run_config)
+
+            all_results = await asyncio.gather(*(single_run(i) for i in range(runs)))
+            all_results_list = list(all_results)
+
+            return await _resolve_consensus(
+                all_results_list,
+                consensus_strategy,
+                runs,
+                judge_fn=judge,
+                instance=self,
+            )
+
+        return wrapper
+
+    return decorator
+
+
+async def _resolve_consensus(
+    all_results: list[AgentRunResult[Any]],
+    strategy: ConsensusStrategy,
+    total_runs: int,
+    judge_fn: Callable[..., Any] | None = None,
+    instance: Any = None,
+) -> ConsensusRunResult[Any]:
+    successful = [r for r in all_results if r.success]
+
+    if not successful:
+        return ConsensusRunResult(
+            output=None,  # type: ignore[arg-type]
+            success=False,
+            error="All runs failed",
+            runs=all_results,
+            agreement=0.0,
+            total_runs=total_runs,
+            successful_runs=0,
+        )
+
+    if strategy == ConsensusStrategy.MAJORITY:
+        serialized = [json.dumps(r.output, sort_keys=True, default=str) for r in successful]
+        counts = Counter(serialized)
+        winner_key, winner_count = counts.most_common(1)[0]
+        winner_result = next(
+            r for r, s in zip(successful, serialized, strict=False) if s == winner_key
+        )
+        return ConsensusRunResult(
+            output=winner_result.output,
+            success=True,
+            raw_result=winner_result.raw_result,
+            runs=all_results,
+            agreement=winner_count / len(successful),
+            total_runs=total_runs,
+            successful_runs=len(successful),
+        )
+
+    if strategy == ConsensusStrategy.UNANIMOUS:
+        serialized = [json.dumps(r.output, sort_keys=True, default=str) for r in successful]
+        if len(set(serialized)) != 1:
+            return ConsensusRunResult(
+                output=None,  # type: ignore[arg-type]
+                success=False,
+                error="Unanimous consensus not reached",
+                runs=all_results,
+                agreement=0.0,
+                total_runs=total_runs,
+                successful_runs=len(successful),
+            )
+        return ConsensusRunResult(
+            output=successful[0].output,
+            success=True,
+            raw_result=successful[0].raw_result,
+            runs=all_results,
+            agreement=1.0,
+            total_runs=total_runs,
+            successful_runs=len(successful),
+        )
+
+    if strategy == ConsensusStrategy.JUDGE:
+        assert judge_fn is not None
+        judge_result = await judge_fn(instance, successful)
+        return ConsensusRunResult(
+            output=judge_result.output,
+            success=judge_result.success,
+            runs=all_results,
+            agreement=0.0,
+            total_runs=total_runs,
+            successful_runs=len(successful),
+        )
+
+    raise ValueError(f"Unknown consensus strategy: {strategy}")

zeroshot_agentic_workflows-0.1.5/src/zeroshot_agentic_workflows/factory.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from .agent_service import AiAgentConfig, AiAgentProvider, AiAgentService, AiAgentServiceLocal
+from .service_ollama import AiAgentServiceOllama
+from .service_openai import AiAgentServiceOpenai
+
+
+class AiAgentFactory:
+    """Creates the appropriate AiAgentService based on configuration."""
+
+    def __init__(self, config: AiAgentConfig) -> None:
+        self._config = config
+
+    def make_agent_service(self) -> AiAgentService:
+        if self._config.local:
+            return AiAgentServiceLocal.get_instance()
+
+        if self._config.provider == AiAgentProvider.OLLAMA:
+            return AiAgentServiceOllama(
+                base_url=self._config.ollama_base_url,
+                default_model=self._config.default_model or "qwen2.5:14b",
+            )
+
+        if self._config.provider == AiAgentProvider.OPENAI:
+            if not self._config.openai_api_token:
+                raise ValueError("openai_api_token is required for the OpenAI provider")
+            return AiAgentServiceOpenai(
+                api_key=self._config.openai_api_token,
+                default_model=self._config.default_model or "gpt-4o",
+            )
+
+        raise ValueError(f"Unknown provider: {self._config.provider}")
+
+    @staticmethod
+    def make_ollama_service(
+        base_url: str = "http://localhost:11434",
+        default_model: str = "qwen2.5:14b",
+    ) -> AiAgentServiceOllama:
+        return AiAgentServiceOllama(base_url=base_url, default_model=default_model)
+
+    @staticmethod
+    def make_openai_service(
+        api_key: str,
+        default_model: str = "gpt-4o",
+    ) -> AiAgentServiceOpenai:
+        return AiAgentServiceOpenai(api_key=api_key, default_model=default_model)

zeroshot_agentic_workflows-0.1.5/src/zeroshot_agentic_workflows/param_mapper.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import inspect
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from .session import RepositorySession
+
+
+@dataclass
+class MappedArguments:
+    input: str
+    context: dict[str, Any] | None = None
+
+
+class AgentParameterMapper:
+    """Maps decorated method parameters to agent input JSON."""
+
+    def __init__(self, param_names: list[str]) -> None:
+        self._param_names = param_names
+
+    @classmethod
+    def from_function(cls, func: Any) -> AgentParameterMapper:
+        sig = inspect.signature(func)
+        names = [name for name, _param in sig.parameters.items() if name != "self"]
+        return cls(names)
+
+    def map_arguments(self, args: tuple[Any, ...]) -> MappedArguments:
+        input_obj: dict[str, Any] = {}
+        context: dict[str, Any] | None = None
+
+        for name, value in zip(self._param_names, args, strict=False):
+            if isinstance(value, RepositorySession):
+                continue
+            if name == "context":
+                context = value
+                continue
+            input_obj[name] = value
+
+        return MappedArguments(
+            input=json.dumps(input_obj, indent=2, default=str),
+            context=context,
+        )
+
+    def find_session(self, args: tuple[Any, ...]) -> RepositorySession | None:
+        for value in args:
+            if isinstance(value, RepositorySession):
+                return value
+        return None
+
+    def get_param_value(self, name: str, args: tuple[Any, ...]) -> Any:
+        for pname, value in zip(self._param_names, args, strict=False):
+            if pname == name:
+                return value
+        return None

zeroshot_agentic_workflows-0.1.5/src/zeroshot_agentic_workflows/prompt_utils.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+import yaml
+
+
+@dataclass
+class PromptFrontmatter:
+    tools: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ParsedPrompt:
+    frontmatter: PromptFrontmatter
+    content: str
+
+
+_FRONTMATTER_RE = re.compile(r"^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$")
+
+
+def parse_prompt_frontmatter(markdown: str) -> ParsedPrompt:
+    match = _FRONTMATTER_RE.match(markdown)
+    if not match:
+        return ParsedPrompt(frontmatter=PromptFrontmatter(), content=markdown)
+
+    raw_frontmatter = match.group(1)
+    content = match.group(2)
+
+    parsed = yaml.safe_load(raw_frontmatter) or {}
+    tools = parsed.get("tools", [])
+
+    return ParsedPrompt(
+        frontmatter=PromptFrontmatter(tools=tools or []),
+        content=content,
+    )
+
+
+def generate_tools_reference(tools: list[Any]) -> str:
+    if not tools:
+        return ""
+
+    lines = ["## Available Tools\n"]
+    for tool in tools:
+        name = getattr(tool, "name", str(tool))
+        description = getattr(tool, "description", "")
+        lines.append(f"### {name}")
+        if description:
+            lines.append(description)
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def map_tool_keys(
+    tool_keys: list[str],
+    registry: dict[str, str],
+) -> list[str]:
+    mapped: list[str] = []
+    for key in tool_keys:
+        if key not in registry:
+            available = ", ".join(sorted(registry.keys()))
+            raise ValueError(f"Tool key '{key}' not found in registry. Available: {available}")
+        mapped.append(registry[key])
+    return mapped
+
+
+def validate_tools_match(
+    declared_tool_names: list[str],
+    actual_tools: list[Any],
+) -> None:
+    actual_names = {getattr(t, "name", str(t)) for t in actual_tools}
+    declared_set = set(declared_tool_names)
+
+    missing = declared_set - actual_names
+    extra = actual_names - declared_set
+
+    errors: list[str] = []
+    if missing:
+        errors.append(f"Declared in frontmatter but not provided: {missing}")
+    if extra:
+        errors.append(f"Provided but not declared in frontmatter: {extra}")
+
+    if errors:
+        raise ValueError("; ".join(errors))

zeroshot_agentic_workflows-0.1.5/src/zeroshot_agentic_workflows/py.typed

@@ -0,0 +1 @@
+

zeroshot_agentic_workflows-0.1.5/src/zeroshot_agentic_workflows/service_ollama.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from agents import Agent, Runner
+from agents.model_settings import ModelSettings
+from agents.models.openai_chatcompletions import OpenAIChatCompletionsModel
+from openai import AsyncOpenAI
+
+from .agent_service import AgentConfig, AgentRunConfig, AgentRunResult, AgentType, T
+
+logger = logging.getLogger(__name__)
+
+
+class AiAgentServiceOllama:
+    """Ollama implementation via OpenAI-compatible API."""
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:11434",
+        default_model: str = "qwen2.5:14b",
+    ) -> None:
+        self._base_url = base_url
+        self._default_model = default_model
+        self._client = AsyncOpenAI(
+            base_url=f"{base_url}/v1",
+            api_key="ollama",
+        )
+
+    def create_agent(self, config: AgentConfig[T]) -> AgentType[T]:
+        return AgentType(config=config)
+
+    async def run_agent(
+        self,
+        agent: AgentType[T],
+        config: AgentRunConfig,
+    ) -> AgentRunResult[T]:
+        return await self.create_and_run(agent.config, config)
+
+    async def create_and_run(
+        self,
+        agent_config: AgentConfig[T],
+        run_config: AgentRunConfig,
+    ) -> AgentRunResult[T]:
+        try:
+            model_name = agent_config.model or self._default_model
+            model = OpenAIChatCompletionsModel(
+                model=model_name,
+                openai_client=self._client,
+            )
+
+            ms = agent_config.model_settings
+            if ms is not None and not isinstance(ms, ModelSettings):
+                ms = ModelSettings(**ms)
+
+            sdk_agent = Agent(
+                name=agent_config.name,
+                instructions=agent_config.instructions,
+                model=model,
+                tools=agent_config.tools or [],
+                output_type=agent_config.output_schema,
+                model_settings=ms or ModelSettings(),
+            )
+
+            run_kwargs: dict[str, Any] = {"input": run_config.input}
+            if run_config.context is not None:
+                run_kwargs["context"] = run_config.context
+            if run_config.max_turns is not None:
+                run_kwargs["max_turns"] = run_config.max_turns
+
+            result = await Runner.run(sdk_agent, **run_kwargs)
+
+            return AgentRunResult(
+                output=result.final_output,
+                success=True,
+                raw_result=result,
+            )
+        except Exception as exc:
+            error_msg = str(exc)
+            if "max_turns" in error_msg.lower():
+                logger.warning("Agent %s reached max turns", agent_config.name)
+            else:
+                logger.exception("Agent %s failed", agent_config.name)
+            return AgentRunResult(
+                output=None,  # type: ignore[arg-type]
+                success=False,
+                error=error_msg,
+            )

zeroshot_agentic_workflows-0.1.5/src/zeroshot_agentic_workflows/service_openai.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from agents import Agent, Runner
+from agents.model_settings import ModelSettings
+from agents.run import RunConfig
+
+from .agent_service import AgentConfig, AgentRunConfig, AgentRunResult, AgentType, T
+
+logger = logging.getLogger(__name__)
+
+
+class AiAgentServiceOpenai:
+    """OpenAI Agents SDK implementation."""
+
+    def __init__(self, api_key: str, default_model: str = "gpt-4o") -> None:
+        self._api_key = api_key
+        self._default_model = default_model
+
+    def create_agent(self, config: AgentConfig[T]) -> AgentType[T]:
+        return AgentType(config=config)
+
+    async def run_agent(
+        self,
+        agent: AgentType[T],
+        config: AgentRunConfig,
+    ) -> AgentRunResult[T]:
+        return await self.create_and_run(agent.config, config)
+
+    async def create_and_run(
+        self,
+        agent_config: AgentConfig[T],
+        run_config: AgentRunConfig,
+    ) -> AgentRunResult[T]:
+        try:
+            model = agent_config.model or self._default_model
+            ms = agent_config.model_settings
+            if ms is not None and not isinstance(ms, ModelSettings):
+                ms = ModelSettings(**ms)
+
+            sdk_agent = Agent(
+                name=agent_config.name,
+                instructions=agent_config.instructions,
+                model=model,
+                tools=agent_config.tools or [],
+                output_type=agent_config.output_schema,
+                model_settings=ms or ModelSettings(),
+            )
+
+            run_kwargs: dict[str, Any] = {"input": run_config.input}
+            if run_config.context is not None:
+                run_kwargs["context"] = run_config.context
+            if run_config.max_turns is not None:
+                run_kwargs["max_turns"] = run_config.max_turns
+
+            run_cfg = RunConfig(model=model)
+
+            result = await Runner.run(
+                sdk_agent,
+                run_config=run_cfg,
+                **run_kwargs,
+            )
+
+            return AgentRunResult(
+                output=result.final_output,
+                success=True,
+                raw_result=result,
+            )
+        except Exception as exc:
+            error_msg = str(exc)
+            if "max_turns" in error_msg.lower():
+                logger.warning("Agent %s reached max turns", agent_config.name)
+            else:
+                logger.exception("Agent %s failed", agent_config.name)
+            return AgentRunResult(
+                output=None,  # type: ignore[arg-type]
+                success=False,
+                error=error_msg,
+            )

zeroshot_agentic_workflows-0.1.5/src/zeroshot_agentic_workflows/session.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from time import time
+from typing import Any, Protocol, TypedDict, cast
+from uuid import uuid4
+
+CONVERSATION_SESSION_REPOSITORY = "CONVERSATION_SESSION_REPOSITORY"
+
+
+def _now_ms() -> int:
+    return int(time() * 1000)
+
+
+@dataclass(slots=True)
+class ConversationSessionModel:
+    session_id: str
+    client_id: str
+    created_at: int
+    updated_at: int
+
+
+@dataclass(slots=True)
+class ConversationItemModel:
+    item_id: str
+    session_id: str
+    sequence_number: int
+    role: str
+    content: str
+    metadata: str | None
+    created_at: int
+    deleted_at: int | None
+
+
+class ConversationMessage(TypedDict):
+    role: str
+    content: str
+    metadata: dict[str, Any] | None
+
+
+class InputTextPart(TypedDict):
+    type: str
+    text: str
+
+
+class SessionItem(TypedDict):
+    role: str
+    content: str | list[InputTextPart]
+
+
+class ConversationSessionRepository(Protocol):
+    async def create_session(self, client_id: str) -> ConversationSessionModel: ...
+
+    async def get_session(self, session_id: str) -> ConversationSessionModel: ...
+
+    async def get_conversation_items(
+        self,
+        session_id: str,
+        limit: int | None = None,
+    ) -> list[ConversationItemModel]: ...
+
+    async def add_conversation_items(
+        self,
+        session_id: str,
+        items: Sequence[ConversationMessage],
+    ) -> None: ...
+
+    async def clear_conversation(self, session_id: str) -> None: ...
+
+    async def pop_last_item(self, session_id: str) -> ConversationItemModel | None: ...
+
+
+class SessionNotFoundError(LookupError):
+    pass
+
+
+class InMemoryConversationSessionRepository:
+    def __init__(self) -> None:
+        self._sessions: dict[str, ConversationSessionModel] = {}
+        self._items: dict[str, list[ConversationItemModel]] = {}
+
+    async def create_session(self, client_id: str) -> ConversationSessionModel:
+        session_id = str(uuid4())
+        now = _now_ms()
+        session = ConversationSessionModel(
+            session_id=session_id,
+            client_id=client_id,
+            created_at=now,
+            updated_at=now,
+        )
+        self._sessions[session_id] = session
+        self._items[session_id] = []
+        return session
+
+    async def get_session(self, session_id: str) -> ConversationSessionModel:
+        session = self._sessions.get(session_id)
+        if session is None:
+            raise SessionNotFoundError(f"Session not found: {session_id}")
+        return session
+
+    async def get_conversation_items(
+        self,
+        session_id: str,
+        limit: int | None = None,
+    ) -> list[ConversationItemModel]:
+        session_items = self._items.get(session_id, [])
+        active_items = [item for item in session_items if item.deleted_at is None]
+        if limit:
+            return active_items[-limit:]
+        return active_items
+
+    async def add_conversation_items(
+        self,
+        session_id: str,
+        items: Sequence[ConversationMessage],
+    ) -> None:
+        session = await self.get_session(session_id)
+        session_items = self._items.get(session_id, [])
+        now = _now_ms()
+        sequence_number = max((item.sequence_number for item in session_items), default=-1) + 1
+
+        for item in items:
+            session_items.append(
+                ConversationItemModel(
+                    item_id=str(uuid4()),
+                    session_id=session_id,
+                    sequence_number=sequence_number,
+                    role=item["role"],
+                    content=item["content"],
+                    metadata=(
+                        json.dumps(item["metadata"]) if item.get("metadata") is not None else None
+                    ),
+                    created_at=now,
+                    deleted_at=None,
+                )
+            )
+            sequence_number += 1
+
+        self._items[session_id] = session_items
+        session.updated_at = now
+
+    async def clear_conversation(self, session_id: str) -> None:
+        session = await self.get_session(session_id)
+        session_items = self._items.get(session_id, [])
+        now = _now_ms()
+
+        for item in session_items:
+            if item.deleted_at is None:
+                item.deleted_at = now
+
+        session.updated_at = now
+
+    async def pop_last_item(self, session_id: str) -> ConversationItemModel | None:
+        session = await self.get_session(session_id)
+        session_items = self._items.get(session_id, [])
+        active_items = [item for item in session_items if item.deleted_at is None]
+        if not active_items:
+            return None
+
+        last_item = active_items[-1]
+        now = _now_ms()
+        last_item.deleted_at = now
+        session.updated_at = now
+        return last_item
+
+
+class RepositorySession:
+    def __init__(self, session_id: str, repository: ConversationSessionRepository) -> None:
+        self.session_id = session_id
+        self.repository = repository
+        self._cached_items: list[SessionItem] | None = None
+
+    def _to_content_parts(self, role: str, content: str) -> list[InputTextPart]:
+        if role == "user":
+            return [{"type": "input_text", "text": content}]
+        return [{"type": "output_text", "text": content}]
+
+    async def get_items(self, limit: int | None = None) -> list[SessionItem]:
+        if limit is None and self._cached_items is not None:
+            return self._cached_items
+
+        db_items = await self.repository.get_conversation_items(self.session_id, limit)
+        items: list[SessionItem] = [
+            SessionItem(
+                role=item.role,
+                content=self._to_content_parts(item.role, item.content),
+            )
+            for item in db_items
+        ]
+
+        if limit is None:
+            self._cached_items = items
+        return items
+
+    async def add_items(self, items: Sequence[Mapping[str, Any]]) -> None:
+        messages: list[ConversationMessage] = []
+        for item in items:
+            role = item.get("role")
+            if role not in {"user", "assistant", "system"} or "content" not in item:
+                continue
+            content = item["content"]
+            if isinstance(content, str):
+                serialized_content = content
+            else:
+                serialized_content = json.dumps(content)
+            messages.append(
+                ConversationMessage(
+                    role=cast(str, role),
+                    content=serialized_content,
+                    metadata=None,
+                )
+            )
+
+        if messages:
+            await self.repository.add_conversation_items(self.session_id, messages)
+        self._cached_items = None
+
+    async def clear_session(self) -> None:
+        await self.repository.clear_conversation(self.session_id)
+        self._cached_items = None
+
+    async def pop_item(self) -> SessionItem | None:
+        popped_item = await self.repository.pop_last_item(self.session_id)
+        self._cached_items = None
+        if popped_item is None:
+            return None
+        return SessionItem(
+            role=popped_item.role,
+            content=self._to_content_parts(popped_item.role, popped_item.content),
+        )

zeroshot_agentic_workflows-0.1.5/src/zeroshot_agentic_workflows/session_factory.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from .session import ConversationSessionRepository, RepositorySession
+
+
+class AiSessionFactory:
+    """Creates or retrieves RepositorySession instances."""
+
+    def __init__(self, repository: ConversationSessionRepository) -> None:
+        self._repository = repository
+
+    async def get_or_create_session(
+        self,
+        client_id: str,
+        session_id: str | None = None,
+    ) -> RepositorySession:
+        if session_id is not None:
+            await self._repository.get_session(session_id)
+            return RepositorySession(session_id, self._repository)
+
+        session = await self._repository.create_session(client_id)
+        return RepositorySession(session.session_id, self._repository)