maos-agent 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

maos_agent/__init__.py

@@ -0,0 +1,4 @@
+from .core import MaosAgent
+from .lifecycle import SpotInterruptionError
+
+__all__ = ["MaosAgent", "SpotInterruptionError"]

maos_agent/core.py

@@ -0,0 +1,30 @@
+from .metrics import MetricsManager
+from .lifecycle import LifecycleManager
+from .decorators import TaskContext, instrument_tool
+
+class MaosAgent:
+    def __init__(self, service_name: str, version: str = "v1.0", metrics_port: int = 8000):
+        self.service_name = service_name
+        self.metrics = MetricsManager(service_name, version, metrics_port)
+        self.lifecycle = LifecycleManager()
+
+    def check_health(self):
+        """
+        Proxy to lifecycle check. 
+        Raises SpotInterruptionError if the node is dying.
+        """
+        self.lifecycle.check_health()
+
+    def tool(self, name: str = None):
+        """
+        Decorator to track tool usage automatically.
+        Usage: @agent.tool(name="search")
+        """
+        return instrument_tool(self.metrics, name)
+
+    def task(self, name: str):
+        """
+        Context manager for the main job loop.
+        Usage: with agent.task("analyze") as task: ...
+        """
+        return TaskContext(self.metrics, name)

maos_agent/decorators.py

@@ -0,0 +1,63 @@
+import functools
+import time
+import logging
+
+# We import metrics inside the methods to avoid circular imports 
+# or we pass the metrics manager object into these classes.
+
+class TaskContext:
+    """
+    Context manager for a unit of work (Task).
+    Tracks duration, step count, and final success/failure status.
+    """
+    def __init__(self, metrics, name: str):
+        self.metrics = metrics
+        self.name = name
+        self.start_time = time.time()
+        self.steps = 0
+        self.logger = logging.getLogger("maos.agent")
+
+    def __enter__(self):
+        self.logger.info(f"Starting task: {self.name}")
+        return self
+
+    def step(self):
+        """
+        Record a 'cognitive step' (e.g., one LLM thought loop).
+        """
+        self.steps += 1
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        duration = time.time() - self.start_time
+        status = "error" if exc_type else "success"
+        
+        self.metrics.record_task_success(self.name, status)
+        self.metrics.record_steps(self.name, self.steps)
+        self.metrics.record_duration(self.name, duration)
+
+        if exc_type:
+            self.logger.error(f"Task '{self.name}' failed: {exc_val}")
+
+
+def instrument_tool(metrics, name: str = None):
+    """
+    Factory that returns the actual decorator.
+    We pass 'metrics' (the manager instance) in so the decorator knows where to record.
+    """
+    def decorator(func):
+        # Use the provided name or default to the function name
+        tool_name = name or func.__name__
+        
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            try:
+                result = func(*args, **kwargs)
+                # Record Success
+                metrics.record_tool(tool_name, status="success")
+                return result
+            except Exception as e:
+                # Record Failure & Re-raise
+                metrics.record_tool(tool_name, status="error")
+                raise e
+        return wrapper
+    return decorator

maos_agent/lifecycle.py

@@ -0,0 +1,28 @@
+import signal
+import sys
+import logging
+
+class SpotInterruptionError(Exception):
+    """Raised when the environment signals a shutdown."""
+    pass
+
+class LifecycleManager:
+    def __init__(self):
+        self.should_exit = False
+        self.logger = logging.getLogger("maos.lifecycle")
+        
+        # Register the signal handlers
+        signal.signal(signal.SIGTERM, self._handle_sigterm)
+        signal.signal(signal.SIGINT, self._handle_sigterm) # Handle Ctrl+C locally too
+
+    def _handle_sigterm(self, signum, frame):
+        self.logger.warning("⚠️ SIGTERM received from Kubernetes! Node is draining.")
+        self.should_exit = True
+
+    def check_health(self):
+        """
+        Call this inside your agent loop.
+        If a kill signal was received, it raises an exception to break the loop safely.
+        """
+        if self.should_exit:
+            raise SpotInterruptionError("Spot Instance Reclaim Imminent")

maos_agent/metrics.py

@@ -0,0 +1,65 @@
+from prometheus_client import Counter, Histogram, start_http_server
+import time
+
+# --- Metric Definitions (Must match Grafana Queries) ---
+
+# Histogram: maos_agent_task_duration_seconds
+TASK_DURATION = Histogram(
+    'maos_agent_task_duration_seconds',
+    'Time spent executing the agent task',
+    ['task_type', 'service_name', 'version']
+)
+
+# Counter: maos_agent_tool_calls_total
+TOOL_CALLS = Counter(
+    'maos_agent_tool_calls_total',
+    'Total number of tool invocations',
+    ['tool_name', 'status', 'service_name', 'version']
+)
+
+# Counter: maos_agent_token_usage_total
+TOKEN_USAGE = Counter(
+    'maos_agent_token_usage_total',
+    'Total LLM tokens consumed',
+    ['model', 'type', 'service_name', 'version']
+)
+
+# Histogram: maos_agent_steps_per_goal
+STEPS_PER_GOAL = Histogram(
+    'maos_agent_steps_per_goal',
+    'Number of cognitive steps taken to solve a goal',
+    ['task_type', 'service_name', 'version'],
+    buckets=[1, 3, 5, 10, 20, 50] # Optimized for "Loop of Death" detection
+)
+
+# Counter: maos_agent_task_success_total
+TASK_SUCCESS = Counter(
+    'maos_agent_task_success_total',
+    'Total task completions',
+    ['task_type', 'status', 'service_name', 'version']
+)
+
+class MetricsManager:
+    def __init__(self, service_name: str, version: str = "v1", port: int = 8000):
+        self.labels = {"service_name": service_name, "version": version}
+        # Start the Prometheus exporter server automatically
+        try:
+            start_http_server(port)
+            print(f"[Maosproject] Metrics server started on port {port}")
+        except Exception as e:
+            print(f"[Maosproject] Warning: Could not start metrics server: {e}")
+
+    def record_tool(self, tool_name: str, status: str = "success"):
+        TOOL_CALLS.labels(tool_name=tool_name, status=status, **self.labels).inc()
+
+    def record_tokens(self, count: int, model: str = "unknown", type: str = "total"):
+        TOKEN_USAGE.labels(model=model, type=type, **self.labels).inc(count)
+
+    def record_task_success(self, task_type: str, status: str):
+        TASK_SUCCESS.labels(task_type=task_type, status=status, **self.labels).inc()
+
+    def record_duration(self, task_type: str, seconds: float):
+        TASK_DURATION.labels(task_type=task_type, **self.labels).observe(seconds)
+
+    def record_steps(self, task_type: str, count: int):
+        STEPS_PER_GOAL.labels(task_type=task_type, **self.labels).observe(count)

{maos_agent-0.1.0.dist-info → maos_agent-0.1.2.dist-info}/METADATA

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: maos-agent
-Version: 0.1.0
+Version: 0.1.2
 Summary: The Observability & Resilience SDK for Maos AI Agents
 Project-URL: Homepage, https://github.com/maosproject-dev/maos-agent
 Project-URL: Bug Tracker, https://github.com/maosproject-dev/maos-agent/issues
 Author-email: Maos AI <support@maosproject.io>
+License-File: LICENSE
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
@@ -13,16 +14,6 @@ Requires-Python: >=3.9
 Requires-Dist: prometheus-client>=0.17.0
 Description-Content-Type: text/markdown
 
-**CTO here.**
-
-Here is the `README.md`.
-
-It is written to be "Marketing-Engineering" aligned. It doesn't just say *how* to use it; it explains *why* a developer needs it (to stop their agents from dying silently on Spot instances).
-
-I’ve added badges, a clear "Quick Start," and a section linking the metrics directly to the Grafana dashboard we just built.
-
----
-
 # Maos Agent SDK
 
 The official Python SDK for building resilient, observable AI Agents on the **Maos Platform**.
@@ -144,4 +135,4 @@ We welcome contributions! Please see [CONTRIBUTING.md](https://www.google.com/se
 
 ---
 
-**Built by [Maos AI](https://www.google.com/search?q=https://maosproject.io) — The Control Plane for Autonomous Compute.**
+**Built by [Maosproject Platform](https://www.google.com/search?q=https://maosproject.io) — The Control Plane for Autonomous Compute.**

maos_agent-0.1.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+maos_agent/__init__.py,sha256=VS0Tmmk8fzdrtu0XISOgjVqJpkOACzgoE9JPPkWtcL0,122
+maos_agent/core.py,sha256=KIgPkCFHJAKvX140GzpRQZMgKA9UrofIeF8lv6gTYD0,997
+maos_agent/decorators.py,sha256=7OFy8BPTZJqP3dH-Pq7ZMHvEK3BFQcP25Y5osO8Bnxk,2012
+maos_agent/lifecycle.py,sha256=RIJzRUyfxX9tMc_A-IQtgFFhJF2GyC0xUE5RVtgQ_Ko,937
+maos_agent/metrics.py,sha256=9KSTHx87-3G0EqBExirDUTq4oYYxhXoLnLkmyQaFPh4,2414
+maos_agent-0.1.2.dist-info/METADATA,sha256=ZXE2uXmokk3Y51WoTHZSSGQnFUpSjmSCSWtZ1NdzFIo,4713
+maos_agent-0.1.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+maos_agent-0.1.2.dist-info/licenses/LICENSE,sha256=pSwPJCJHLTj7MzXnoRrLL1a9wblFZoynxjBdlHvkv3E,1071
+maos_agent-0.1.2.dist-info/RECORD,,

maos_agent-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 maosproject.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

maos_agent-0.1.0.dist-info/RECORD

@@ -1,3 +0,0 @@
-maos_agent-0.1.0.dist-info/METADATA,sha256=q2GwYBKeRMPLRhQyBY0vrFo-ohcycm7art2Dm60Bmqg,5044
-maos_agent-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-maos_agent-0.1.0.dist-info/RECORD,,