Metadata-Version: 2.5
Name: nika
Version: 0.2.0
Summary: Autonomous AI SRE agent — investigates alerts, performs RCA, learns from feedback
Project-URL: Homepage, https://github.com/kalyanace44/nika
Project-URL: Repository, https://github.com/kalyanace44/nika
Project-URL: Documentation, https://github.com/kalyanace44/nika/docs
Author-email: Vegapay Platform <platform@vegapay.io>
License: Apache-2.0
License-File: LICENSE
Keywords: ai,holmesgpt,incident-response,observability,rca,sre
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Requires-Dist: asyncpg>=0.29.0
Requires-Dist: boto3>=1.34.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: pydantic-settings>=2.2.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: slack-bolt>=1.18.0
Requires-Dist: structlog>=24.1.0
Requires-Dist: tenacity>=8.2.0
Provides-Extra: all
Requires-Dist: datadog-api-client>=2.22.0; extra == 'all'
Requires-Dist: mypy>=1.9.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'all'
Requires-Dist: pytest-cov>=5.0.0; extra == 'all'
Requires-Dist: pytest>=8.0.0; extra == 'all'
Requires-Dist: respx>=0.21.0; extra == 'all'
Requires-Dist: ruff>=0.4.0; extra == 'all'
Provides-Extra: datadog
Requires-Dist: datadog-api-client>=2.22.0; extra == 'datadog'
Provides-Extra: dev
Requires-Dist: mypy>=1.9.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# AI-SRE-Agent (Nika)

> *Ni* (नि) — to investigate. *Ka* (क) — the one who does.
> **"The one who investigates."**

Autonomous AI SRE agent that monitors multi-account AWS infrastructure, performs real-time Root Cause Analysis when alerts fire, and posts findings directly to your incident channels. Learns from every investigation and engineer feedback.

Built for **Vegapay** — powering credit card and payment processing across 7 banking clients, 4 AWS accounts.

---

## Architecture

```
┌────────────────────────────────────────────────────────────────────────┐
│                    ALERT SOURCES (4 AWS Accounts)                        │
│  CloudWatch │ Prometheus │ PagerDuty │ Opsgenie │ Datadog               │
└──────────────────────────────┬──────────────────────────────────────────┘
                               │ SNS → cross-account SQS
                               ▼
┌──────────────────────────────────────────────────────────────────────────┐
│              Vegapay-AI Account (g5.xlarge EC2 Spot)                       │
│                                                                           │
│  ┌──────────┐  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐   │
│  │  vLLM    │  │  HolmesGPT   │  │ Memory       │  │  PostgreSQL   │   │
│  │  Server  │  │  + Slack Bot  │  │ Worker       │  │  + pgvector   │   │
│  │ Qwen3.6  │  │  + Plugins   │  │              │  │               │   │
│  │ 27B-AWQ  │  │              │  │              │  │               │   │
│  └──────────┘  └──────────────┘  └──────────────┘  └───────────────┘   │
│  ┌────────────────────┐  ┌────────────────────────────────────────────┐ │
│  │ Embedder (CPU)     │  │ RCA Dashboard (FastAPI)                     │ │
│  │ bge-base-en-v1.5   │  │ Browse/search/filter past investigations   │ │
│  └────────────────────┘  └────────────────────────────────────────────┘ │
└────────────────────────────────┬────────────────────────────────────────┘
                                 │ sts:AssumeRole (OIDC)
              ┌──────────────────┼──────────────────┐
              ▼                  ▼                  ▼
    ┌─────────────────┐ ┌──────────────┐ ┌──────────────────┐
    │ Vegapay Prod     │ │ SSFB         │ │ Yes Bank / BOB   │
    │ (4 clients:      │ │ (dedicated)  │ │ (dedicated)      │
    │ Capri/Ebix/      │ └──────────────┘ └──────────────────┘
    │ Scapia/Pahal)    │
    └─────────────────┘
```

---

## Install

```bash
pip install nika
```

With Datadog support:
```bash
pip install nika[datadog]
```

---

## Configuration

All config via environment variables (12-factor). Prefix: `NIKA_`.

### Core

| Variable | Description | Default |
|----------|-------------|---------|
| `NIKA_DB_URL` | PostgreSQL connection (local or RDS/Cloud SQL) | `postgresql://postgres:postgres@localhost:5432/ai_sre_memory` |
| `NIKA_DB_SSL_MODE` | SSL mode (`disable`, `prefer`, `require`) | `prefer` |
| `NIKA_DB_POOL_MAX` | Max DB connection pool size | `10` |
| `NIKA_REDIS_URL` | Redis URL (local or ElastiCache/Memorystore) | `redis://localhost:6379/0` |
| `NIKA_REDIS_SSL` | Enable TLS for managed Redis | `false` |
| `NIKA_VLLM_BASE_URL` | vLLM server URL | `http://localhost:8000/v1` |
| `NIKA_VLLM_MODEL` | Model name | `Qwen/Qwen3.6-27B-AWQ` |
| `NIKA_EMBEDDER_URL` | Embedding service URL | `http://localhost:8081` |

> **Infrastructure-agnostic:** Every dependency is a connection string. Use self-hosted containers, managed services (RDS, ElastiCache, Cloud SQL), or any mix. See [docs/deployment.md](docs/deployment.md) for configuration examples.

### Slack (Primary)

| Variable | Description |
|----------|-------------|
| `NIKA_SLACK_BOT_TOKEN` | Bot token (`xoxb-...`) |
| `NIKA_SLACK_APP_TOKEN` | App token (`xapp-...`) for Socket Mode |
| `NIKA_SLACK_DEFAULT_CHANNEL` | Default channel for RCAs |

### Microsoft Teams

| Variable | Description |
|----------|-------------|
| `NIKA_TEAMS_WEBHOOK_URL` | Incoming Webhook URL |
| `NIKA_TEAMS_ENABLED` | Enable Teams notifications (`true`/`false`) |

### PagerDuty

| Variable | Description |
|----------|-------------|
| `NIKA_PAGERDUTY_ROUTING_KEY` | Events API v2 routing key |
| `NIKA_PAGERDUTY_API_KEY` | REST API key (for notes/updates) |
| `NIKA_PAGERDUTY_ENABLED` | Enable PagerDuty (`true`/`false`) |

### Opsgenie

| Variable | Description |
|----------|-------------|
| `NIKA_OPSGENIE_API_KEY` | Opsgenie API key |
| `NIKA_OPSGENIE_TEAM` | Default responder team |
| `NIKA_OPSGENIE_ENABLED` | Enable Opsgenie (`true`/`false`) |

### Datadog Collector

| Variable | Description |
|----------|-------------|
| `NIKA_DATADOG_API_KEY` | Datadog API key |
| `NIKA_DATADOG_APP_KEY` | Datadog Application key |
| `NIKA_DATADOG_SITE` | Datadog site (default: `datadoghq.com`) |
| `NIKA_DATADOG_ENABLED` | Enable Datadog polling (`true`/`false`) |

### Bedrock Fallback (P1 only)

| Variable | Description | Default |
|----------|-------------|---------|
| `NIKA_BEDROCK_MODEL` | Claude model ID | `anthropic.claude-sonnet-4-20250514-v1:0` |
| `NIKA_BEDROCK_REGION` | AWS region for Bedrock | `us-east-1` |
| `NIKA_BEDROCK_TRIGGER_SEVERITY` | Min severity to trigger Bedrock | `P1` |

### Accounts (YAML)

```yaml
# config/accounts.yaml
accounts:
  - id: "111111111111"
    name: "vegapay-prod"
    type: "shared-cluster"
    role_arn: "arn:aws:iam::111111111111:role/ai-sre-readonly-role"
    region: "ap-south-1"
    clients:
      - name: "capri"
        label_selector: "vegapay.io/client=capri"
        service_prefix: "capri-"
        slack_channel: "#oncall-support"
        l1_team: "@payments-capri"
        l2_poc: "@capri-client-devops"
      # ... more clients

  - id: "222222222222"
    name: "ssfb-prod"
    type: "dedicated"
    role_arn: "arn:aws:iam::222222222222:role/ai-sre-readonly-role"
    region: "ap-south-1"
    slack_channel: "#oncall-support"
    l1_team: "@payments-ssfb"
    l2_poc: "@ssfb-client-devops"
```

---

## Plugin System

### Notification Targets

All targets implement `NotificationTarget` — post RCA reports and follow-up messages.

| Plugin | Transport | Features |
|--------|-----------|----------|
| **Slack** (built-in) | Bolt WebSocket | Thread replies, reactions, feedback loop |
| **Teams** | Incoming Webhook | Adaptive Cards, severity coloring |
| **PagerDuty** | Events API v2 | Trigger/ack/resolve, severity mapping |
| **Opsgenie** | Alerts API v2 | Create/note/close, team routing |

### Alert Collectors

All collectors implement `AlertCollector` — poll for alerts and fetch metrics.

| Plugin | Source | Capabilities |
|--------|--------|--------------|
| **CloudWatch** (built-in) | SNS → SQS | Cross-account, alarm metadata |
| **Prometheus** (built-in) | AlertManager webhook | Label-based routing |
| **Datadog** | API v1/v2 | Monitor polling, metric query, event correlation |

### Writing a Plugin

```python
from nika.plugins import NotificationTarget
from nika.core.models import RCAReport

class MyTarget(NotificationTarget):
    name = "my-target"

    async def send_rca(self, report: RCAReport) -> str | None:
        # Post the RCA, return thread/incident ID
        ...

    async def send_followup(self, thread_id: str, message: str) -> None:
        # Post follow-up to existing thread
        ...

    async def healthcheck(self) -> bool:
        # Return True if connection is working
        ...
```

---

## Project Structure

```
AI-SRE-Agent/
├── src/nika/
│   ├── __init__.py
│   ├── core/
│   │   ├── config.py              # Pydantic settings, account loading
│   │   └── models.py              # Alert, Investigation, RCAReport
│   ├── plugins/
│   │   ├── __init__.py            # Base classes: NotificationTarget, AlertCollector
│   │   ├── targets/
│   │   │   ├── teams.py           # Microsoft Teams (Adaptive Cards)
│   │   │   ├── pagerduty.py       # PagerDuty Events API v2
│   │   │   └── opsgenie.py        # Opsgenie Alerts API v2
│   │   └── collectors/
│   │       └── datadog.py         # Datadog monitor polling + metrics
│   ├── investigation/             # HolmesGPT integration, query planner
│   └── memory/                    # Episodic, semantic, procedural memory
├── services/
│   ├── memory-worker/
│   │   ├── main.py                # Background: extraction, decay, archive
│   │   └── Dockerfile
│   └── rca-dashboard/
│       ├── app.py                 # FastAPI: browse/search investigations
│       └── Dockerfile
├── tests/
│   ├── unit/
│   │   ├── test_models.py
│   │   ├── test_targets.py
│   │   └── test_datadog.py
│   └── integration/
├── .github/workflows/
│   ├── ci.yml                     # Lint + test + docker build on push/PR
│   └── release.yml                # PyPI + GHCR publish on tag
├── config/
│   └── accounts.yaml              # Multi-account configuration
├── pyproject.toml
├── DESIGN.md                      # Full system design document
└── README.md
```

---

## CI/CD

### Continuous Integration (`.github/workflows/ci.yml`)

Triggers on push to `main` and PRs:

1. **Lint** — `ruff check src/ tests/`
2. **Type check** — `mypy src/nika/`
3. **Test** — `pytest tests/ -v --cov=nika` (Python 3.11 + 3.12 matrix)
4. **Docker build** — validates both Dockerfiles build cleanly

### Release (`.github/workflows/release.yml`)

Triggers on tag push (`v*`):

1. **Test** — full test suite gate
2. **PyPI** — trusted publishing (OIDC, no API key)
3. **GHCR** — builds and pushes container images:
   - `ghcr.io/<owner>/nika-memory-worker:<version>`
   - `ghcr.io/<owner>/nika-rca-dashboard:<version>`

### Releasing

```bash
# Bump version in pyproject.toml, then:
git tag v0.1.0
git push --tags
# CI handles PyPI + GHCR automatically
```

---

## Development

```bash
# Clone and install
git clone https://github.com/vegapay/ai-sre-agent.git
cd ai-sre-agent

# Using uv (recommended)
uv run --extra dev pytest tests/ -v

# Or manually
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v -m "not integration"
```

### Running Lint + Type Checks

```bash
uv run --extra dev ruff check src/ tests/
uv run --extra dev mypy src/nika/ --ignore-missing-imports
```

---

## Security Model

- **Read-only access** — explicit IAM Deny on all write actions across all spoke accounts
- **Credential isolation** — each account investigation gets its own temporary STS credentials (1hr TTL)
- **No credential sharing** — multi-account aggregation only sees text findings, never holds multiple credential sets
- **Zero-trust** — no Confluence/wiki access, no SSH to prod instances, no kubectl exec
- **Compliance archive** — every investigation archived to S3 (KMS-encrypted, 2-year retention)

---

## Cost

| Component | Monthly | Notes |
|-----------|---------|-------|
| EC2 g5.xlarge (Spot) | ~$230 | A10G 24GB GPU |
| EBS (100GB gp3) | ~$30 | Model weights + DB |
| S3 archive | ~$2 | 10K RCAs/month |
| Bedrock Claude (P1 only) | ~$20 | ~5-10 P1 incidents/month |
| **Total** | **~$290/month** | |

---

## License

Apache-2.0
