flatagents 4.0.1__tar.gz → 4.2.0__tar.gz

{flatagents-4.0.1 → flatagents-4.2.0}/AGENTS.md

@@ -22,7 +22,7 @@
 ```yaml
 # profiles.yml — agents reference by name
 spec: flatprofile
-spec_version: "4.0.1"
+spec_version: "4.2.0"
 data:
   model_profiles:
     fast: { provider: cerebras, name: zai-glm-4.6, temperature: 0.6 }

{flatagents-4.0.1 → flatagents-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flatagents
-Version: 4.0.1
+Version: 4.2.0
 Summary: A lightweight framework for building LLM-powered agents.
 Project-URL: Homepage, https://github.com/memgrafter/flatagents
 Project-URL: Repository, https://github.com/memgrafter/flatagents
@@ -17,7 +17,7 @@ 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-Python: >=3.11
 Requires-Dist: aiofiles
 Requires-Dist: httpx
 Requires-Dist: jinja2

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "4.0.1"
+__version__ = "4.2.0"
 
 from .baseagent import (
     # Base agent (abstract, for multi-step agents)

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/adapters/claude_code.py

@@ -838,7 +838,12 @@ class ClaudeCodeExecutor:
         # MCP server configuration
         mcp_config = cfg.get("mcp_config")
         if mcp_config:
-            args += ["--mcp-config", str(mcp_config)]
+            mcp_config_path = os.path.expanduser(str(mcp_config))
+            if not os.path.isabs(mcp_config_path):
+                mcp_config_path = os.path.join(self._config_dir, mcp_config_path)
+            if not os.path.isfile(mcp_config_path):
+                raise FileNotFoundError(f"Claude MCP config file not found: {mcp_config_path}")
+            args += ["--mcp-config", mcp_config_path]
 
         # Budget (0 = disabled)
         max_budget = cfg.get("max_budget_usd", 0)

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/adapters/codex_cli.py

@@ -40,6 +40,17 @@ Config keys (agent config or global settings.agent_runners.codex_cli):
   rate_limit_jitter   +/-seconds jitter (default: 0)
   use_app_server      bool -- use app-server transport (required for fork)
   session_source      App-server session source tag (default: "exec")
+
+Session semantics:
+  - FlatMachine ``state.session_id`` is accepted by execute() for executor
+    protocol compatibility only.  It is a machine-level cache/session key and
+    is NOT a Codex thread id.
+  - To resume an existing Codex CLI conversation/thread, pass
+    ``input.resume_session``.  Exec transport maps it to
+    ``codex exec resume <SESSION_ID>``; app-server transport maps it to
+    ``thread/resume``.
+  - Do not map arbitrary ``state.session_id`` values to Codex resume; Codex
+    requires the real thread id returned in ``output.thread_id``.
 """
 
 from __future__ import annotations
@@ -384,8 +395,9 @@ class CodexCliExecutor:
         """Execute a Codex CLI invocation.
 
         `session_id` is accepted for AgentExecutor protocol compatibility.
-        The Codex CLI adapter uses explicit `input.resume_session` to resume
-        existing Codex threads; `session_id` is intentionally ignored.
+        It is intentionally ignored because FlatMachine state session ids are
+        not Codex thread ids.  To resume a Codex CLI thread, pass the real
+        Codex thread id as `input.resume_session`.
         """
         task = input_data.get("task") or input_data.get("prompt", "")
         if not task:
@@ -641,7 +653,12 @@ class CodexCliExecutor:
         # Output schema
         output_schema = cfg.get("output_schema")
         if output_schema:
-            args += ["--output-schema", str(output_schema)]
+            output_schema_path = os.path.expanduser(str(output_schema))
+            if not os.path.isabs(output_schema_path):
+                output_schema_path = os.path.join(self._config_dir, output_schema_path)
+            if not os.path.isfile(output_schema_path):
+                raise FileNotFoundError(f"Codex output schema file not found: {output_schema_path}")
+            args += ["--output-schema", output_schema_path]
 
         # Additional directories
         add_dirs = cfg.get("add_dirs")
@@ -862,8 +879,13 @@ class CodexCliExecutor:
             # Load output schema if configured
             output_schema = None
             schema_path = self._merged.get("output_schema")
-            if schema_path and os.path.isfile(str(schema_path)):
-                with open(str(schema_path)) as f:
+            if schema_path:
+                schema_path = os.path.expanduser(str(schema_path))
+                if not os.path.isabs(schema_path):
+                    schema_path = os.path.join(self._config_dir, schema_path)
+                if not os.path.isfile(schema_path):
+                    raise FileNotFoundError(f"Codex output schema file not found: {schema_path}")
+                with open(schema_path) as f:
                     output_schema = json.load(f)
 
             await transport.turn_start(thread_id, text, output_schema)

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/adapters/pi_agent_bridge.py

@@ -103,8 +103,12 @@ def create_pi_agent_bridge_executor(
     runner_path = config.get("runner") or settings.get("runner")
     if not runner_path:
         runner_path = os.path.join(os.path.dirname(__file__), "pi_agent_runner.mjs")
-    elif not os.path.isabs(runner_path):
-        runner_path = os.path.join(config_dir, runner_path)
+    else:
+        runner_path = os.path.expanduser(runner_path)
+        if not os.path.isabs(runner_path):
+            runner_path = os.path.join(config_dir, runner_path)
+    if not os.path.isfile(runner_path):
+        raise FileNotFoundError(f"pi-agent runner file not found: {runner_path}")
 
     node_path = config.get("node") or settings.get("node") or "node"
     timeout = config.get("timeout") or settings.get("timeout")

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/adapters/smolagents.py

@@ -105,9 +105,11 @@ def _load_factory(ref: str, config_dir: str):
     module_ref, factory_name = _parse_ref(ref)
 
     if module_ref.endswith(".py") or module_ref.startswith(".") or "/" in module_ref:
-        module_path = module_ref
+        module_path = os.path.expanduser(module_ref)
         if not os.path.isabs(module_path):
             module_path = os.path.join(config_dir, module_path)
+        if not os.path.isfile(module_path):
+            raise FileNotFoundError(f"Smolagents factory file not found: {module_path}")
         spec = importlib.util.spec_from_file_location("smolagents_factory", module_path)
         if spec is None or spec.loader is None:
             raise ImportError(f"Unable to load smolagents factory from {module_path}")

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/assets/flatagent.d.ts

@@ -9,7 +9,7 @@
  * Each may be provided inline or by reference.
  */
 
-export const SPEC_VERSION = "4.0.1";
+export const SPEC_VERSION = "4.2.0";
 
 import {
   PromptWrapper,

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/assets/flatagent.schema.json

@@ -71,6 +71,9 @@
         "instruction_suffix": {
           "type": "string"
         },
+        "post_history_instructions": {
+          "type": "string"
+        },
         "output": {
           "$ref": "#/definitions/OutputSchema"
         },

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/assets/flatagent.slim.d.ts

@@ -1,4 +1,4 @@
-export const SPEC_VERSION = "4.0.1";
+export const SPEC_VERSION = "4.2.0";
 import { PromptWrapper, PromptData, PromptRef, OutputSchema, MCPConfig, ToolDefinition, } from "./prompt";
 import { ProfileWrapper, ProfileData, ProfileRef, ModelConfig, OAuthConfig, } from "./profile";
 export interface AgentWrapper {

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/assets/flatagents-runtime.d.ts

@@ -800,7 +800,7 @@ export interface BackendConfig {
     aws_region?: string;
 }
 
-export const SPEC_VERSION = "4.0.1";
+export const SPEC_VERSION = "4.2.0";
 
 export interface SDKRuntimeWrapper {
     spec: "flatagents-runtime";

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/assets/flatagents-runtime.schema.json

@@ -11,7 +11,7 @@
         },
         "spec_version": {
           "type": "string",
-          "const": "4.0.1"
+          "const": "4.2.0"
         },
         "execution_lock": {
           "$ref": "#/definitions/ExecutionLock"

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/assets/flatagents-runtime.slim.d.ts

@@ -252,7 +252,7 @@ export interface BackendConfig {
     dynamodb_table?: string;
     aws_region?: string;
 }
-export const SPEC_VERSION = "4.0.1";
+export const SPEC_VERSION = "4.2.0";
 export interface SDKRuntimeWrapper {
     spec: "flatagents-runtime";
     spec_version: typeof SPEC_VERSION;

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/assets/flatmachine.d.ts

@@ -190,7 +190,7 @@ waiting_channel     - Signal channel this machine is blocked on (v1.2.0)
 config_hash         - Content-addressed machine config key for cross-SDK resume (v2.1.0)
 */
 
-export const SPEC_VERSION = "4.0.1";
+export const SPEC_VERSION = "4.2.0";
 
 export interface MachineWrapper {
   spec: "flatmachine";
@@ -209,6 +209,7 @@ export interface MachineRuntimeMetadata {
   current_state: string;
   total_api_calls: number;
   total_cost: number;
+  depth?: number;
 }
 
 export interface MachineData {
@@ -245,6 +246,7 @@ export interface HooksRefConfig {
 export interface MachineSettings {
   max_steps?: number;
   parallel_fallback?: "sequential" | "error";
+  max_depth?: number;
   [key: string]: any;
 }
 
@@ -288,13 +290,13 @@ export interface StateDefinition {
 }
 
 export interface ToolLoopStateConfig {
-  max_tool_calls?: number;  // default: 50
-  max_turns?: number;       // default: 20
+  max_tool_calls?: number;  // default: 0 (unlimited)
+  max_turns?: number;       // default: 0 (unlimited); counts LLM calls, not tool calls
   allowed_tools?: string[]; // allowlist
   denied_tools?: string[];  // denylist (wins)
-  tool_timeout?: number;    // seconds, default: 30
-  total_timeout?: number;   // seconds, default: 600
-  max_cost?: number;        // dollars
+  tool_timeout?: number;    // seconds, default: 0 (unlimited)
+  total_timeout?: number;   // seconds, default: 0 (unlimited)
+  max_cost?: number;        // dollars, default: 0 (unlimited)
 }
 
 export interface MachineInput {
@@ -350,6 +352,7 @@ export interface MachineSnapshot {
     loop_cost: number;
   };
   config_hash?: string;
+  depth?: number;
 }
 
 export interface PersistenceConfig {

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/assets/flatmachine.schema.json

@@ -114,6 +114,9 @@
         },
         "total_cost": {
           "type": "number"
+        },
+        "depth": {
+          "type": "number"
         }
       },
       "required": [
@@ -210,6 +213,9 @@
         "instruction_suffix": {
           "type": "string"
         },
+        "post_history_instructions": {
+          "type": "string"
+        },
         "output": {
           "$ref": "#/definitions/OutputSchema"
         },
@@ -1124,6 +1130,9 @@
             "sequential",
             "error"
           ]
+        },
+        "max_depth": {
+          "type": "number"
         }
       }
     },

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/assets/flatmachine.slim.d.ts

@@ -1,4 +1,4 @@
-export const SPEC_VERSION = "4.0.1";
+export const SPEC_VERSION = "4.2.0";
 export interface MachineWrapper {
     spec: "flatmachine";
     spec_version: string;
@@ -14,6 +14,7 @@ export interface MachineRuntimeMetadata {
     current_state: string;
     total_api_calls: number;
     total_cost: number;
+    depth?: number;
 }
 export interface MachineData {
     name?: string;
@@ -42,6 +43,7 @@ export interface HooksRefConfig {
 export interface MachineSettings {
     max_steps?: number;
     parallel_fallback?: "sequential" | "error";
+    max_depth?: number;
     [key: string]: any;
 }
 export interface StateDefinition {
@@ -125,6 +127,7 @@ export interface MachineSnapshot {
         loop_cost: number;
     };
     config_hash?: string;
+    depth?: number;
 }
 export interface PersistenceConfig {
     enabled: boolean;

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/assets/profile.d.ts

@@ -14,7 +14,7 @@
  * It does not define prompt text or output schema.
  */
 
-export const SPEC_VERSION = "4.0.1";
+export const SPEC_VERSION = "4.2.0";
 
 export interface ProfileWrapper {
   spec: "flatprofile";

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/assets/profile.slim.d.ts

@@ -1,4 +1,4 @@
-export const SPEC_VERSION = "4.0.1";
+export const SPEC_VERSION = "4.2.0";
 export interface ProfileWrapper {
     spec: "flatprofile";
     spec_version: string;

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/assets/prompt.d.ts

@@ -5,14 +5,14 @@
  * Prompt is the pure prompt/output contract.
  *
  * It defines:
- * - authored prompt text (`system`, `user`, `instruction_suffix`)
+ * - authored prompt text (`system`, `user`, `instruction_suffix`, `post_history_instructions`)
  * - expected structured output (`output`)
  * - optional model-facing tool declarations (`tools`, `mcp`)
  *
  * It does not define runtime, model, profile, or adapter selection.
  */
 
-export const SPEC_VERSION = "4.0.1";
+export const SPEC_VERSION = "4.2.0";
 
 export interface PromptWrapper {
   spec: "prompt";
@@ -26,6 +26,7 @@ export interface PromptData {
   system?: string;
   user: string;
   instruction_suffix?: string;
+  post_history_instructions?: string;
   output?: OutputSchema;
   mcp?: MCPConfig;
   tools?: ToolDefinition[];

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/assets/prompt.schema.json

@@ -41,6 +41,9 @@
         "instruction_suffix": {
           "type": "string"
         },
+        "post_history_instructions": {
+          "type": "string"
+        },
         "output": {
           "$ref": "#/definitions/OutputSchema"
         },

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/assets/prompt.slim.d.ts

@@ -1,4 +1,4 @@
-export const SPEC_VERSION = "4.0.1";
+export const SPEC_VERSION = "4.2.0";
 export interface PromptWrapper {
     spec: "prompt";
     spec_version: string;
@@ -10,6 +10,7 @@ export interface PromptData {
     system?: string;
     user: string;
     instruction_suffix?: string;
+    post_history_instructions?: string;
     output?: OutputSchema;
     mcp?: MCPConfig;
     tools?: ToolDefinition[];

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/baseagent.py

@@ -1030,6 +1030,7 @@ class FlatAgent(ABC):
         config = {}
 
         if config_file is not None:
+            config_file = os.path.abspath(os.path.expanduser(config_file))
             if not os.path.exists(config_file):
                 raise FileNotFoundError(f"Configuration file not found: {config_file}")
 

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/flatagent.py

@@ -446,6 +446,7 @@ class FlatAgent:
         config_dir = kwargs.get("config_dir") or os.getcwd()
 
         if config_file is not None:
+            config_file = os.path.abspath(os.path.expanduser(config_file))
             if not os.path.exists(config_file):
                 raise FileNotFoundError(f"Configuration file not found: {config_file}")
             with open(config_file, 'r') as f:
@@ -515,7 +516,8 @@ class FlatAgent:
         except ImportError:
             yaml = None
 
-        path = ref if os.path.isabs(ref) else os.path.join(self._config_dir, ref)
+        expanded = os.path.expanduser(ref)
+        path = expanded if os.path.isabs(expanded) else os.path.join(self._config_dir, expanded)
         if not os.path.exists(path):
             raise FileNotFoundError(f"Referenced config file not found: {path}")
 
@@ -604,6 +606,7 @@ class FlatAgent:
             self._system_prompt_template = prompt_data.get('system', self.DEFAULT_SYSTEM_PROMPT)
             self._user_prompt_template = prompt_data.get('user', '')
             self._instruction_suffix = prompt_data.get('instruction_suffix', '')
+            self._post_history_instructions = prompt_data.get('post_history_instructions', '')
             self.output_schema = prompt_data.get('output', {})
             self.mcp_config = prompt_data.get('mcp')
             self.tools = prompt_data.get('tools', [])
@@ -615,6 +618,11 @@ class FlatAgent:
                 if self._instruction_suffix
                 else None
             )
+            self._compiled_post_history_instructions = (
+                self._jinja_env.from_string(self._post_history_instructions)
+                if self._post_history_instructions
+                else None
+            )
 
             if self._runtime_type == 'llm':
                 model_config = profile_data.get('model')
@@ -644,6 +652,7 @@ class FlatAgent:
         self._system_prompt_template = data.get('system', self.DEFAULT_SYSTEM_PROMPT)
         self._user_prompt_template = data.get('user', '')
         self._instruction_suffix = data.get('instruction_suffix', '')
+        self._post_history_instructions = data.get('post_history_instructions', '')
         self._compiled_system = self._jinja_env.from_string(self._system_prompt_template)
         self._compiled_user = self._jinja_env.from_string(self._user_prompt_template)
         self._compiled_instruction_suffix = (
@@ -651,6 +660,11 @@ class FlatAgent:
             if self._instruction_suffix
             else None
         )
+        self._compiled_post_history_instructions = (
+            self._jinja_env.from_string(self._post_history_instructions)
+            if self._post_history_instructions
+            else None
+        )
         self.output_schema = data.get('output', {})
         self.mcp_config = data.get('mcp')
         self.tools = data.get('tools', [])
@@ -904,6 +918,87 @@ class FlatAgent:
                 prompt = f"{prompt}\n\n{suffix}"
         return prompt
 
+    def _render_post_history_instructions(
+        self,
+        input_data: Dict[str, Any],
+        tools_prompt: str = "",
+        tools: Optional[List[Dict]] = None,
+    ) -> str:
+        """
+        Render post-history instructions with the same template context as prompts.
+
+        These instructions are not part of the stored logical conversation. They
+        are appended ephemerally to the final submitted user/tool message after
+        the full message history has been constructed.
+        """
+        if self._compiled_post_history_instructions is None:
+            return ""
+
+        model_config = {
+            **self._model_config_raw,
+            "name": self.model,
+            "temperature": self.temperature,
+            "max_tokens": self.max_tokens,
+            "top_p": self.top_p,
+            "top_k": self.top_k,
+            "frequency_penalty": self.frequency_penalty,
+            "presence_penalty": self.presence_penalty,
+            "seed": self.seed,
+            "base_url": self.base_url,
+        }
+        return self._compiled_post_history_instructions.render(
+            input=input_data,
+            tools_prompt=tools_prompt,
+            tools=tools or [],
+            model=model_config,
+        )
+
+    def _messages_with_post_history_instructions(
+        self,
+        messages: List[Dict[str, Any]],
+        post_history_instructions: str,
+    ) -> List[Dict[str, Any]]:
+        """
+        Return an ephemeral copy of messages with post-history instructions.
+
+        Rules:
+        - if the final submitted message is user/tool, append there;
+        - otherwise append a synthetic user message;
+        - never mutate the original list or message dicts.
+        """
+        instructions = (post_history_instructions or "").strip()
+        if not instructions:
+            return messages
+
+        copied = [dict(message) for message in messages]
+        body = f"System:\n\n{instructions}"
+
+        if copied and copied[-1].get("role") in ("user", "tool"):
+            self._append_post_history_to_message(copied[-1], body)
+        else:
+            copied.append({"role": "user", "content": body})
+        return copied
+
+    def _append_post_history_to_message(self, message: Dict[str, Any], body: str) -> None:
+        """Append rendered post-history body to one copied message in-place."""
+        content = message.get("content")
+        append_text = f"\n\n{body}"
+
+        if isinstance(content, str):
+            message["content"] = f"{content}{append_text}" if content else body
+            return
+
+        if isinstance(content, list):
+            text = append_text if content else body
+            message["content"] = list(content) + [{"type": "text", "text": text}]
+            return
+
+        if content is None:
+            message["content"] = body
+            return
+
+        message["content"] = f"{content}{append_text}"
+
     def _runtime_task_from_prompt(self, system_prompt: str, user_prompt: str) -> str:
         """Flatten prompt fields into a runtime task when needed."""
         if self._runtime_type == "claude-code":
@@ -1150,10 +1245,23 @@ class FlatAgent:
                 {"role": "user", "content": user_prompt}
             ]
 
+        # Append post-history instructions only to an ephemeral submit copy.
+        # The logical history, caller-provided messages, and rendered_user_prompt
+        # must remain unchanged so tool-loop chains/checkpoints never persist it.
+        post_history_instructions = self._render_post_history_instructions(
+            input_data,
+            tools_prompt=tools_prompt,
+            tools=_mcp_tools,
+        )
+        submit_messages = self._messages_with_post_history_instructions(
+            all_messages,
+            post_history_instructions,
+        )
+
         # Build LLM call parameters
         params = {
             "model": self.model,
-            "messages": all_messages,
+            "messages": submit_messages,
         }
         # Only include temperature if explicitly provided
         if self.temperature is not None:

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/monitoring.py

@@ -120,15 +120,21 @@ def setup_logging(
     if force:
         lib_logger.handlers.clear()
     
-    # Only add a handler if this logger has none yet (avoid duplicates)
-    if not lib_logger.handlers:
-        stdout_handler = logging.StreamHandler(sys.stdout)
-        stdout_handler.setFormatter(formatter)
-        lib_logger.addHandler(stdout_handler)
-    
-    # Prevent propagation to root to avoid duplicate output when the
-    # application also configures root-level handlers.
-    lib_logger.propagate = False
+    # Opt-in to a console handler via FLATAGENTS_LOG_HANDLER.
+    # This keeps headful apps (CLI, TUI, REPL) from seeing library
+    # logs unless the user explicitly requests them.
+    add_console = os.getenv('FLATAGENTS_LOG_HANDLER', '').lower() in ('stdout', 'console', 'true')
+    
+    if add_console:
+        if not lib_logger.handlers:
+            stdout_handler = logging.StreamHandler(sys.stdout)
+            stdout_handler.setFormatter(formatter)
+            lib_logger.addHandler(stdout_handler)
+        lib_logger.propagate = False
+    else:
+        # No stdout handler by default — logs propagate to the host app's
+        # root logger so headful apps control whether they appear on console.
+        lib_logger.propagate = True
     
     # Add file handler if FLATAGENTS_LOG_DIR is set
     log_dir = os.getenv('FLATAGENTS_LOG_DIR')
@@ -232,8 +238,13 @@ def _init_metrics() -> None:
             SERVICE_NAME: service_name
         })
         
-        # Check which exporter to use (default to console so metrics are visible)
-        exporter_type = os.getenv('OTEL_METRICS_EXPORTER', 'console').lower()
+        # Check which exporter to use (default to none — headful apps
+        # control whether metrics appear via explicit env opt-in).
+        exporter_type = os.getenv('OTEL_METRICS_EXPORTER', 'none').lower()
+        
+        if exporter_type == 'none':
+            _metrics_enabled = False
+            return
         
         if exporter_type == 'console':
             # Use console exporter for testing/debugging

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/profiles.py

@@ -196,7 +196,12 @@ class ProfileManager:
             if override_cfg:
                 result.update(override_cfg)
             else:
-                logger.warning(f"Override profile '{self._override_profile}' not found")
+                available_profiles = list(self._profiles.keys())
+                raise ValueError(
+                    f"Override profile '{self._override_profile}' not found. "
+                    f"The intended model override was NOT applied. "
+                    f"Available profiles: {available_profiles}"
+                )
 
         return result
 
@@ -224,9 +229,9 @@ def load_profiles_from_file(profiles_file: str) -> Dict[str, Any]:
     except ImportError:
         raise ImportError("pyyaml is required for profiles.yml")
 
+    profiles_file = os.path.abspath(os.path.expanduser(profiles_file))
     if not os.path.exists(profiles_file):
-        logger.debug(f"No profiles file at {profiles_file}")
-        return {'profiles': {}, 'default': None, 'override': None}
+        raise FileNotFoundError(f"Profiles file not found: {profiles_file}")
 
     with open(profiles_file, 'r') as f:
         config = yaml.safe_load(f) or {}
@@ -320,7 +325,13 @@ def discover_profiles_file(config_dir: str, explicit_path: Optional[str] = None)
         Path to profiles.yml if found, explicit_path if provided, or None
     """
     if explicit_path:
-        return explicit_path
+        path = os.path.expanduser(explicit_path)
+        if not os.path.isabs(path):
+            path = os.path.join(config_dir, path)
+        path = os.path.abspath(path)
+        if not os.path.exists(path):
+            raise FileNotFoundError(f"Profiles file not found: {path}")
+        return path
     default_path = os.path.join(config_dir, 'profiles.yml')
     return default_path if os.path.exists(default_path) else None
 

flatagents-4.2.0/flatagents/tests/test_monitoring.py

@@ -0,0 +1,189 @@
+"""Tests for monitoring.py — headful logging opt-in and metrics defaults."""
+
+import logging
+import sys
+import importlib
+
+import pytest
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+_ENV_KEYS = (
+    "FLATAGENTS_LOG_HANDLER",
+    "FLATAGENTS_LOG_LEVEL",
+    "FLATAGENTS_LOG_FORMAT",
+    "FLATAGENTS_LOG_DIR",
+    "FLATAGENTS_METRICS_ENABLED",
+    "OTEL_METRICS_EXPORTER",
+    "OTEL_SERVICE_NAME",
+    "OTEL_EXPORTER_OTLP_ENDPOINT",
+)
+
+
+def _reset_env(monkeypatch):
+    """Clear flatagents-related env vars."""
+    for key in _ENV_KEYS:
+        monkeypatch.delenv(key, raising=False)
+
+
+def _reset_module(mod):
+    """Reset flatagents.monitoring internal state."""
+    mod._logging_configured = False
+    mod._metrics_init_attempted = False
+    mod._metrics_enabled = False
+    mod._meter = None
+    mod._cached_histograms.clear()
+    lib_logger = logging.getLogger("flatagents")
+    lib_logger.handlers.clear()
+    lib_logger.propagate = True
+
+
+# ── Fixtures ────────────────────────────────────────────────────────────────
+
+
+@pytest.fixture(autouse=True)
+def _clean_flatagents(monkeypatch):
+    """Auto-reset env and module state for every test."""
+    _reset_env(monkeypatch)
+    mod = importlib.import_module("flatagents.monitoring")
+    _reset_module(mod)
+    yield
+
+
+# ── Issue 1: setup_logging ──────────────────────────────────────────────────
+
+
+class TestSetupLoggingDefault:
+    """setup_logging() adds no stdout handler and sets propagate=True."""
+
+    def test_no_console_handler_by_default(self):
+        from flatagents.monitoring import setup_logging
+
+        setup_logging()
+        lib_logger = logging.getLogger("flatagents")
+
+        stdout_handlers = [
+            h
+            for h in lib_logger.handlers
+            if isinstance(h, logging.StreamHandler)
+            and h.stream is sys.stdout
+        ]
+        assert len(stdout_handlers) == 0
+
+    def test_propagate_is_true_by_default(self):
+        from flatagents.monitoring import setup_logging
+
+        setup_logging()
+        lib_logger = logging.getLogger("flatagents")
+
+        assert lib_logger.propagate is True
+
+    def test_no_duplicate_handlers_on_second_call(self):
+        from flatagents.monitoring import setup_logging
+
+        setup_logging()
+        setup_logging()
+        lib_logger = logging.getLogger("flatagents")
+
+        stdout_handlers = [
+            h
+            for h in lib_logger.handlers
+            if isinstance(h, logging.StreamHandler)
+            and h.stream is sys.stdout
+        ]
+        assert len(stdout_handlers) <= 1
+
+
+class TestSetupLoggingOptIn:
+    """FLATAGENTS_LOG_HANDLER=stdout adds handler and sets propagate=False."""
+
+    @pytest.mark.parametrize(
+        "opt_in_value, should_add_handler",
+        [
+            ("stdout", True),
+            ("console", True),
+            ("true", True),
+            ("STDLONG", False),
+            ("1", False),
+            ("", False),
+        ],
+    )
+    def test_opt_in_variations(self, opt_in_value, should_add_handler, monkeypatch):
+        """Test various env values for FLATAGENTS_LOG_HANDLER."""
+        if opt_in_value:
+            monkeypatch.setenv("FLATAGENTS_LOG_HANDLER", opt_in_value)
+
+        from flatagents.monitoring import setup_logging
+
+        setup_logging()
+        lib_logger = logging.getLogger("flatagents")
+
+        stdout_handlers = [
+            h
+            for h in lib_logger.handlers
+            if isinstance(h, logging.StreamHandler)
+            and h.stream is sys.stdout
+        ]
+        assert len(stdout_handlers) == (1 if should_add_handler else 0)
+        # When handler added: propagate=False; when not: propagate=True
+        assert lib_logger.propagate == (not should_add_handler)
+
+
+# ── Issue 2: _init_metrics ─────────────────────────────────────────────────
+
+class TestInitMetricsDefault:
+    """_init_metrics() with default env does NOT create console exporter."""
+
+    def test_metrics_disabled_by_default(self):
+        """Even when otel is installed, default exporter=none disables metrics."""
+        try:
+            import opentelemetry  # noqa: F401
+        except ImportError:
+            pytest.skip("opentelemetry not installed")
+
+        import flatagents.monitoring as mod
+        from flatagents.monitoring import _init_metrics
+
+        _init_metrics()
+        assert mod._metrics_enabled is False
+
+    def test_get_meter_returns_none_when_metrics_disabled(self):
+        try:
+            import opentelemetry  # noqa: F401
+        except ImportError:
+            pytest.skip("opentelemetry not installed")
+
+        from flatagents.monitoring import get_meter
+
+        assert get_meter() is None
+
+
+class TestInitMetricsConsoleExporter:
+    """OTEL_METRICS_EXPORTER=console creates a console exporter."""
+
+    def test_metrics_enabled_with_console_exporter(self, monkeypatch):
+        try:
+            import opentelemetry  # noqa: F401
+        except ImportError:
+            pytest.skip("opentelemetry not installed")
+
+        monkeypatch.setenv("OTEL_METRICS_EXPORTER", "console")
+
+        import flatagents.monitoring as mod
+        from flatagents.monitoring import _init_metrics
+
+        _init_metrics()
+        assert mod._metrics_enabled is True
+
+    def test_get_meter_returns_meter_with_console_exporter(self, monkeypatch):
+        try:
+            import opentelemetry  # noqa: F401
+        except ImportError:
+            pytest.skip("opentelemetry not installed")
+
+        monkeypatch.setenv("OTEL_METRICS_EXPORTER", "console")
+
+        from flatagents.monitoring import get_meter
+
+        assert get_meter() is not None

flatagents-4.2.0/flatagents/tests/test_profiles.py

@@ -0,0 +1,25 @@
+"""Tests for model profile resolution."""
+
+import pytest
+
+from flatagents.profiles import ProfileManager
+
+
+def test_missing_override_profile_fails_fast_with_actionable_message():
+    manager = ProfileManager(
+        {
+            "profiles": {
+                "cheap": {"provider": "cerebras", "name": "zai-glm-4.6"},
+            },
+            "default": "cheap",
+            "override": "fast",
+        }
+    )
+
+    with pytest.raises(ValueError) as exc_info:
+        manager.resolve_model_config(None)
+
+    message = str(exc_info.value)
+    assert "Override profile 'fast' not found" in message
+    assert "intended model override was NOT applied" in message
+    assert "cheap" in message

{flatagents-4.0.1 → flatagents-4.2.0}/flatagents/tool_loop.py

@@ -55,14 +55,18 @@ class Tool:
 
 @dataclass
 class Guardrails:
-    """Configurable limits for the tool loop."""
-    max_tool_calls: int = 50
-    max_turns: int = 20
+    """Configurable limits for the tool loop.
+
+    Numeric guardrails use 0 to mean unlimited/disabled.
+    max_turns counts LLM calls, not tool calls.
+    """
+    max_tool_calls: int = 0
+    max_turns: int = 0
     allowed_tools: Optional[List[str]] = None
     denied_tools: Optional[List[str]] = None
-    tool_timeout: float = 30.0
-    total_timeout: float = 600.0
-    max_cost: Optional[float] = None
+    tool_timeout: float = 0.0
+    total_timeout: float = 0.0
+    max_cost: Optional[float] = 0.0
 
 
 @dataclass
@@ -228,7 +232,7 @@ class ToolLoopAgent:
         while True:
             # Check total timeout
             elapsed = time.monotonic() - start_time
-            if elapsed >= guardrails.total_timeout:
+            if guardrails.total_timeout > 0 and elapsed >= guardrails.total_timeout:
                 return ToolLoopResult(
                     content=last_content, messages=chain,
                     tool_calls_count=tool_calls_count, turns=turns,
@@ -236,7 +240,7 @@ class ToolLoopAgent:
                 )
 
             # Check max turns
-            if turns >= guardrails.max_turns:
+            if guardrails.max_turns > 0 and turns >= guardrails.max_turns:
                 return ToolLoopResult(
                     content=last_content, messages=chain,
                     tool_calls_count=tool_calls_count, turns=turns,
@@ -244,7 +248,7 @@ class ToolLoopAgent:
                 )
 
             # Check cost limit
-            if guardrails.max_cost is not None and usage.total_cost >= guardrails.max_cost:
+            if guardrails.max_cost is not None and guardrails.max_cost > 0 and usage.total_cost >= guardrails.max_cost:
                 return ToolLoopResult(
                     content=last_content, messages=chain,
                     tool_calls_count=tool_calls_count, turns=turns,
@@ -292,6 +296,7 @@ class ToolLoopAgent:
             if (
                 response.finish_reason == FinishReason.TOOL_USE
                 and guardrails.max_cost is not None
+                and guardrails.max_cost > 0
                 and usage.total_cost >= guardrails.max_cost
             ):
                 return ToolLoopResult(
@@ -312,7 +317,7 @@ class ToolLoopAgent:
 
             # We have tool calls — check guardrails before executing
             pending_calls = response.tool_calls or []
-            if tool_calls_count + len(pending_calls) > guardrails.max_tool_calls:
+            if guardrails.max_tool_calls > 0 and tool_calls_count + len(pending_calls) > guardrails.max_tool_calls:
                 return ToolLoopResult(
                     content=last_content, messages=chain,
                     tool_calls_count=tool_calls_count, turns=turns,
@@ -358,12 +363,13 @@ class ToolLoopAgent:
         if guardrails.allowed_tools and name not in guardrails.allowed_tools:
             return ToolResult(content=f"Tool '{name}' is not allowed", is_error=True)
 
-        # Execute via provider with timeout
+        # Execute via provider with timeout. 0 disables the per-tool timeout.
         try:
-            result = await asyncio.wait_for(
-                self._provider.execute_tool(name, tool_call_id, arguments),
-                timeout=guardrails.tool_timeout,
-            )
+            coroutine = self._provider.execute_tool(name, tool_call_id, arguments)
+            if guardrails.tool_timeout > 0:
+                result = await asyncio.wait_for(coroutine, timeout=guardrails.tool_timeout)
+            else:
+                result = await coroutine
             return result
         except asyncio.TimeoutError:
             return ToolResult(

{flatagents-4.0.1 → flatagents-4.2.0}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flatagents"
-version = "4.0.1"
+version = "4.2.0"
 description = "A lightweight framework for building LLM-powered agents."
 readme = "README.md"
 license = "Apache-2.0"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 authors = [
     { email = "memgrafter@gmail.com" }
 ]