maos-agent 0.1.0__tar.gz

maos_agent-0.1.0/.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

maos_agent-0.1.0/.python-version

@@ -0,0 +1 @@
+maos-agent

maos_agent-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: maos-agent
+Version: 0.1.0
+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>
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+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**.
+
+**`maos-agent`** provides the "Day 2" primitives required to run autonomous agents in production:
+
+1. **Zero-Config Telemetry:** Automatically emits Prometheus metrics for every tool call, token used, and cognitive step.
+2. **Spot Instance Resilience:** Handles `SIGTERM` signals from Kubernetes to allow graceful state checkpointing before node termination.
+
+---
+
+## Installation
+
+```bash
+pip install maos-agent
+
+```
+
+---
+
+## Quick Start
+
+Wrap your existing agent code with the Maos decorators to instantly get Grafana dashboards and Spot interruption protection.
+
+```python
+import time
+import random
+from maos_agent import MaosAgent, SpotInterruptionError
+
+# 1. Initialize (Starts Prometheus server on port 8000)
+agent = MaosAgent(service_name="financial-analyst", version="v1.2")
+
+# 2. Define Tools (Auto-tracked for success/failure rates)
+@agent.tool(name="stock_lookup")
+def get_stock_price(ticker: str):
+    # Simulate work
+    if random.random() < 0.05:
+        raise ConnectionError("API Timeout") # Recorded as 'error' in Grafana
+    return 150.00
+
+# 3. The Agent Loop
+def run_job():
+    # Track duration, steps, and success automatically
+    with agent.task("analyze_portfolio") as task:
+        print("Starting analysis...")
+        
+        for i in range(5):
+            # --- THE MAOS GUARANTEE ---
+            # Checks if K8s sent a termination signal (Spot reclaim).
+            # Raises SpotInterruptionError if node is draining.
+            agent.check_health() 
+            
+            # Record a "cognitive step" (thinking loop)
+            task.step() 
+            
+            price = get_stock_price("AAPL")
+            time.sleep(1)
+
+if __name__ == "__main__":
+    try:
+        run_job()
+    except SpotInterruptionError:
+        print("🚨 SPOT RECLAIM DETECTED! SAVING STATE TO REDIS...")
+        # Checkpoint your agent's memory here so it can resume on a new node
+        exit(0)
+
+```
+
+---
+
+## Key Features
+
+### 1. Automatic Telemetry (The "Brain Scan")
+
+Stop guessing if your agent is working. The SDK automatically exposes a `/metrics` endpoint on port `8000` (configurable) with standard Prometheus metrics:
+
+| Metric Name | Type | Description |
+| --- | --- | --- |
+| `maos_agent_tool_calls_total` | Counter | Tracks tool usage + Success/Error rates. |
+| `maos_agent_steps_per_goal` | Histogram | Detects "Loops of Death" (agents spinning in circles). |
+| `maos_agent_token_usage_total` | Counter | Tracks cost (Input vs Output tokens). |
+| `maos_agent_task_duration_seconds` | Histogram | End-to-end latency of jobs. |
+
+*Compatible with the [Maos Agent Quality Dashboard](https://www.google.com/search?q=https://github.com/maos-ai/platform/tree/main/dashboards).*
+
+### 2. Graceful Shutdown (The "Money Saver")
+
+Maos runs agents on Spot Instances to save you 90% on compute. However, Spot nodes can disappear with a 2-minute warning.
+
+The `agent.check_health()` method abstracts the complexity of Kubernetes signal handling.
+
+* **Normal operation:** Returns immediately.
+* **During Drain:** Raises `SpotInterruptionError`.
+
+**Best Practice:** Call `check_health()` inside your main `while` loop or before every LLM call.
+
+---
+
+## Configuration
+
+You can configure the agent via environment variables or constructor arguments.
+
+| Environment Variable | Default | Description |
+| --- | --- | --- |
+| `MAOS_SERVICE_NAME` | `unknown-agent` | The name of your agent (for filtering in Grafana). |
+| `MAOS_METRICS_PORT` | `8000` | Port to expose Prometheus metrics. |
+| `MAOS_LOG_LEVEL` | `INFO` | Logging verbosity. |
+
+---
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](https://www.google.com/search?q=CONTRIBUTING.md) for details.
+
+1. Fork the repo.
+2. Create a feature branch (`git checkout -b feature/langchain-integration`).
+3. Commit your changes.
+4. Open a Pull Request.
+
+---
+
+**Built by [Maos AI](https://www.google.com/search?q=https://maosproject.io) — The Control Plane for Autonomous Compute.**

maos_agent-0.1.0/README.md

@@ -0,0 +1,132 @@
+**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**.
+
+**`maos-agent`** provides the "Day 2" primitives required to run autonomous agents in production:
+
+1. **Zero-Config Telemetry:** Automatically emits Prometheus metrics for every tool call, token used, and cognitive step.
+2. **Spot Instance Resilience:** Handles `SIGTERM` signals from Kubernetes to allow graceful state checkpointing before node termination.
+
+---
+
+## Installation
+
+```bash
+pip install maos-agent
+
+```
+
+---
+
+## Quick Start
+
+Wrap your existing agent code with the Maos decorators to instantly get Grafana dashboards and Spot interruption protection.
+
+```python
+import time
+import random
+from maos_agent import MaosAgent, SpotInterruptionError
+
+# 1. Initialize (Starts Prometheus server on port 8000)
+agent = MaosAgent(service_name="financial-analyst", version="v1.2")
+
+# 2. Define Tools (Auto-tracked for success/failure rates)
+@agent.tool(name="stock_lookup")
+def get_stock_price(ticker: str):
+    # Simulate work
+    if random.random() < 0.05:
+        raise ConnectionError("API Timeout") # Recorded as 'error' in Grafana
+    return 150.00
+
+# 3. The Agent Loop
+def run_job():
+    # Track duration, steps, and success automatically
+    with agent.task("analyze_portfolio") as task:
+        print("Starting analysis...")
+        
+        for i in range(5):
+            # --- THE MAOS GUARANTEE ---
+            # Checks if K8s sent a termination signal (Spot reclaim).
+            # Raises SpotInterruptionError if node is draining.
+            agent.check_health() 
+            
+            # Record a "cognitive step" (thinking loop)
+            task.step() 
+            
+            price = get_stock_price("AAPL")
+            time.sleep(1)
+
+if __name__ == "__main__":
+    try:
+        run_job()
+    except SpotInterruptionError:
+        print("🚨 SPOT RECLAIM DETECTED! SAVING STATE TO REDIS...")
+        # Checkpoint your agent's memory here so it can resume on a new node
+        exit(0)
+
+```
+
+---
+
+## Key Features
+
+### 1. Automatic Telemetry (The "Brain Scan")
+
+Stop guessing if your agent is working. The SDK automatically exposes a `/metrics` endpoint on port `8000` (configurable) with standard Prometheus metrics:
+
+| Metric Name | Type | Description |
+| --- | --- | --- |
+| `maos_agent_tool_calls_total` | Counter | Tracks tool usage + Success/Error rates. |
+| `maos_agent_steps_per_goal` | Histogram | Detects "Loops of Death" (agents spinning in circles). |
+| `maos_agent_token_usage_total` | Counter | Tracks cost (Input vs Output tokens). |
+| `maos_agent_task_duration_seconds` | Histogram | End-to-end latency of jobs. |
+
+*Compatible with the [Maos Agent Quality Dashboard](https://www.google.com/search?q=https://github.com/maos-ai/platform/tree/main/dashboards).*
+
+### 2. Graceful Shutdown (The "Money Saver")
+
+Maos runs agents on Spot Instances to save you 90% on compute. However, Spot nodes can disappear with a 2-minute warning.
+
+The `agent.check_health()` method abstracts the complexity of Kubernetes signal handling.
+
+* **Normal operation:** Returns immediately.
+* **During Drain:** Raises `SpotInterruptionError`.
+
+**Best Practice:** Call `check_health()` inside your main `while` loop or before every LLM call.
+
+---
+
+## Configuration
+
+You can configure the agent via environment variables or constructor arguments.
+
+| Environment Variable | Default | Description |
+| --- | --- | --- |
+| `MAOS_SERVICE_NAME` | `unknown-agent` | The name of your agent (for filtering in Grafana). |
+| `MAOS_METRICS_PORT` | `8000` | Port to expose Prometheus metrics. |
+| `MAOS_LOG_LEVEL` | `INFO` | Logging verbosity. |
+
+---
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](https://www.google.com/search?q=CONTRIBUTING.md) for details.
+
+1. Fork the repo.
+2. Create a feature branch (`git checkout -b feature/langchain-integration`).
+3. Commit your changes.
+4. Open a Pull Request.
+
+---
+
+**Built by [Maos AI](https://www.google.com/search?q=https://maosproject.io) — The Control Plane for Autonomous Compute.**

maos_agent-0.1.0/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-0.1.0/decorators.py

@@ -0,0 +1,77 @@
+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"
+        
+        # 1. Record Success/Fail Counter
+        self.metrics.record_task_success(self.name, status)
+        
+        # 2. Record Duration
+        # We manually observe the histogram since we managed the time
+        from .metrics import TASK_DURATION
+        TASK_DURATION.labels(
+            task_type=self.name, 
+            **self.metrics.labels
+        ).observe(duration)
+
+        # 3. Record Steps (The "Loop of Death" check)
+        from .metrics import STEPS_PER_GOAL
+        STEPS_PER_GOAL.labels(
+            task_type=self.name, 
+            **self.metrics.labels
+        ).observe(self.steps)
+
+        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-0.1.0/examples/simple-worker.py

@@ -0,0 +1,36 @@
+import time
+import random
+from maos_agent import MaosAgent, SpotInterruptionError
+
+# 1. Initialize
+agent = MaosAgent(service_name="stock-analyst", version="v1.2")
+
+# 2. Define a Tool (Auto-tracked)
+@agent.tool(name="google_search")
+def search(query):
+    if random.random() < 0.1:
+        raise Exception("Network Error") # Will show as red in Grafana
+    return "Result"
+
+# 3. The Worker Loop
+def process_job():
+    print("Starting job...")
+    
+    # Track duration, steps, and success automatically
+    with agent.task("daily_report") as task:
+        for i in range(5):
+            # Check if Spot Instance is dying
+            agent.check_health() 
+            
+            # Simulate "Thinking"
+            task.step() 
+            search("Apple Stock")
+            time.sleep(1)
+
+if __name__ == "__main__":
+    try:
+        process_job()
+    except SpotInterruptionError:
+        print("🚨 SAVING STATE TO REDIS BEFORE DEATH...")
+        # Checkpoint logic here
+        exit(0)

maos_agent-0.1.0/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-0.1.0/metrics.py

@@ -0,0 +1,63 @@
+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"[Maos] Metrics server started on port {port}")
+        except Exception as e:
+            print(f"[Maos] 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 task_timer(self, task_type: str):
+        """Returns a context manager to time a task."""
+        return TASK_DURATION.labels(task_type=task_type, **self.labels).time()

maos_agent-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "maos-agent"
+version = "0.1.0"
+authors = [
+  { name="Maos AI", email="support@maosproject.io" },
+]
+description = "The Observability & Resilience SDK for Maos AI Agents"
+readme = "README.md"
+requires-python = ">=3.9"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    "prometheus-client>=0.17.0",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/maosproject-dev/maos-agent"
+"Bug Tracker" = "https://github.com/maosproject-dev/maos-agent/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["maos_agent"]