Metadata-Version: 2.4
Name: marg-sdk
Version: 0.1.0
Summary: Marg MCP Telemetry SDK
Author-email: Falak Rana <ranafalak18@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/falakrana/MargMCP
Project-URL: Repository, https://github.com/falakrana/MargMCP
Project-URL: Issues, https://github.com/falakrana/MargMCP/issues
Keywords: telemetry,observability,mcp,agents,ai-agents,llm,opentelemetry,tracing,monitoring
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: responses>=0.24.1; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.1.0; extra == "test"
Requires-Dist: responses>=0.24.1; extra == "test"
Dynamic: license-file

# Marg MCP SDK

[![PyPI version](https://img.shields.io/pypi/v/marg-sdk.svg)](https://pypi.org/project/marg-sdk/)
[![Python versions](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://pypi.org/project/marg-sdk/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

Python SDK for instrumenting AI agents with [Marg MCP](https://github.com/falakrana/MargMCP) telemetry.

- **Lightweight**: `pydantic` and `requests` only.
- **Non-blocking**: events are batched and exported on a background queue.
- **Best-effort by default**: telemetry failures and queue overflows never crash your agent.
- **Private by default**: payloads and sensitive data are redacted unless you opt in.

Requires Python **3.9+**.

## Installation

```bash
pip install marg-sdk
```

For local development from a checkout:

```bash
pip install -e ".[dev]"
```

## Quickstart

```python
from marg_sdk import Marg

marg = Marg.from_env()

with marg.start_run(agent_id="my-agent") as run:
    # ... your agent logic here
    run.set_output_summary({"result": "Success"})
```

Events are buffered and flushed automatically on a background thread. On
short-lived processes, call `marg.shutdown()` before exit to flush remaining
events:

```python
marg.shutdown(timeout=5.0)
```

## Recording custom events

```python
with marg.start_run(agent_id="my-agent") as run:
    run.record_event("llm_call", data={"model": "gpt-4o", "tokens": 512})
    run.record_event("tool_call", data={"tool": "search", "status": "ok"})
```

Run lifecycle events (`run_started`, `run_completed`, `run_failed`) are
recorded automatically by the context manager, including failure details when
an exception escapes the `with` block.

## Configuration

Create the client from environment variables with `Marg.from_env()`, or pass a
`MargConfig` directly:

```python
from marg_sdk import Marg, MargConfig

marg = Marg(MargConfig(
    api_endpoint="https://marg.example.com",
    api_key="...",
    project_id="my-project",
    environment="production",
))
```

### Environment variables

| Variable                  | Fallback (legacy)         | Default                 |
| ------------------------- | ------------------------- | ----------------------- |
| `MARG_API_ENDPOINT`       | `AGENTOPS_API_ENDPOINT`   | `http://localhost:8000` |
| `MARG_API_KEY`            | `AGENTOPS_API_KEY`        | None                    |
| `MARG_PROJECT_ID`         | `AGENTOPS_PROJECT_ID`     | None                    |
| `MARG_AGENT_ID`           | `AGENTOPS_AGENT_ID`       | None                    |
| `MARG_ENV`                | `AGENTOPS_ENV`            | `development`           |
| `MARG_DEPLOYMENT_VERSION` | `AGENTOPS_DEPLOYMENT_VERSION` | None                |
| `MARG_CAPTURE_PAYLOADS`   | `AGENTOPS_CAPTURE_PAYLOADS`   | `false`             |

### Buffering and resilience knobs

`MargConfig` also exposes bounded buffering and retry settings:
`flush_interval_seconds` (default 2.0), `max_batch_size` (100), `max_queue_size`
(1000), `timeout_seconds` (5.0), `max_retries` (2), `retry_backoff_seconds`
(0.5). When the queue is full, the oldest-pending work is dropped and the count
is available via `marg.dropped_events_count`.

## Privacy

Payload capture is **off by default**. Only lightweight event metadata is
exported; `set_output_summary()` content is passed through the redaction layer,
which strips sensitive values (keys, tokens, connection strings). Set
`MARG_CAPTURE_PAYLOADS=true` only if your backend and compliance posture allow
it.

## Parser-not-required note for agent adapters

A generic `@observe_agent` decorator is available:

```python
from marg_sdk import Marg
from marg_sdk.adapters.decorator import observe_agent

marg = Marg.from_env()

@observe_agent(marg, agent_id="my-agent")
def run_my_task(task: str) -> str:
    ...
```

## License

Apache-2.0 &mdash; see [LICENSE](LICENSE).
