Metadata-Version: 2.4
Name: agentminds
Version: 0.4.0
Summary: AgentMinds Python SDK — auto-captures errors, web requests, and logs from Python web apps.
Project-URL: Homepage, https://agentminds.dev
Project-URL: Documentation, https://agentminds.dev/docs/python
Project-URL: Repository, https://github.com/UzunGridera/agentminds
Project-URL: Issues, https://github.com/UzunGridera/agentminds/issues
Author: AgentMinds
License: MIT
License-File: LICENSE
Keywords: django,errors,fastapi,flask,logging,monitoring,observability
Classifier: Development Status :: 4 - Beta
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.8
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 :: Software Development :: Bug Tracking
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Provides-Extra: dev
Requires-Dist: fastapi; extra == 'dev'
Requires-Dist: flask; extra == 'dev'
Requires-Dist: httpx; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.95; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: flask>=2.0; extra == 'flask'
Description-Content-Type: text/markdown

# agentminds — Python SDK

Auto-capture errors, failed requests, and logs from your Python web app.
Sentry-style API, Sentry-style ergonomics — one `init()` call and the SDK
hooks `sys.excepthook`, your web framework's error pipeline, and the
logging module. Connect once and your site joins the AgentMinds
intelligence pool — patterns the network has already learned for your
stack come back as recommendations.

## Install — one command

```bash
pip install agentminds && agentminds connect
```

`agentminds connect` is the recommended onboarding. It prompts for your
site URL + email, registers your site with the API, gets your DSN, and
auto-edits your FastAPI/Flask entry file in place (a `.agentminds.bak`
backup is written first). After that, set the printed `AGENTMINDS_DSN`
env var in your runtime and deploy.

```bash
# non-interactive — pass everything as flags
agentminds connect --url=https://yourapp.com --email=you@example.com
```

## Quickstart (manual, if you already have a DSN)

```python
import agentminds

agentminds.init(
    dsn="https://pk_yoursite_xxx@api.agentminds.dev/yoursite",
    release="v1.2.3",        # optional — auto-detected from git
    environment="production",
)
```

That's it. From this point:

- Every uncaught exception (main thread + worker threads) is captured.
- Every `logging.error(...)` call ships as an event.
- Every `logging.info/warning(...)` becomes a breadcrumb on the next event.

The SDK is a no-op if no DSN is set — safe to leave `init()` in dev.

## FastAPI

```python
from fastapi import FastAPI
import agentminds
from agentminds.integrations.fastapi_app import AgentMindsMiddleware

agentminds.init(dsn="...")
app = FastAPI()
app.add_middleware(AgentMindsMiddleware)
```

Captures uncaught handler exceptions plus any 5xx response. Adds
`http.method` / `http.route` tags and a request breadcrumb.

## Flask

```python
from flask import Flask
import agentminds
from agentminds.integrations.flask_app import init_app

agentminds.init(dsn="...")
app = Flask(__name__)
init_app(app)
```

## Manual capture

```python
try:
    risky_thing()
except Exception as e:
    agentminds.capture_exception(e)

agentminds.capture_message("payment retry exceeded", level="warning")
agentminds.set_user({"id": user.id, "email": user.email})
agentminds.set_tag("plan", user.plan)
agentminds.add_breadcrumb(category="db", message="SELECT users WHERE...")
```

## Configuration

| Argument | Env var | Default | Notes |
|---|---|---|---|
| `dsn` | `AGENTMINDS_DSN` | — | Required. SDK no-op if absent. |
| `release` | `AGENTMINDS_RELEASE` | `git rev-parse --short HEAD` | Tag events with build. |
| `environment` | `AGENTMINDS_ENV` | `"production"` | Filter on the dashboard. |
| `sample_rate` | — | `1.0` | `0.1` = drop 90% of events. |
| `debug` | `AGENTMINDS_DEBUG=1` | `False` | Logs SDK internals to `agentminds` logger. |
| `attach_logging` | — | `True` | Auto-attach logging handler. |
| `install_excepthook` | — | `True` | Auto-hook `sys.excepthook`. |

## Wire format

The SDK posts batched events to:

```
POST {api_base}/api/v1/sync/ingest/{site_id}/events?key={public_key}
Content-Type: application/json
{ "events": [ { type, fingerprint, payload, page_url? }, ... ] }
```

Same envelope as the browser collector (`agent.js`) — server-side and
browser events land in the same `runtime_events` table.

## Privacy

- No request bodies sent unless you opt in (`send_default_pii=True`).
- No DB query parameters captured.
- User PII (email, IP) only sent if you set it via `set_user(...)`.
- Stack traces are truncated to 8 KB; messages to 500 chars.

## License

MIT
