Metadata-Version: 2.4
Name: visibleagent
Version: 0.1.0
Summary: Plain-English observability for AI agents — live dashboards, replay, and one-line LangGraph auto-instrumentation, metadata-safe by default.
Author-email: Harshet Jain <hjain8620.hj@gmail.com>
License-Expression: Apache-2.0
Keywords: ai-agents,observability,tracing,langgraph,langchain,transparency
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Provides-Extra: langgraph
Requires-Dist: langchain-core<2,>=1.0; extra == "langgraph"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: langchain-core<2,>=1.0; extra == "dev"
Requires-Dist: langgraph<2,>=1.0; extra == "dev"
Dynamic: license-file

# VisibleAgent Python SDK

Plain-English observability for AI agents. VisibleAgent turns your agent's
work into a story a human can read — every run, every step, every tool call,
live-streamed to a dashboard with full replay — while capturing **metadata
only** by default: never prompts, never customer content, unless you
explicitly opt in.

## Install

```bash
pip install visibleagent            # core SDK
pip install "visibleagent[langgraph]"  # + LangGraph auto-instrumentation
```

## LangGraph: one line, zero node changes

```python
from visibleagent import VisibleAgent
from visibleagent.integrations.langgraph import VisibleAgentTracer

va = VisibleAgent(api_key="...", base_url="https://your-visibleagent-host")

tracer = VisibleAgentTracer(
    client=va,
    source="MyApp",                       # "which app did this?" label
    display_names={                       # optional: human names per node
        "classify": "Classifying the message",
        "respond": "Drafting a reply",
    },
    descriptions={                        # optional: what each step does
        "classify": "Reads the message and works out what it's about",
    },
    narrate=my_narrator,                  # optional: plain-English outcomes
)

graph.invoke(state, config={"callbacks": [tracer]})
```

The tracer auto-derives the whole span tree from LangGraph's callbacks —
nodes, model calls ("Thinking — …"), and tool calls — including model names,
token usage, and latencies. It works with bare `llm.invoke()` calls inside
your nodes (no config threading needed), never raises into your app, and is
completely inert when unconfigured.

`narrate(node_name, output_state)` lets you turn structured state into
human sentences — `"Understood the message as a new order (94% confident)"`
— without ever exposing raw content.

## Manual instrumentation

```python
with va.start_run(name="Refund request #4521", attrs={"source": "MyApp"}) as run:
    with run.agent("support_agent", display="Support Agent") as agent:
        with agent.step("classify", display="Understanding the request"):
            ...
        with agent.tool("orders.lookup", display="Checking the order") as tool:
            order = lookup(order_id)
            tool.note(f"Found order {order_id}")
va.flush()
```

Spans emit `.started` / `.completed` / `.failed` automatically based on
whether the block raises. Delivery is batched on a background thread and
fail-open: a missing or unreachable VisibleAgent backend never affects
your application.

## Content safety

Metadata capture is the default and the contract: span attributes carry
model ids, token counts, durations, statuses, and the labels you author —
never prompt or completion text, never tool argument values. A separate
explicit `capture_content="full"` mode exists for teams who want their own
content in their own dashboard.

## License

Apache-2.0
