Metadata-Version: 2.4
Name: saksh
Version: 1.0.1
Summary: Sahasraksh - The All-Seeing Observer for AI Agents
Author-email: Ram Bikkina <itsrambikkina@gmail.com>
Keywords: observability,ai-agents,crewai,langgraph
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: fastapi
Requires-Dist: uvicorn
Requires-Dist: requests
Requires-Dist: pydantic
Requires-Dist: crewai
Requires-Dist: build>=1.3.0
Requires-Dist: twine>=6.0.1

<p align="center">
  <img
    src="https://i.ibb.co/p6Y7MVTq/saksh-logo.png"
    alt="saksh-logo"
    width="256"
    height="256"
  />
</p>

# Saksh (Sahasraksh) v1.0.0

> **"The All-Seeing Observer for your AI Agents."**

**Saksh** (derived from *Sahasraksh* — "The One with a Thousand Eyes") is a lightweight, non-intrusive observability layer designed specifically for modern AI Agent ecosystems.

Think of it as a **Sidecar** for your agents. whether you're running a swarm of **CrewAI** workers, a complex **LangGraph** state machine, or raw LLM chains, Saksh sits quietly in the background, monitoring health, latency, and vitality without ever blocking your main event loop.

![Saksh Dashboard](https://i.ibb.co/HpMyq78x/Screenshot-2026-02-15-at-11-14-27-AM.png)


## ⚡ Why Saksh?

Building agents is hard. Debugging why they "hung" or "timed out" is harder.
Saksh gives you a **Mission Control** dashboard out of the box, so you can stop guessing if your agents are actually working or just hallucinating silence.

* **Universal & Agnostic:** We don't care if you use CrewAI, LangGraph, or raw OpenAI calls. If it has an API key and a URL, we can watch it.
* **Zero-Touch Dashboard:** Just instantiate the class, and a full React/FastAPI dashboard spins up on port `2604`. No React code required.
* **Vitality Scoring:** We don't just check "Is it up?". We calculate a **Vitality Score (0-100)** based on latency spikes and auth failures.
* **Non-Blocking Sidecar:** Runs in a daemon thread. Your agents keep working even if Saksh takes a coffee break.

## 📦 Installation

Get it via pip:

```bash
pip install saksh

```

## 🛠️ Quick Start

You can attach Saksh to your existing stack in about 3 lines of code.

### 1. The Setup

```python
from saksh import Saksh, CrewAINetra, LangGraphNetra
from crewai import Agent

# 1. Summon the Observer 👁️
# This auto-magically starts the dashboard at http://localhost:2604
observer = Saksh(start_dashboard=True)

```

### 2. Connect CrewAI

Saksh automatically detects the LLM configuration (URL, API Key) inside your CrewAI agents.

```python
# Your standard CrewAI setup
researcher = Agent(
    role="Researcher", 
    goal="Analyze market trends", 
    backstory="You are a data wizard."
)

# Open an Eye on it
observer.open_eye(CrewAINetra(researcher, "Market-Researcher-01"))

```

### 3. Connect LangGraph

Since LangGraph is stateful and abstract, we monitor the underlying LLM provider it relies on.

```python
# graph_app = workflow.compile()

# Register the graph (defaults to checking OpenAI availability)
observer.open_eye(LangGraphNetra(graph_app, "Math-Graph-State-Machine"))

```

*That's it. Your terminal will now log:*
`👁️ Saksh is watching...`

## 🧩 Architecture

Saksh uses a **Netra (Eye) Adapter Pattern**.

* **Saksh (Core):** The singleton observer that manages the background thread and dashboard.
* **Netra (Adapter):** A standardized interface that knows how to "Gaze" at a specific type of agent and normalize its health data into a `HealthPulse`.

## 🤝 Contributing

This is **v1.0.0** — the "It Works on My Machine" release.
We are actively looking for contributors to build **Netras** (Adapters) for:

* Autogen
* Semantic Kernel
* Local Ollama/Llama.cpp instances

PRs are welcome! Let's build the standard for Agent Observability together.

## 📜 License

MIT © 2026 Ram Bikkina
