Metadata-Version: 2.4
Name: stillrunning-sdk
Version: 0.1.0
Summary: One-line monitoring for any Python job, agent, or script. Decorate or wrap your code and StillRunning gets a ping on success/failure with duration, cost, tokens, and model.
Project-URL: Homepage, https://stillrunning.ai/docs/sdks/python
Project-URL: Documentation, https://stillrunning.ai/docs/sdks/python
Project-URL: Repository, https://github.com/maximum-sl/stillrunning
Author: StillRunning
License: MIT
License-File: LICENSE
Keywords: agent,ai,cost,crewai,cron,heartbeat,langchain,llm,monitoring,observability,stillrunning
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# stillrunning-sdk

Monitoring for any Python job, agent, or script, in one line.

Decorate or wrap your code and [StillRunning](https://stillrunning.ai) gets a ping on success or
failure with the run's **duration**, plus optional **cost, tokens, and model**. Get alerted the
moment a cron job stops, an agent fails, or a script runs too long or costs too much, with no ping
plumbing. Works with LangChain, CrewAI, agent scripts, Celery/RQ workers, and plain cron jobs.

```bash
pip install stillrunning-sdk
```

## 30-second quickstart

1. Create a workflow at [stillrunning.ai/app/new](https://stillrunning.ai/app/new) and copy its token.
2. `export STILLRUNNING_TOKEN=your_token_here`
3. Monitor your work:

   ```python
   from stillrunning_sdk import StillRunning

   sr = StillRunning()  # reads STILLRUNNING_TOKEN

   @sr.monitor
   def nightly_job():
       ...
   ```

Every call to `nightly_job` is now timed and reported, success on return, failure on exception
(re-raised untouched).

## Three ways to use it

**Decorator** , monitor a function:

```python
@sr.monitor
def sync_customers():
    ...
```

**Context manager** , attach AI metrics inside the block:

```python
with sr.track() as run:
    result = call_agent(prompt)
    run.meta(tokens_in=result.usage.input, tokens_out=result.usage.output, model="gpt-4o")
    # model + tokens -> costUsd estimated automatically
```

**Run a callable** , inline:

```python
answer = sr.run(lambda: call_agent(prompt), meta={"model": "claude-sonnet-4", "tokens_in": 1200})
```

## Heartbeats and manual pings

For a cron job that just needs to say "I ran", or when you can't wrap the work:

```python
sr.heartbeat()                          # bare success ping
sr.ping(event="start", traceId="...")   # low-level: success | fail | start | log
```

## Cost estimation

Give `model` plus token counts and cost is estimated from a built-in pricing table (Claude / GPT /
Gemini). It's approximate, it powers relative cost-anomaly detection and a ballpark spend figure.
Pass an explicit `cost_usd` for exact accounting, or extend the table:

```python
from stillrunning_sdk import register_model_pricing
register_model_pricing([(r"my-custom-model", (1.5, 6.0))])  # USD per 1M (input, output) tokens
```

Unknown models simply send no cost rather than a wrong one.

## Grouping multi-step runs with `with_trace`

```python
from stillrunning_sdk import StillRunning, with_trace
sr = StillRunning()

with with_trace():
    sr.run(plan_step)
    sr.run(execute_step)   # both pings share one trace_id
```

## Configuration

```python
StillRunning(
    token=None,        # defaults to env STILLRUNNING_TOKEN
    base_url="https://stillrunning.ai",
    timeout=3.0,       # seconds; bounds each ping so a slow StillRunning never hangs your job
    await_ping=True,   # False = fire-and-forget in a daemon thread (lowest latency)
    on_error=None,     # callable(Exception) -> observe ping delivery failures
    transport=None,    # custom transport (testing / non-urllib runtimes)
)
```

Monitoring never raises into your code: a failed ping routes to `on_error` and is otherwise
swallowed.

## Requirements

Python 3.9+. No runtime dependencies (uses the standard library).

## License

MIT
