agentsflowcompiler-lib 0.1.5__py3-none-any.whl

agentsflow/__init__.py

@@ -0,0 +1,53 @@
+"""
+agentsflow — PROD API
+=====================
+Production entry point. Import ``load_agents`` to load and run agents.
+
+Usage::
+
+    from agentsflow import load_agents
+
+    agents = load_agents("/path/to/agents_dir")
+    result = agents["my_agent"].run("Hello")
+"""
+
+from agentsflow._prod import load_agents
+from agentsflow.config import AgentsFlowConfig
+from agentsflow.errors import (
+    AgentsFlowError,
+    AgentsFlowConfigError,
+    AgentsFlowLogError,
+    AgentsFlowToolError,
+    MaxToolRoundsError,
+    LLMProviderError,
+    LLMAuthenticationError,
+    LLMInvalidRequestError,
+    LLMRateLimitError,
+    LLMServerError,
+)
+
+try:
+    from importlib.metadata import version, PackageNotFoundError
+except ImportError:  # pragma: no cover
+    from importlib_metadata import version, PackageNotFoundError  # type: ignore
+
+try:
+    __version__ = version("AgentsFlowCompiler-lib")
+except PackageNotFoundError:
+    # package is not installed
+    __version__ = "0.0.0"
+__all__ = [
+    "load_agents",
+    "AgentsFlowConfig",
+    "__version__",
+    "AgentsFlowError",
+    "AgentsFlowConfigError",
+    "AgentsFlowLogError",
+    "AgentsFlowToolError",
+    "MaxToolRoundsError",
+    "LLMProviderError",
+    "LLMAuthenticationError",
+    "LLMInvalidRequestError",
+    "LLMRateLimitError",
+    "LLMServerError",
+]

agentsflow/_prod.py

@@ -0,0 +1,72 @@
+"""
+agentsflow — Production Loader
+===============================
+Minimal PROD API: load agents from a directory and get ready-to-use Agent objects.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+
+from dotenv import load_dotenv
+
+if TYPE_CHECKING:
+    from agentsflow.agent import Agent
+    from agentsflow.config import AgentsFlowConfig
+
+logger = logging.getLogger(__name__)
+
+
+def load_agents(
+    agents_dir: str,
+    env_path: Optional[str] = None,
+    config: Optional["AgentsFlowConfig"] = None,
+) -> dict[str, "Agent"]:
+    """
+    Load all agents from a directory and return a dict of Agent instances.
+
+    This is the **single entry point** for production use.
+
+    Args:
+        agents_dir:  Path to the agents root directory (contains ``config/agents.yaml``
+                     and ``agents/`` subdirectory with per-agent configs).
+        env_path:    Optional path to a ``.env`` file. If provided, environment
+                     variables are loaded from it before resolving API keys.
+        config:      Optional SDK-wide config for log level, network logger silencing,
+                     and log format. If provided, applies log_level and optionally
+                     silence_network_loggers.
+
+    Returns:
+        Dict mapping agent name → ``Agent`` instance, ready to call ``.run()``.
+
+    Example::
+
+        from agentsflow import load_agents
+
+        agents = load_agents("/home/user/my_project/DEV")
+        result = agents["analyzer"].run("Analyze this data")
+
+        # With custom .env
+        agents = load_agents("/path/to/project", env_path="/path/to/.env")
+    """
+    # Load .env file if provided
+    if env_path:
+        _load_env_file(env_path)
+
+    # Apply SDK-wide config if provided
+    if config is not None:
+        from agentsflow.config import _apply_config
+        _apply_config(config)
+
+    from agentsflow.builder import build_agents
+    return build_agents(Path(agents_dir))
+
+
+def _load_env_file(env_path: str) -> None:
+    """Load environment variables from a .env file using python-dotenv."""
+    path = Path(env_path)
+    if not path.exists():
+        raise FileNotFoundError(f".env file not found: {path}")
+    load_dotenv(env_path)

agentsflow/agent/__init__.py

@@ -0,0 +1,9 @@
+"""
+agent package
+=============
+Public API: ``from agent import Agent``
+"""
+
+from .agent import Agent
+
+__all__ = ["Agent"]

agentsflow/agent/_utils.py

@@ -0,0 +1,122 @@
+"""
+Agent Utilities
+===============
+Shared helper functions used across the agent package:
+file loading, dynamic function import, and token counting.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from typing import Any, Callable, Optional, Union
+
+from tiktoken import encoding_for_model, get_encoding
+
+
+# ── File Loading ─────────────────────────────────────────────
+
+
+def load_file(path: Optional[Path]) -> Any:
+    """
+    Load a file and return its contents.
+
+    Supports:
+        .json  → parsed dict / list
+        .md / .txt / .text → raw string
+
+    Returns None if path is None.
+    Raises FileNotFoundError / ValueError for missing / unsupported files.
+    """
+    if path is None:
+        return None
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+
+    suffix = path.suffix.lower()
+    if suffix == ".json":
+        with open(path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    elif suffix in (".md", ".txt", ".text"):
+        with open(path, "r", encoding="utf-8") as f:
+            return f.read()
+    else:
+        raise ValueError(f"Unsupported file type: {suffix}")
+
+
+def load_prompt(base_dir: Path, relative_path: Optional[Path]) -> Any:
+    """Load a prompt file relative to a base directory."""
+    if not relative_path:
+        return None
+    full_path = (base_dir / relative_path).resolve()
+    if not full_path.is_relative_to(base_dir.resolve()):
+        raise ValueError(f"Path traversal detected: '{relative_path}' escapes base directory.")
+    return load_file(full_path)
+
+
+# ── Dynamic Function Loading ────────────────────────────────
+
+
+def _load_function(
+    module_path: Union[str, Path],
+    func_name: Optional[str],
+) -> Callable[..., Any]:
+    """
+    Dynamically import a callable from a Python module.
+
+    Args:
+        module_path: Absolute path to a .py file, or a dotted module name.
+        func_name:   Name of the callable inside the module.
+
+    Returns:
+        The callable object.
+    """
+    if not func_name:
+        raise ValueError("func_name is required")
+    if isinstance(module_path, Path):
+        module_path = module_path.resolve()
+        spec = importlib.util.spec_from_file_location(module_path.stem, module_path)
+        if spec is None or spec.loader is None:
+            raise ImportError(f"Cannot load module from file '{module_path}'")
+
+        module = importlib.util.module_from_spec(spec)
+        module_key = str(module_path)
+        sys.modules[module_key] = module
+        spec.loader.exec_module(module)
+    else:
+        module = importlib.import_module(module_path)
+
+    func = getattr(module, func_name, None)
+    if func is None:
+        raise AttributeError(
+            f"Module '{module.__name__}' has no attribute '{func_name}'"
+        )
+    if not callable(func):
+        raise TypeError(
+            f"Attribute '{func_name}' in module '{module.__name__}' is not callable"
+        )
+    return func
+
+
+# ── Token Counting ───────────────────────────────────────────
+
+
+def count_tokens(text: Optional[str], model: str = "o200k_base") -> int:
+    """
+    Count the number of tokens in *text* for the given *model*.
+
+    NOTE: This uses tiktoken (OpenAI's tokenizer). For non-OpenAI models (Claude, Llama, Gemini),
+    this is a pragmatic surrogate and may not be 100% accurate.
+    For maximum accuracy, use the count_tokens() method on the respective LLMClient instance.
+
+    Falls back to the ``o200k_base`` encoding when the model is unknown.
+    """
+    if text is None:
+        return 0
+    try:
+        encoding = encoding_for_model(model)
+    except KeyError:
+        encoding = get_encoding("o200k_base")
+    return len(encoding.encode(text))

agentsflow/agent/agent.py

@@ -0,0 +1,237 @@
+"""
+Agent — Core Runtime
+====================
+Slim orchestrator that wires together the modular components
+(prompts, tools, stats) and runs the LLM interaction loop.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any, Optional, Callable
+from uuid import uuid4
+
+from agentsflow.constants import AGENTS_DIR, DEFAULT_AGENT_TIMEOUT
+from agentsflow.schema import AgentConfig
+from agentsflow.llm import create_llm_client, LLMClient
+from agentsflow.types import ChatMessage, TokensSummary
+
+from .run_context import RunContext, RunResult
+from .llm_loop import run_llm_loop
+from .prompt_builder import build_system_prompt
+from .tools import AgentTools
+from .stats import AgentStats
+from ._utils import load_prompt, _load_function
+from agentsflow.logging_utils import log_structured
+
+logger = logging.getLogger(__name__)
+
+
+class Agent:
+    """
+    A single AI agent that can be run with ``agent.run(user_prompt)``.
+
+    Internally delegates to:
+        - ``AgentTools``   — tool schemas & execution
+        - ``AgentStats``   — logging & token tracking
+    """
+
+    def __init__(
+        self,
+        base_agents_dir: Path,
+        config: AgentConfig,
+        api_key: str,
+        base_url: Optional[str] = None,
+        tools_base_dir: Optional[Path] = None,
+        ) -> None:
+        self._agent_name = config.identity.name
+        # ── Paths ────────────────────────────────────────────
+        self._agent_dir = base_agents_dir / AGENTS_DIR / self._agent_name
+        # ── LLM Client ──────────────────────────────────────
+        self.client: LLMClient = create_llm_client(
+            model=config.model_settings.model,
+            api_key=api_key,
+            base_url=base_url,
+            provider=config.model_settings.provider,
+        )
+
+        # ── Prompts ─────────────────────────────
+        self._system_prompt = build_system_prompt(self._agent_dir, config.prompt_config)
+
+        # ── Output Format ────────────────────────────────────────────
+        self._json_schema = load_prompt(self._agent_dir, config.output_format_config.json_schema_path if config.output_format_config else None)
+        # ── Processing ────────────────────────────────────────────
+        self._preprocess_fn: Optional[Callable] = None
+        if config.preprocess_config:
+            self._preprocess_fn = _load_function(
+                (self._agent_dir / config.preprocess_config.path).resolve(),
+                config.preprocess_config.function_name,
+            )
+        self._postprocess_fn: Optional[Callable] = None
+        if config.postprocess_config:
+            self._postprocess_fn = _load_function(
+                self._agent_dir / config.postprocess_config.path,
+                config.postprocess_config.function_name,
+            )
+        # ── Tools ────────────────────────────────────────────
+
+        self._tools = AgentTools(
+            agent_dir=self._agent_dir,
+            tool_configs=config.tools if config.tools else [],
+            tools_base_dir=tools_base_dir,
+        )
+        # ── Stats / Logging ──────────────────────────────────
+        self._stats = AgentStats(
+            agent_dir=self._agent_dir,
+            client=self.client,
+            logs_config=config.logs_config,
+        )
+
+        # ── Config Shortcuts ─────────────────────────────────
+        self._temperature = config.model_settings.temperature
+        self._max_tokens = config.model_settings.max_tokens
+        self._timeout = config.model_settings.timeout
+        self._retry_config = config.model_settings.retry_config
+        self._return_format = config.output_format_config.return_format if config.output_format_config else "text"
+
+ 
+        # Log system prompt on init (hash-based dedup)
+        self._stats.log_system_prompt(self._system_prompt)
+
+
+    @property
+    def name(self) -> str:
+        return self._agent_name
+
+    @property
+    def model(self) -> str:
+        return self.client.model
+
+    @property
+    def provider(self) -> str:
+        return self.client.provider_name
+
+    # ── Run ──────────────────────────────────────────────────
+
+    def build_messages(self, user_prompt: str) -> list[ChatMessage]:
+        messages: list[ChatMessage] = []
+        if self._system_prompt:
+            messages.append({"role": "system", "content": self._system_prompt})
+        messages.append({"role": "user", "content": user_prompt})
+        return messages
+
+    def run(self, user_prompt: str, timeout: Optional[float] = None) -> RunResult:
+        ctx = self._create_run_context(user_prompt)
+        self._tools.reset_log()
+
+        log_structured(
+            logging.INFO,
+            "run_start",
+            rid=ctx.rid,
+            agent_name=getattr(self, "_agent_name", None),
+        )
+
+        try:
+            self._apply_preprocess(ctx)
+            ctx.messages = self.build_messages(ctx.llm_input)
+            ctx.llm_raw_output = run_llm_loop(
+                client=self.client,
+                messages=ctx.messages,
+                tools=self._tools,
+                temperature=self._temperature,
+                max_tokens=self._max_tokens,
+                response_format=self._build_response_format(),
+                timeout=timeout if timeout is not None else self._timeout,
+                retry_config=self._retry_config,
+                rid=ctx.rid,
+            )
+            ctx.llm_output = self._default_output_fn(ctx.llm_raw_output)
+            self._apply_postprocess(ctx)
+            self._finalize_run_state(ctx)
+            self._log_run(ctx)
+
+            log_structured(
+                logging.INFO,
+                "run_end",
+                rid=ctx.rid,
+                agent_name=getattr(self, "_agent_name", None),
+            )
+            return RunResult(
+                output=ctx.final_output,
+                rid=ctx.rid,
+                token_input=self.client.count_tokens(ctx.llm_input),
+                token_output=self.client.count_tokens(str(ctx.llm_output) if ctx.llm_output else ""),
+                tool_calls=self._tools.call_log,
+            )
+        except Exception as e:
+            log_structured(
+                logging.ERROR,
+                "run_error",
+                rid=ctx.rid,
+                agent_name=getattr(self, "_agent_name", None),
+                error=str(e),
+            )
+            raise
+
+    def get_tokens_summary(self, ctx: RunContext) -> TokensSummary:
+        return self._stats.get_tokens_summary(
+            system_prompt=self._system_prompt,
+            user_prompt=ctx.user_prompt,
+            rag_context=getattr(ctx, "rag_context", None),
+            answer=ctx.final_output,
+        )
+
+    # ── Private ──────────────────────────────────────────────
+
+    def _build_response_format(self) -> Optional[dict]:
+        if self._json_schema:
+            return {
+                "type": "json_schema",
+                "json_schema": {
+                    "name": self._agent_name,
+                    "schema": self._json_schema,
+                    "strict": True,
+                },
+            }
+        elif self._return_format == "json_object":
+            return {"type": "json_object"}
+        return None
+
+    def _create_run_context(self, user_prompt: str) -> RunContext:
+        return RunContext(rid=str(uuid4()), user_prompt=user_prompt, llm_input=user_prompt)
+
+    def _apply_preprocess(self, ctx: RunContext) -> None:
+        if self._preprocess_fn:
+            ctx.preprocess_output = self._preprocess_fn(ctx.user_prompt)
+            ctx.llm_input = str(ctx.preprocess_output)
+
+    def _apply_postprocess(self, ctx: RunContext) -> None:
+        if self._postprocess_fn:
+            ctx.postprocess_output = self._postprocess_fn(ctx.llm_output)
+            ctx.final_output = ctx.postprocess_output
+        else:
+            ctx.final_output = ctx.llm_output
+
+    def _finalize_run_state(self, ctx: RunContext) -> None:
+        pass
+
+    def _log_run(self, ctx: RunContext) -> None:
+        self._stats.log_io(
+            rid=ctx.rid,
+            input_text=ctx.user_prompt,
+            llm_input=ctx.llm_input,
+            llm_output=ctx.llm_output,
+            system_prompt=self._system_prompt,
+            preprocess_output=ctx.preprocess_output,
+            postprocess_output=ctx.postprocess_output,
+            tool_calls=self._tools.call_log if self._tools.call_log else None,
+        )
+
+    def _default_output_fn(self, output: str) -> Any:
+        """Try to parse output as JSON; fall back to raw string."""
+        try:
+            return json.loads(output)
+        except json.JSONDecodeError:
+            return output

agentsflow/agent/llm_loop.py

@@ -0,0 +1,137 @@
+"""
+LLM Loop
+========
+Provider-agnostic multi-turn chat loop with tool execution.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Optional
+
+from agentsflow.errors import LLMProviderError, LLMRateLimitError, LLMServerError, MaxToolRoundsError
+from agentsflow.llm import LLMClient
+from agentsflow.logging_utils import log_structured
+from agentsflow.schema import RetryConfig
+from agentsflow.types import ChatMessage, ToolCallSpec
+
+from .tools import AgentTools
+
+
+def run_llm_loop(
+    client: LLMClient,
+    messages: list[ChatMessage],
+    tools: AgentTools,
+    temperature: Optional[float],
+    max_tokens: Optional[int],
+    response_format: Optional[dict],
+    timeout: Optional[float] = None,
+    retry_config: Optional[RetryConfig] = None,
+    rid: Optional[str] = None,
+) -> str:
+    """Run the model loop until final text or max tool rounds."""
+    tool_schemas = tools.get_schemas(provider=client.provider_name)
+    rc = retry_config or RetryConfig()
+
+    import tenacity
+    from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
+
+    def _call_chat() -> str | dict:
+        try:
+            return client.chat(
+                messages=messages,
+                temperature=temperature,
+                max_tokens=max_tokens,
+                response_format=response_format if not tool_schemas else None,
+                tools=tool_schemas,
+                timeout=timeout,
+            )
+        except LLMProviderError as e:
+            log_structured(
+                logging.ERROR,
+                "llm_error",
+                rid=rid,
+                error=str(e),
+                provider_request_id=e.provider_request_id,
+            )
+            if rid and e.rid is None:
+                raise type(e)(
+                    e.args[0],
+                    cause=e,
+                    rid=rid,
+                    provider_request_id=e.provider_request_id,
+                ) from e
+            raise
+
+    @retry(
+        retry=retry_if_exception_type((LLMRateLimitError, LLMServerError)),
+        wait=wait_exponential(multiplier=1, min=rc.base_delay, max=rc.max_delay),
+        stop=stop_after_attempt(rc.max_attempts),
+        reraise=True,
+    )
+    def _call_chat_with_retry() -> str | dict:
+        return _call_chat()
+
+    for _round in range(AgentTools.MAX_TOOL_ROUNDS):
+        result = _call_chat_with_retry()
+
+        if isinstance(result, str):
+            return result
+
+        if isinstance(result, dict) and "tool_calls" in result:
+            append_assistant_tool_calls(messages, result["tool_calls"])
+            execute_tool_calls(tools, messages, result["tool_calls"], rid=rid)
+            continue
+
+        return str(result)
+
+    raise MaxToolRoundsError(
+        f"Agent exceeded {AgentTools.MAX_TOOL_ROUNDS} tool-calling rounds without a final answer."
+    )
+
+
+def append_assistant_tool_calls(
+    messages: list[ChatMessage], tool_calls: list[ToolCallSpec]
+) -> None:
+    """Append the assistant tool-call message in OpenAI-style format."""
+    messages.append({
+        "role": "assistant",
+        "content": None,
+        "tool_calls": [
+            {
+                "id": tc["id"],
+                "type": "function",
+                "function": {
+                    "name": tc["name"],
+                    "arguments": json.dumps(tc["arguments"]),
+                },
+            }
+            for tc in tool_calls
+        ],
+    })
+
+
+def execute_tool_calls(
+    tools: AgentTools,
+    messages: list[ChatMessage],
+    tool_calls: list[ToolCallSpec],
+    rid: Optional[str] = None,
+) -> None:
+    """Execute tool calls and append tool results to the transcript."""
+    agent_name = tools._agent_dir.name if hasattr(tools, "_agent_dir") else None
+    for tc in tool_calls:
+        log_structured(
+            logging.INFO,
+            "tool_call",
+            rid=rid,
+            agent_name=agent_name,
+            tool_name=tc["name"],
+            tool_arguments=tc.get("arguments"),
+        )
+        tool_result_str = tools.execute(tc["name"], tc["arguments"])
+        messages.append({
+            "role": "tool",
+            "tool_call_id": tc["id"],
+            "content": tool_result_str,
+        })