flatagents 0.1.0__py3-none-any.whl

flatagents/__init__.py

@@ -0,0 +1,30 @@
+__version__ = "0.1.0"
+
+from .baseagent import (
+    FlatAgent,
+    LLMBackend,
+    LiteLLMBackend,
+    AISuiteBackend,
+    Extractor,
+    FreeExtractor,
+    FreeThinkingExtractor,
+    StructuredExtractor,
+    ToolsExtractor,
+    RegexExtractor,
+)
+from .declarativeagent import DeclarativeAgent
+
+__all__ = [
+    "__version__",
+    "FlatAgent",
+    "LLMBackend",
+    "LiteLLMBackend",
+    "AISuiteBackend",
+    "Extractor",
+    "FreeExtractor",
+    "FreeThinkingExtractor",
+    "StructuredExtractor",
+    "ToolsExtractor",
+    "RegexExtractor",
+    "DeclarativeAgent",
+]

flatagents/baseagent.py

@@ -0,0 +1,699 @@
+"""
+Self-contained FlatAgent base class with pluggable LLM backends.
+
+Unifies the agent interface, configuration, and execution loop into a single class.
+LLM interaction is delegated to an LLMBackend, allowing different providers.
+"""
+
+import asyncio
+import logging
+import os
+import random
+from abc import ABC, abstractmethod
+from typing import Any, Tuple, Callable, List, Dict, Optional, Protocol, runtime_checkable
+
+logger = logging.getLogger(__name__)
+
+try:
+    import litellm
+except ImportError:
+    litellm = None
+
+try:
+    import aisuite
+except ImportError:
+    aisuite = None
+
+try:
+    import yaml
+except ImportError:
+    yaml = None
+
+import json
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# LLM Backend Protocol and Implementations
+# ─────────────────────────────────────────────────────────────────────────────
+
+@runtime_checkable
+class LLMBackend(Protocol):
+    """Protocol for LLM backends. Implement this to support different providers."""
+
+    total_cost: float
+    total_api_calls: int
+
+    async def call(
+        self,
+        messages: List[Dict[str, str]],
+        **kwargs
+    ) -> str:
+        """
+        Call the LLM with the given messages.
+
+        Args:
+            messages: List of message dicts with 'role' and 'content' keys
+            **kwargs: Additional parameters (temperature, max_tokens, etc.)
+
+        Returns:
+            The LLM response content as a string
+        """
+        ...
+
+    async def call_raw(
+        self,
+        messages: List[Dict[str, str]],
+        **kwargs
+    ) -> Any:
+        """
+        Call the LLM and return the raw response object.
+
+        Args:
+            messages: List of message dicts with 'role' and 'content' keys
+            **kwargs: Additional parameters (temperature, max_tokens, etc.)
+
+        Returns:
+            The raw LiteLLM/provider response object
+        """
+        ...
+
+
+class LiteLLMBackend:
+    """LLM backend using the litellm library."""
+
+    def __init__(
+        self,
+        model: str,
+        temperature: float = 0.7,
+        max_tokens: int = 2048,
+        top_p: float = 1.0,
+        frequency_penalty: float = 0.0,
+        presence_penalty: float = 0.0,
+        retry_delays: Optional[List[float]] = None,
+    ):
+        if litellm is None:
+            raise ImportError("litellm is required. Install with: pip install litellm")
+
+        self.model = model
+        self.llm_kwargs = {
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+            "top_p": top_p,
+            "frequency_penalty": frequency_penalty,
+            "presence_penalty": presence_penalty,
+        }
+        self.retry_delays = retry_delays or [1, 2, 4, 8]
+        self.total_cost = 0.0
+        self.total_api_calls = 0
+
+        logger.info(f"Initialized LiteLLMBackend with model: {model}")
+
+    async def call_raw(
+        self,
+        messages: List[Dict[str, str]],
+        **kwargs
+    ) -> Any:
+        """Call the LLM and return the raw response object with retry logic."""
+        call_kwargs = {**self.llm_kwargs, **kwargs}
+
+        last_exception = None
+        for attempt, delay in enumerate(self.retry_delays):
+            try:
+                self.total_api_calls += 1
+                logger.info(f"Calling LLM (Attempt {attempt + 1}/{len(self.retry_delays)})...")
+
+                response = await litellm.acompletion(
+                    model=self.model,
+                    messages=messages,
+                    **call_kwargs
+                )
+
+                if response is None or response.choices is None or len(response.choices) == 0:
+                    raise ValueError("Received an empty or invalid response from the LLM.")
+
+                # Track cost if available
+                if hasattr(response, '_hidden_params') and 'response_cost' in response._hidden_params:
+                    self.total_cost += response._hidden_params['response_cost']
+
+                return response
+
+            except Exception as e:
+                last_exception = e
+                logger.warning(f"LLM call failed on attempt {attempt + 1}: {e}")
+                if attempt < len(self.retry_delays) - 1:
+                    jittered_delay = delay + random.random()
+                    logger.info(f"Retrying in {jittered_delay:.2f} seconds...")
+                    await asyncio.sleep(jittered_delay)
+
+        logger.error("All retry attempts failed.")
+        raise last_exception or RuntimeError("LLM call failed after all retries")
+
+    async def call(
+        self,
+        messages: List[Dict[str, str]],
+        **kwargs
+    ) -> str:
+        """Call the LLM and return the content string."""
+        response = await self.call_raw(messages, **kwargs)
+        content = response.choices[0].message.content
+        if content is None:
+            raise ValueError("The LLM response content was empty.")
+        logger.info(f"LLM response received: '{content[:100]}...'")
+        return content
+
+
+class AISuiteBackend:
+    """
+    LLM backend using the aisuite library (by Andrew Ng).
+
+    Provides a unified interface to multiple providers:
+    OpenAI, Anthropic, Google, AWS, Cohere, Mistral, Ollama, HuggingFace.
+
+    Model format: "provider:model" (e.g., "openai:gpt-4o", "anthropic:claude-3-5-sonnet")
+    """
+
+    def __init__(
+        self,
+        model: str,
+        temperature: float = 0.7,
+        max_tokens: int = 2048,
+        top_p: float = 1.0,
+        retry_delays: Optional[List[float]] = None,
+    ):
+        if aisuite is None:
+            raise ImportError("aisuite is required. Install with: pip install aisuite")
+
+        # Normalize model format: accept both "provider/model" and "provider:model"
+        self.model = model.replace("/", ":", 1) if "/" in model else model
+        self.llm_kwargs = {
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+            "top_p": top_p,
+        }
+        self.retry_delays = retry_delays or [1, 2, 4, 8]
+        self.total_cost = 0.0
+        self.total_api_calls = 0
+        self.client = aisuite.Client()
+
+        logger.info(f"Initialized AISuiteBackend with model: {self.model}")
+
+    async def call_raw(
+        self,
+        messages: List[Dict[str, str]],
+        **kwargs
+    ) -> Any:
+        """Call the LLM and return the raw response object with retry logic."""
+        call_kwargs = {**self.llm_kwargs, **kwargs}
+
+        last_exception = None
+        for attempt, delay in enumerate(self.retry_delays):
+            try:
+                self.total_api_calls += 1
+                logger.info(f"Calling LLM via AISuite (Attempt {attempt + 1}/{len(self.retry_delays)})...")
+
+                # aisuite is sync-only, wrap in thread for async compatibility
+                response = await asyncio.to_thread(
+                    self.client.chat.completions.create,
+                    model=self.model,
+                    messages=messages,
+                    **call_kwargs
+                )
+
+                if response is None or response.choices is None or len(response.choices) == 0:
+                    raise ValueError("Received an empty or invalid response from the LLM.")
+
+                # Track cost from usage if available
+                if hasattr(response, 'usage') and response.usage:
+                    # Estimate cost based on token counts (rough estimate)
+                    # This is approximate; providers have different pricing
+                    usage = response.usage
+                    prompt_tokens = getattr(usage, 'prompt_tokens', 0) or 0
+                    completion_tokens = getattr(usage, 'completion_tokens', 0) or 0
+                    # Very rough estimate: $0.01 per 1K tokens average
+                    estimated_cost = (prompt_tokens + completion_tokens) * 0.00001
+                    self.total_cost += estimated_cost
+
+                return response
+
+            except Exception as e:
+                last_exception = e
+                logger.warning(f"AISuite call failed on attempt {attempt + 1}: {e}")
+                if attempt < len(self.retry_delays) - 1:
+                    jittered_delay = delay + random.random()
+                    logger.info(f"Retrying in {jittered_delay:.2f} seconds...")
+                    await asyncio.sleep(jittered_delay)
+
+        logger.error("All retry attempts failed.")
+        raise last_exception or RuntimeError("AISuite call failed after all retries")
+
+    async def call(
+        self,
+        messages: List[Dict[str, str]],
+        **kwargs
+    ) -> str:
+        """Call the LLM and return the content string."""
+        response = await self.call_raw(messages, **kwargs)
+        content = response.choices[0].message.content
+        if content is None:
+            raise ValueError("The LLM response content was empty.")
+        logger.info(f"LLM response received: '{content[:100]}...'")
+        return content
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Extractors (process LiteLLM responses into structured output)
+# ─────────────────────────────────────────────────────────────────────────────
+
+@runtime_checkable
+class Extractor(Protocol):
+    """Protocol for response extractors. Process raw LLM responses into structured output."""
+
+    def extract(self, response: Any) -> Any:
+        """
+        Extract structured data from a raw LLM response.
+
+        Args:
+            response: Raw response object from LLMBackend.call_raw()
+
+        Returns:
+            Extracted/structured data
+        """
+        ...
+
+
+class FreeExtractor:
+    """Returns the raw response content as-is. No parsing."""
+
+    def extract(self, response: Any) -> str:
+        """Extract raw content string."""
+        content = response.choices[0].message.content
+        return content if content is not None else ""
+
+
+class FreeThinkingExtractor:
+    """
+    Preserves reasoning/thinking from the response.
+    Returns: { "thinking": str, "response": str }
+
+    Works with models that return thinking in:
+    - A separate 'thinking' field
+    - Content blocks with type='thinking'
+    - <thinking> tags in content
+    """
+
+    def extract(self, response: Any) -> Dict[str, str]:
+        """Extract thinking and response separately."""
+        import re
+        message = response.choices[0].message
+        content = message.content or ""
+        thinking = ""
+
+        # Check for thinking in message attributes (provider-specific)
+        if hasattr(message, 'thinking') and message.thinking:
+            thinking = message.thinking
+        # Check for thinking in content blocks (Anthropic style)
+        elif hasattr(message, 'content_blocks'):
+            for block in message.content_blocks or []:
+                if getattr(block, 'type', None) == 'thinking':
+                    thinking = getattr(block, 'text', '')
+                elif getattr(block, 'type', None) == 'text':
+                    content = getattr(block, 'text', content)
+        # Check for <thinking> tags in content
+        elif '<thinking>' in content and '</thinking>' in content:
+            match = re.search(r'<thinking>(.*?)</thinking>', content, re.DOTALL)
+            if match:
+                thinking = match.group(1).strip()
+                content = re.sub(r'<thinking>.*?</thinking>', '', content, flags=re.DOTALL).strip()
+
+        return {"thinking": thinking, "response": content}
+
+
+class StructuredExtractor:
+    """
+    Extracts structured JSON output using response_format.
+    Requires the LLM call to include response_format parameter.
+    """
+
+    def __init__(self, schema: Optional[Dict] = None):
+        """
+        Args:
+            schema: Optional JSON schema for validation
+        """
+        self.schema = schema
+
+    def extract(self, response: Any) -> Dict[str, Any]:
+        """Extract and parse JSON from response."""
+        content = response.choices[0].message.content
+        if content is None:
+            return {}
+
+        try:
+            parsed = json.loads(content)
+            return parsed
+        except json.JSONDecodeError as e:
+            logger.warning(f"Failed to parse JSON response: {e}")
+            return {"_raw": content, "_error": str(e)}
+
+
+class ToolsExtractor:
+    """
+    Extracts tool calls from the response.
+    Returns: { "tool_calls": [...], "content": str }
+    """
+
+    def extract(self, response: Any) -> Dict[str, Any]:
+        """Extract tool calls and content."""
+        message = response.choices[0].message
+        content = message.content or ""
+        tool_calls = []
+
+        if hasattr(message, 'tool_calls') and message.tool_calls:
+            for tc in message.tool_calls:
+                tool_call = {
+                    "id": getattr(tc, 'id', None),
+                    "type": getattr(tc, 'type', 'function'),
+                    "function": {
+                        "name": tc.function.name if hasattr(tc, 'function') else None,
+                        "arguments": tc.function.arguments if hasattr(tc, 'function') else None,
+                    }
+                }
+                # Parse arguments JSON if present
+                if tool_call["function"]["arguments"]:
+                    try:
+                        tool_call["function"]["arguments"] = json.loads(
+                            tool_call["function"]["arguments"]
+                        )
+                    except json.JSONDecodeError:
+                        pass  # Keep as string if not valid JSON
+                tool_calls.append(tool_call)
+
+        return {"tool_calls": tool_calls, "content": content}
+
+
+class RegexExtractor:
+    """
+    Extracts fields from response using regex patterns.
+    Patterns are provided at runtime, not in the spec.
+
+    Can extract from:
+    - Raw LLM response object (response.choices[0].message.content)
+    - Plain string
+    """
+
+    def __init__(self, patterns: Dict[str, str], types: Optional[Dict[str, str]] = None):
+        """
+        Args:
+            patterns: Map of field names to regex patterns (must have capture group)
+            types: Optional map of field names to type names ('str', 'int', 'float', 'bool', 'json')
+        """
+        import re
+        self.patterns = {name: re.compile(pattern) for name, pattern in patterns.items()}
+        self.types = types or {}
+
+    def extract(self, response: Any) -> Optional[Dict[str, Any]]:
+        """Extract fields using regex patterns."""
+        # Handle both response object and plain string
+        if isinstance(response, str):
+            content = response
+        else:
+            content = response.choices[0].message.content
+
+        if content is None:
+            return None
+
+        result = {}
+        for field_name, pattern in self.patterns.items():
+            match = pattern.search(content)
+            if not match:
+                logger.debug(f"Field '{field_name}' pattern did not match")
+                return None
+
+            value = match.group(1)
+            field_type = self.types.get(field_name, 'str')
+
+            try:
+                if field_type == 'json':
+                    result[field_name] = json.loads(value)
+                elif field_type == 'int':
+                    result[field_name] = int(value)
+                elif field_type == 'float':
+                    result[field_name] = float(value)
+                elif field_type == 'bool':
+                    result[field_name] = value.lower() in ('true', '1', 'yes')
+                else:
+                    result[field_name] = value
+            except (json.JSONDecodeError, ValueError) as e:
+                logger.debug(f"Failed to parse field '{field_name}': {e}")
+                return None
+
+        return result
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# FlatAgent Base Class
+# ─────────────────────────────────────────────────────────────────────────────
+
+class FlatAgent(ABC):
+    """
+    Abstract base class for self-contained flat agents.
+
+    Combines the agent interface, configuration, and execution loop.
+    LLM interaction is delegated to a pluggable LLMBackend.
+
+    Configuration can be provided via:
+    - config_file: Path to a YAML configuration file
+    - config_dict: A dictionary with configuration
+    - backend: Custom LLMBackend instance (overrides config-based backend)
+    - **kwargs: Override individual parameters
+
+    Example usage:
+        class MyAgent(FlatAgent):
+            def create_initial_state(self): return {}
+            def generate_step_prompt(self, state): return "..."
+            def update_state(self, state, result): return {**state, 'result': result}
+            def is_solved(self, state): return state.get('done', False)
+
+        # Using config file (creates LiteLLMBackend automatically)
+        agent = MyAgent(config_file="config.yaml")
+
+        # Using custom backend
+        backend = LiteLLMBackend(model="openai/gpt-4", temperature=0.5)
+        agent = MyAgent(backend=backend)
+
+        trace = await agent.execute()
+    """
+
+    DEFAULT_SYSTEM_PROMPT = "You are a helpful assistant."
+
+    def __init__(
+        self,
+        config_file: Optional[str] = None,
+        config_dict: Optional[Dict] = None,
+        backend: Optional[LLMBackend] = None,
+        **kwargs
+    ):
+        """
+        Initialize the agent with configuration and optional backend.
+
+        Args:
+            config_file: Path to YAML config file
+            config_dict: Configuration dictionary
+            backend: Custom LLMBackend (if not provided, creates LiteLLMBackend from config)
+            **kwargs: Override specific config values
+        """
+        self._load_config(config_file, config_dict, **kwargs)
+
+        if backend is not None:
+            self.backend = backend
+        else:
+            self.backend = self._create_default_backend()
+
+        logger.info(f"Initialized {self.__class__.__name__} with backend: {self.backend.__class__.__name__}")
+
+    def _load_config(
+        self,
+        config_file: Optional[str],
+        config_dict: Optional[Dict],
+        **kwargs
+    ):
+        """Load and process configuration from file (YAML or JSON), dict, or kwargs."""
+        config = {}
+
+        if config_file is not None:
+            if not os.path.exists(config_file):
+                raise FileNotFoundError(f"Configuration file not found: {config_file}")
+
+            with open(config_file, 'r') as f:
+                if config_file.endswith('.json'):
+                    config = json.load(f) or {}
+                else:
+                    if yaml is None:
+                        raise ImportError("pyyaml is required for YAML config files. Install with: pip install pyyaml")
+                    config = yaml.safe_load(f) or {}
+        elif config_dict is not None:
+            config = config_dict
+
+        model_config = config.get('model', {})
+        defaults = config.get('litellm_defaults', {})
+
+        # Build model name from provider/name if needed
+        provider = model_config.get('provider')
+        model_name = model_config.get('name')
+        if provider and model_name and '/' not in model_name:
+            full_model_name = f"{provider}/{model_name}"
+        else:
+            full_model_name = model_name
+
+        def get_value(key: str, fallback: Any) -> Any:
+            return kwargs.get(key, model_config.get(key, defaults.get(key, fallback)))
+
+        # Store config values for backend creation
+        self.model = kwargs.get('model', full_model_name)
+        self.temperature = get_value('temperature', 0.7)
+        self.max_tokens = get_value('max_tokens', 2048)
+        self.top_p = get_value('top_p', 1.0)
+        self.frequency_penalty = get_value('frequency_penalty', 0.0)
+        self.presence_penalty = get_value('presence_penalty', 0.0)
+        self.retry_delays = model_config.get('retry_delays', [1, 2, 4, 8])
+
+        # Store raw config for subclass access
+        self.config = config
+
+    def _create_default_backend(self) -> LLMBackend:
+        """Create the default LiteLLMBackend from loaded config."""
+        if self.model is None:
+            raise ValueError("Model name is required. Provide via config file, config_dict, or 'model' kwarg.")
+
+        return LiteLLMBackend(
+            model=self.model,
+            temperature=self.temperature,
+            max_tokens=self.max_tokens,
+            top_p=self.top_p,
+            frequency_penalty=self.frequency_penalty,
+            presence_penalty=self.presence_penalty,
+            retry_delays=self.retry_delays,
+        )
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Convenience Properties (delegate to backend)
+    # ─────────────────────────────────────────────────────────────────────────
+
+    @property
+    def total_cost(self) -> float:
+        """Total cost accumulated by the backend."""
+        return self.backend.total_cost
+
+    @property
+    def total_api_calls(self) -> int:
+        """Total API calls made by the backend."""
+        return self.backend.total_api_calls
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Abstract Methods (subclasses must implement)
+    # ─────────────────────────────────────────────────────────────────────────
+
+    @abstractmethod
+    def create_initial_state(self, *args, **kwargs) -> Any:
+        """Create the initial state for the problem."""
+        pass
+
+    @abstractmethod
+    def generate_step_prompt(self, state: Any) -> str:
+        """Generate the user prompt for the next step based on current state."""
+        pass
+
+    @abstractmethod
+    def update_state(self, current_state: Any, step_result: Any) -> Any:
+        """Update the state based on the step result."""
+        pass
+
+    @abstractmethod
+    def is_solved(self, state: Any) -> bool:
+        """Check if the problem is solved."""
+        pass
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Overridable Hooks
+    # ─────────────────────────────────────────────────────────────────────────
+
+    def get_system_prompt(self) -> str:
+        """
+        Get the system prompt for LLM calls.
+        Override to customize the system prompt for your agent.
+        """
+        return self.DEFAULT_SYSTEM_PROMPT
+
+    def get_response_parser(self) -> Callable[[str], Any]:
+        """
+        Get the response parser for this agent.
+        Override to provide domain-specific parsing of LLM responses.
+        """
+        return lambda x: x
+
+    def validate_step_result(self, step_result: Any) -> bool:
+        """
+        Validate that a step result is acceptable before updating state.
+        Override for domain-specific validation.
+        """
+        return step_result is not None
+
+    def step_generator(self, state: Any) -> Tuple[Tuple[str, str], Callable[[str], Any]]:
+        """
+        Generate the prompt tuple and parser for the current state.
+
+        Returns:
+            Tuple of ((system_prompt, user_prompt), response_parser)
+
+        Override for full control over prompt generation.
+        """
+        system_prompt = self.get_system_prompt()
+        user_prompt = self.generate_step_prompt(state)
+        parser = self.get_response_parser()
+        return (system_prompt, user_prompt), parser
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Execution
+    # ─────────────────────────────────────────────────────────────────────────
+
+    async def execute(self, *args, **kwargs) -> List[Any]:
+        """
+        Execute the agent to solve the problem.
+
+        Args:
+            *args, **kwargs: Passed to create_initial_state()
+
+        Returns:
+            List of states representing the execution trace
+        """
+        logger.info(f"Starting execution with args={args}, kwargs={kwargs}")
+
+        state = self.create_initial_state(*args, **kwargs)
+        trace = [state]
+
+        while not self.is_solved(state):
+            prompt_tuple, parser = self.step_generator(state)
+            raw_result = await self._call_llm(prompt_tuple)
+            parsed_result = parser(raw_result)
+
+            if not self.validate_step_result(parsed_result):
+                logger.warning(f"Step result validation failed: {parsed_result}")
+
+            state = self.update_state(state, parsed_result)
+            trace.append(state)
+            logger.info("State updated.")
+
+        logger.info(f"Execution completed. Trace length: {len(trace)} states")
+        return trace
+
+    async def _call_llm(self, prompt_tuple: Tuple[str, str]) -> str:
+        """
+        Call the LLM backend with the given prompt.
+
+        Override this for custom pre/post processing around LLM calls.
+        """
+        system_prompt, user_prompt = prompt_tuple
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ]
+        return await self.backend.call(messages)

flatagents/declarativeagent.py

@@ -0,0 +1,255 @@
+"""
+DeclarativeAgent - A single LLM call configured entirely via YAML or JSON.
+
+See declarative-agent.d.ts for the TypeScript type definition.
+
+An agent is a single LLM call: model + prompts + output schema.
+Workflows handle composition, branching, and loops.
+"""
+
+import json
+import logging
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+try:
+    import jinja2
+except ImportError:
+    jinja2 = None
+
+try:
+    import litellm
+except ImportError:
+    litellm = None
+
+
+class DeclarativeAgent:
+    """
+    A single LLM call configured entirely via YAML. No code required.
+
+    v0.4.0 Container format:
+
+        spec: declarative_agent
+        spec_version: "0.4.0"
+
+        data:
+          name: greeter
+
+          model:
+            provider: cerebras
+            name: zai-glm-4.6
+            temperature: 0.7
+
+          system: "You are a friendly greeter."
+
+          user: |
+            Greet the user named {{ input.name }}.
+
+          output:
+            greeting:
+              type: str
+              description: "A friendly greeting message"
+
+        metadata:
+          author: "your-name"
+
+    Example usage:
+        agent = DeclarativeAgent(config_file="agent.yaml")
+        result = await agent.call(name="Alice")
+        print(result)  # {"greeting": "Hello, Alice!"}
+    """
+
+    SPEC_VERSION = "0.4.0"
+    DEFAULT_SYSTEM_PROMPT = "You are a helpful assistant."
+
+    def __init__(
+        self,
+        config_file: Optional[str] = None,
+        config_dict: Optional[Dict] = None,
+        **kwargs
+    ):
+        if jinja2 is None:
+            raise ImportError("jinja2 is required for DeclarativeAgent. Install with: pip install jinja2")
+        if litellm is None:
+            raise ImportError("litellm is required for DeclarativeAgent. Install with: pip install litellm")
+
+        self._load_config(config_file, config_dict, **kwargs)
+        self._validate_spec()
+        self._parse_agent_config()
+
+        # Tracking
+        self.total_cost = 0.0
+        self.total_api_calls = 0
+
+        logger.info(f"Initialized DeclarativeAgent: {self.agent_name}")
+
+    def _load_config(
+        self,
+        config_file: Optional[str],
+        config_dict: Optional[Dict],
+        **kwargs
+    ):
+        """Load v0.4.0 container config."""
+        import os
+        try:
+            import yaml
+        except ImportError:
+            yaml = None
+
+        config = {}
+        if config_file is not None:
+            if not os.path.exists(config_file):
+                raise FileNotFoundError(f"Configuration file not found: {config_file}")
+            with open(config_file, 'r') as f:
+                if config_file.endswith('.json'):
+                    config = json.load(f) or {}
+                else:
+                    if yaml is None:
+                        raise ImportError("pyyaml is required for YAML config files.")
+                    config = yaml.safe_load(f) or {}
+        elif config_dict is not None:
+            config = config_dict
+
+        self.config = config
+
+        # Extract model config from data section
+        data = config.get('data', {})
+        model_config = data.get('model', {})
+
+        # Build model name from provider/name
+        provider = model_config.get('provider')
+        model_name = model_config.get('name')
+        if provider and model_name and '/' not in model_name:
+            full_model_name = f"{provider}/{model_name}"
+        else:
+            full_model_name = model_name
+
+        # Set model attributes (with kwargs override)
+        self.model = kwargs.get('model', full_model_name)
+        self.temperature = kwargs.get('temperature', model_config.get('temperature', 0.7))
+        self.max_tokens = kwargs.get('max_tokens', model_config.get('max_tokens', 2048))
+
+    def _validate_spec(self):
+        """Validate the spec envelope."""
+        config = self.config
+
+        if config.get('spec') != 'declarative_agent':
+            raise ValueError(
+                f"Invalid spec: expected 'declarative_agent', got '{config.get('spec')}'. "
+                "Config must have: spec: declarative_agent"
+            )
+
+        if 'data' not in config:
+            raise ValueError("Config missing 'data' section")
+
+        spec_version = config.get('spec_version', '')
+        if not spec_version.startswith('0.4'):
+            logger.warning(f"spec_version '{spec_version}' may not be fully compatible with {self.SPEC_VERSION}")
+
+    def _parse_agent_config(self):
+        """Parse the v0.4.0 declarative configuration."""
+        data = self.config['data']
+        self.metadata = self.config.get('metadata', {})
+
+        # Agent name
+        self.agent_name = data.get('name') or self.metadata.get('name', 'unnamed-agent')
+
+        # Prompts
+        self._system_prompt = data.get('system', self.DEFAULT_SYSTEM_PROMPT)
+        self._user_prompt_template = data.get('user', '')
+        self._instruction_suffix = data.get('instruction_suffix', '')
+
+        # Compile Jinja2 template
+        self._jinja_env = jinja2.Environment(undefined=jinja2.StrictUndefined)
+        self._compiled_user = self._jinja_env.from_string(self._user_prompt_template)
+
+        # Output schema (stored for reference, extraction uses json_object mode)
+        self.output_schema = data.get('output', {})
+
+    def _render_user_prompt(self, input_data: Dict[str, Any]) -> str:
+        """Render user prompt with input data."""
+        prompt = self._compiled_user.render(input=input_data)
+        if self._instruction_suffix:
+            prompt = f"{prompt}\n\n{self._instruction_suffix}"
+        return prompt
+
+    def _build_output_instruction(self) -> str:
+        """Build instruction for JSON output based on schema."""
+        if not self.output_schema:
+            return ""
+
+        fields = []
+        for name, field_def in self.output_schema.items():
+            desc = field_def.get('description', '')
+            field_type = field_def.get('type', 'str')
+            enum_vals = field_def.get('enum')
+
+            parts = [f'"{name}"']
+            if desc:
+                parts.append(f"({desc})")
+            if enum_vals:
+                parts.append(f"- one of: {enum_vals}")
+
+            fields.append(" ".join(parts))
+
+        return "Respond with JSON containing: " + ", ".join(fields)
+
+    async def call(self, **input_data) -> Dict[str, Any]:
+        """
+        Execute a single LLM call with the given input.
+
+        Args:
+            **input_data: Input values available as {{ input.* }} in templates
+
+        Returns:
+            Dict with output fields as defined in the output schema
+        """
+        user_prompt = self._render_user_prompt(input_data)
+
+        # Add output instruction if we have a schema
+        output_instruction = self._build_output_instruction()
+        if output_instruction:
+            user_prompt = f"{user_prompt}\n\n{output_instruction}"
+
+        messages = [
+            {"role": "system", "content": self._system_prompt},
+            {"role": "user", "content": user_prompt}
+        ]
+
+        params = {
+            "model": self.model,
+            "messages": messages,
+            "temperature": self.temperature,
+            "max_tokens": self.max_tokens,
+        }
+
+        # Use JSON mode if we have an output schema
+        if self.output_schema:
+            params["response_format"] = {"type": "json_object"}
+
+        response = await litellm.acompletion(**params)
+
+        # Track usage
+        self.total_api_calls += 1
+        if hasattr(response, 'usage') and response.usage:
+            input_tokens = getattr(response.usage, 'prompt_tokens', 0)
+            output_tokens = getattr(response.usage, 'completion_tokens', 0)
+            self.total_cost += (input_tokens * 0.001 + output_tokens * 0.002) / 1000
+
+        content = response.choices[0].message.content
+
+        # Parse JSON response if we have an output schema
+        if self.output_schema and content:
+            try:
+                return json.loads(content)
+            except json.JSONDecodeError:
+                logger.warning(f"Failed to parse JSON response: {content}")
+                return {"_raw": content}
+
+        return {"_raw": content}
+
+    def call_sync(self, **input_data) -> Dict[str, Any]:
+        """Synchronous wrapper for call()."""
+        import asyncio
+        return asyncio.run(self.call(**input_data))

flatagents-0.1.0.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: flatagents
+Version: 0.1.0
+Summary: A lightweight framework for building LLM-powered agents with pluggable backends.
+Project-URL: Homepage, https://github.com/memgrafter/flatagents
+Project-URL: Repository, https://github.com/memgrafter/flatagents
+Project-URL: Issues, https://github.com/memgrafter/flatagents/issues
+Author-email: memgrafter@gmail.com
+License-Expression: MIT
+Keywords: agents,ai,aisuite,framework,litellm,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: jinja2
+Requires-Dist: pyyaml
+Provides-Extra: aisuite
+Requires-Dist: aisuite; extra == 'aisuite'
+Provides-Extra: all
+Requires-Dist: aisuite; extra == 'all'
+Requires-Dist: litellm; extra == 'all'
+Provides-Extra: litellm
+Requires-Dist: litellm; extra == 'litellm'
+Description-Content-Type: text/markdown
+
+# FlatAgents Python SDK
+
+Reference implementation of the [FlatAgents spec](../../README.md).
+
+## Installation
+
+```bash
+pip install flatagents[litellm]   # LiteLLM backend
+pip install flatagents[aisuite]   # AISuite backend
+pip install flatagents[all]       # Both backends
+```
+
+## Usage
+
+### From YAML/JSON Config
+
+```python
+from flatagents import DeclarativeAgent
+
+agent = DeclarativeAgent(config_file="agent.yaml")
+result = await agent.execute(input={"question": "What is 2+2?"})
+```
+
+### From Dictionary
+
+```python
+from flatagents import DeclarativeAgent
+
+config = {
+    "spec": "declarative_agent",
+    "spec_version": "0.4.0",
+    "data": {
+        "name": "calculator",
+        "model": {"provider": "openai", "name": "gpt-4"},
+        "system": "You are a calculator.",
+        "user": "Calculate: {{ input.expression }}",
+        "output": {
+            "result": {"type": "float", "description": "The calculated result"}
+        }
+    }
+}
+
+agent = DeclarativeAgent(config_dict=config)
+result = await agent.execute(input={"expression": "2 + 2"})
+```
+
+### Custom Agent (Subclass FlatAgent)
+
+```python
+from flatagents import FlatAgent
+
+class MyAgent(FlatAgent):
+    def create_initial_state(self):
+        return {"count": 0}
+
+    def generate_step_prompt(self, state):
+        return f"Count is {state['count']}. What's next?"
+
+    def update_state(self, state, result):
+        return {**state, "count": int(result)}
+
+    def is_solved(self, state):
+        return state["count"] >= 10
+
+agent = MyAgent(config_file="config.yaml")
+trace = await agent.execute()
+```
+
+## LLM Backends
+
+Two backends available:
+
+```python
+from flatagents import LiteLLMBackend, AISuiteBackend
+
+# LiteLLM - model format: provider/model
+backend = LiteLLMBackend(model="openai/gpt-4o", temperature=0.7)
+
+# AISuite - model format: provider:model
+backend = AISuiteBackend(model="openai:gpt-4o", temperature=0.7)
+```
+
+### Custom Backend
+
+Implement the `LLMBackend` protocol:
+
+```python
+class MyBackend:
+    total_cost: float = 0.0
+    total_api_calls: int = 0
+
+    async def call(self, messages: list, **kwargs) -> str:
+        self.total_api_calls += 1
+        return "response"
+
+agent = MyAgent(backend=MyBackend())
+```
+
+## License
+
+MIT License - see [LICENSE](../../LICENSE) for details.

flatagents-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+flatagents/__init__.py,sha256=iWJO0hDqTV7Mc5oGWbj_TzuEqkk5h289LFyEMkABdqk,569
+flatagents/baseagent.py,sha256=DAMMLeJ5eBVIuxUVUaHqgCmm0ro7j5r2NzQDFZ_iH6Q,26973
+flatagents/declarativeagent.py,sha256=QB-VfY1q7uLPddAsykGaRYWJF2Z7vxpHDpxvB4KjO9E,8352
+flatagents-0.1.0.dist-info/METADATA,sha256=1h_vmezUZ5TAHHlGtKWf1bLPrReWfuiy-gU0KQLiL18,3522
+flatagents-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+flatagents-0.1.0.dist-info/RECORD,,

flatagents-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any