Metadata-Version: 2.4
Name: lightup-agentic
Version: 1.0.0
Summary: AI assistant for Lightup data quality — MCP server + agentic chat client
Author-email: siva <siva@lightup.ai>
Requires-Python: ~=3.11.11
Requires-Dist: anthropic<1.0.0,>=0.48.0
Requires-Dist: google-genai>=1.66.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: openai>=1.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-docx>=1.2.0
Description-Content-Type: text/markdown

# lightup-agentic

AI assistant for [Lightup](https://lightup.ai) data quality — ask questions about your metrics, monitors, datasources, and incidents in plain English.

Connects your Lightup instance to an AI assistant (Claude, OpenAI, or Gemini) via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). Also works as an MCP server for Claude Desktop and Claude Code.

---

## Requirements

- Python 3.11+
- A Lightup account with a `lightup-api-credential.json` file
- An API key for Claude, OpenAI, or Gemini

---

## Installation

```bash
pip install lightup-agentic
```

---

## Quick start

```bash
lightup-agentic start
```

This runs a guided setup wizard that:
1. Connects to your Lightup instance
2. Configures your AI provider (Claude / OpenAI / Gemini)
3. Starts the MCP server
4. Opens an interactive chat session

On the first run you will be prompted for:
- Your `lightup-api-credential.json` file path (download from the Lightup UI under your profile)
- Your AI provider and API key

Config is saved to `~/.lightup-agentic/config.json` and reused on subsequent runs.

### How `lightup-agentic start` behaves

| Situation | Behaviour |
|---|---|
| First run (no config) | Runs full setup wizard — prompts for credential file and AI provider key |
| Config exists and valid | Skips setup, starts MCP server and chat immediately |
| `-s` / `--setup` flag | Always runs full setup wizard, even if config exists |

```bash
lightup-agentic start       # first run → setup wizard; subsequent runs → skip to chat
lightup-agentic start -s    # force re-run setup wizard (--setup)
lightup-agentic start -v    # verbose logs (--verbose)
lightup-agentic start -d    # debug mode (--debug)
lightup-agentic start -s -v # force setup + verbose logs
```

### Verbose mode

```bash
lightup-agentic start -v          # verbose logs (--verbose)
lightup-agentic start -s -v       # force setup + verbose logs
```

Shows API calls, tool invocations, and server logs as they happen.

### Debug mode

```bash
lightup-agentic start -d          # debug mode (--debug)
```

Disables the documentation content cap — the full content of every doc file is sent to the AI with no truncation. Useful when diagnosing why the AI is giving incomplete answers. Note: increases token usage and may trigger API rate limits on lower-tier plans.

---

## Using with Claude Desktop

After running `lightup-agentic start`, the setup wizard auto-configures Claude Desktop. Restart Claude Desktop to apply.

To configure manually, add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "lightup-agentic": {
      "command": "lightup-agentic",
      "args": ["serve", "--stdio"]
    }
  }
}
```

---

## Using with Claude Code

After setup, Claude Code is auto-configured. To add manually:

```bash
claude mcp add --transport sse lightup-agentic http://localhost:8765/sse
```

---

## What you can ask

- "List my workspaces"
- "Create a workspace called Acme with description 'Production monitoring'"
- "Show all metrics in workspace Acme"
- "What monitors are failing in workspace Acme?"
- "List recent incidents in workspace Acme"
- "Get details for incident `<uuid>`"
- "Show all integrations in workspace Acme"
- "Create a postgres datasource in workspace Acme"
- "Show system errors in workspace Acme from the last 48 hours"
- "List all users"
- "Who has admin access?"
- "What is a slice in Lightup?"
- "How does monitoring work?"
- "Create a manual threshold monitor on metric X in workspace Acme with bounds 0 to 500"
- "Create an anomaly detection monitor on metric Y in workspace Acme"
- "Create a monitor on metric X and alert via Slack"
- "Why is monitor `<uuid>` not working?"
- "Diagnose monitor `<uuid>` in workspace Acme"
- "How does monitor training work?"
- "Why is my monitor getting too many false positives?"

---

## Available tools

| Tool | Description |
|---|---|
| `list_workspaces` | List all workspaces |
| `get_workspace` | Get workspace details |
| `create_workspace` | Create a new workspace |
| `list_metrics` | List metrics in a workspace |
| `get_metric` | Get metric details |
| `search_metric` | Search for a metric by name across all workspaces |
| `list_datasources` | List datasources in a workspace |
| `get_datasource` | Get datasource details |
| `test_datasource_connection` | Test a datasource connection before creating |
| `create_datasource` | Create a new datasource (postgres, snowflake, mysql, bigquery, etc.) |
| `list_monitors` | List monitors in a workspace |
| `get_monitor` | Get monitor details |
| `create_monitor` | Create a manual threshold or anomaly detection monitor on a metric |
| `diagnose_monitor` | Explain why a monitor is not working in plain English (training failed, paused, not alerting, etc.) |
| `list_incidents` | List recent incidents in a workspace |
| `get_incident` | Get incident details |
| `list_integrations` | List integrations (email, Slack, ServiceNow, OpsGenie) in a workspace |
| `list_events` | List system events (errors, warnings) for the last N hours (max 1 week) |
| `list_recommendations` | List AI-generated metric/monitor recommendations in a workspace |
| `list_users` | List all users in the Lightup instance with their roles and workspace memberships |
| `list_llm_connections` | List all LLM connections (OpenAI, Azure OpenAI, Google AI Studio, etc.) configured in the instance |
| `list_catalog_integrations` | List all catalog integrations (Atlan, Alation) with connection status and any errors |
| `get_documentation` | Fetch Lightup product documentation by topic |
| `list_documentation_topics` | List all available documentation topics |
