Metadata-Version: 2.5
Name: openai-radar
Version: 2.1.0
Summary: OpenAI infrastructure FinOps SDK — scan, analyze, and export your OpenAI org resources
Project-URL: Homepage, https://github.com/gomorsmi/openai-radar
Project-URL: Repository, https://github.com/gomorsmi/openai-radar
Project-URL: Bug Tracker, https://github.com/gomorsmi/openai-radar/issues
Project-URL: PyPI, https://pypi.org/project/openai-radar/
Author: Sarimor Michaeli
License: MIT
Keywords: cloud-cost,finops,hyperscaler,llm,openai,radar
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: anyio>=4.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: lxml>=5.0.0
Requires-Dist: openai>=1.60.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: agents
Requires-Dist: openai-agents>=0.22.0; extra == 'agents'
Provides-Extra: all
Requires-Dist: openai-agents>=0.22.0; extra == 'all'
Provides-Extra: csv
Provides-Extra: drawio
Description-Content-Type: text/markdown

# openai-radar

**OpenAI infrastructure FinOps SDK** — part of the [Hyperscaler Radar](https://github.com/gomorsmi) suite.

[![PyPI](https://img.shields.io/pypi/v/openai-radar)](https://pypi.org/project/openai-radar/)
[![Python](https://img.shields.io/pypi/pyversions/openai-radar)](https://pypi.org/project/openai-radar/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Scan your OpenAI org for assistants, vector stores, fine-tunes, batch jobs, and token usage.
Detect external service relationships in assistant instructions, flag cost anomalies via a findings engine,
and export inventory to CSV or a draw.io architecture diagram — all through a clean Python SDK
that mirrors the `openai-agents` Runner API.

---

## Install

```bash
pip install openai-radar                   # SDK + CLI + CSV and draw.io export
pip install openai-radar[agents]           # + openai-agents integration
pip install openai-radar[all]              # everything
```

Requires Python 3.10+.

CSV and draw.io export are part of the base install — no extras needed, same as
the rest of the Radar suite. The `[csv]` and `[drawio]` extras still resolve (as
no-ops) so older pins keep working.

---

## Quick-start

```python
from openai_radar import RadarClient, Runner

# Reads OPENAI_API_KEY from environment
client = RadarClient()

result = Runner.run_sync(client)

print(result.summary())
result.export_csv("./out/")
result.export_drawio("./out/openai_arch.drawio")
```

### With admin key (org-wide visibility)

```python
client = RadarClient(
    api_key="sk-proj-...",
    admin_key="sk-admin-...",   # unlocks cross-project usage data
)
result = Runner.run_sync(client, config)
```

### Scoped to a project

```python
from openai_radar import RadarClient, Runner, RunConfig

client = RadarClient()
config = RunConfig(project_id="proj_xxx", usage_lookback_days=7)
result = Runner.run_sync(client, config)
```

---

## CLI

```bash
# Full scan — findings table to stdout
openai-radar run

# CSVs + draw.io diagram
openai-radar run --csv-dir ./out --drawio-file arch.drawio

# JSON instead of a table
openai-radar run --output json --out-file scan.json

# Admin key for org-wide usage data
openai-radar run --admin-key sk-admin-... --csv-dir ./out

# Findings only
openai-radar findings

# Scope to a project, 7-day lookback
openai-radar run --project proj_xxx --lookback 7

# Print the version
openai-radar version
```

Flags follow the Radar suite convention: `--output/-o` selects `table` or `json`,
`--out-file` writes the JSON payload, `--csv-dir` writes per-resource CSVs.

---

## openai-agents integration

```bash
pip install openai-radar[agents]
```

```python
from openai_radar.agents import build_radar_agent
from agents import Runner

agent  = build_radar_agent()
result = Runner.run_sync(agent, "Scan my org and flag any cost anomalies")
print(result.final_output)
```

Or compose individual Radar tools into your own agent:

```python
from agents import Agent
from openai_radar.agents.tools import scan_assistants, run_findings, export_drawio

agent = Agent(
    name="My FinOps Agent",
    instructions="...",
    tools=[scan_assistants, run_findings, export_drawio],
)
```

---

## Findings engine

| Rule ID    | Severity | Condition |
|------------|----------|-----------|
| ASST_001   | LOW      | Assistant has zero tools |
| ASST_002   | INFO     | Code Interpreter enabled (file storage costs) |
| VS_001     | MEDIUM   | Vector store > 5 GB |
| VS_002     | HIGH     | Vector store expires within 7 days |
| FT_001     | MEDIUM   | Fine-tune job in `failed` state |
| BATCH_001  | HIGH     | Batch job failure rate > 10% |
| USAGE_001  | MEDIUM   | Model consumes > 10M tokens in lookback window |

---

## Service relationship detection

`AssistantScanner` inspects each assistant's `instructions` field for external service signals
and emits `ServiceRelationship` objects (visualized as edges in the draw.io diagram):

| Kind | Signals |
|------|---------|
| AWS | `aws`, `s3`, `ec2`, `lambda`, `dynamodb`, `sqs` |
| GCP | `gcp`, `bigquery`, `gcs`, `google cloud` |
| AZURE | `azure`, `blob.core.windows`, `cosmosdb` |
| DATABASE | `postgres`, `mysql`, `mongo`, `redis`, `neon` |
| SLACK | `slack` |
| EMAIL | `sendgrid`, `mailgun`, `smtp` |
| WEBHOOK | `webhook`, `http://` |

---

## SDK structure

```
src/openai_radar/
├── client.py            # RadarClient (auth, project vs admin key)
├── runner.py            # Runner, RunConfig, RunResult
├── findings.py          # FindingEngine, Finding, Severity
├── models/base.py       # Pydantic v2 models for all resource types
├── scanners/            # One scanner per resource type
├── exporters/           # CSV + draw.io exporters
├── agents/              # openai-agents tools + build_radar_agent()
└── cli.py               # openai-radar CLI
```

---

## Part of the Hyperscaler Radar suite

`aws-radar` · `gcp-radar` · `azure-radar` · `oci-radar` · `openai-radar` · `datadog-radar` · `coreweave-radar`
