Metadata-Version: 2.4
Name: nightgaze
Version: 0.2.0
Summary: Observability for AI agents — trace agents, tools, MCP and LLM calls with token usage, cost and latency
Author: Kunal Bhagat, Deepanshu
License-Expression: Apache-2.0
Keywords: observability,tracing,llm,agents,openai,anthropic,gemini,langchain,langgraph,llamaindex,mcp,monitoring
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: httpx>=0.27
Requires-Dist: zstandard>=0.22
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30; extra == "anthropic"
Provides-Extra: gemini
Requires-Dist: google-genai>=1.0; extra == "gemini"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2; extra == "langchain"
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.2; extra == "langgraph"
Requires-Dist: langchain-core>=0.2; extra == "langgraph"
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.11; extra == "llamaindex"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# NightGaze

**Observability for AI agents.** Trace your agents, tools, MCP and LLM calls with
two lines of code — and see every step, token, and millisecond of your agent
workflows.

## Installation

```bash
pip install nightgaze
```

## Quick start

```python
import nightgaze

nightgaze.init(
    api_key="ng_live_...",               # from your NightGaze project settings
    base_url="https://your-nightgaze-host.com",
)

@nightgaze.agent("planner")
def plan_trip(query: str) -> str:
    hotels = search_hotels(query)
    return summarize(hotels)

@nightgaze.tool("search_hotels")
def search_hotels(query: str) -> list:
    ...
```

That's it. The outermost call becomes a **trace**; everything inside it — nested
functions, LLM calls, tool calls — becomes a child **span** with timing, token
usage, and error capture. Works with sync, async, and generator functions.

## Trace your LLM calls automatically

```python
nightgaze.instrument_openai()      # Chat Completions + Responses API
nightgaze.instrument_anthropic()   # Messages API
nightgaze.instrument_gemini()      # Google Gemini (google-genai)
```

Every request is captured with model, token usage, latency, and
time-to-first-token for streaming — no changes to your calling code.

## Framework integrations

```python
nightgaze.instrument_langchain()    # chains, LLMs, tools, retrievers
nightgaze.instrument_langgraph()    # graphs with named node spans
nightgaze.instrument_llamaindex()   # queries, retrieval, synthesis
```

## Decorators and manual spans

```python
@nightgaze.agent("researcher")      # agent step
@nightgaze.tool("web_search")       # tool call
@nightgaze.trace("checkout")        # explicit workflow root
@nightgaze.mcp("fetch_docs")        # MCP tool call
@nightgaze.span                     # generic span

# or as a context manager, with custom attributes:
with nightgaze.span_context("rerank", kind="tool") as span:
    results = rerank(docs)
    span.add_metadata(doc_count=len(results))
```

## Attribute traces to your users

```python
nightgaze.identify(user_id="u_123", session_id="sess_9", customer_id="acme")
```

Every event emitted afterwards carries these identifiers, so you can filter
traces by user, follow a session end-to-end, and break down cost per customer.

## Streaming support

Streamed LLM responses are traced correctly: the span stays open until the
stream is consumed (full generation latency) and records
`time_to_first_token_ms`.

## Safe by design

- **Never breaks your app** — after `init()`, telemetry is best-effort; any
  failure means a dropped event, never an exception in your code.
- **Off the hot path** — events batch in the background with compression,
  retries, and a circuit breaker. Fork-safe under gunicorn/celery.

## Optional extras

```bash
pip install "nightgaze[openai]"       # openai
pip install "nightgaze[anthropic]"    # anthropic
pip install "nightgaze[gemini]"       # google-genai
pip install "nightgaze[langchain]"    # langchain-core
pip install "nightgaze[langgraph]"    # langgraph
pip install "nightgaze[llamaindex]"   # llama-index-core
```

## Requirements

Python 3.9+

## License

Apache-2.0
