the-third-eye 0.1.0__tar.gz

the_third_eye-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: ["master"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package
+        run: python -m pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Test
+        run: pytest
+      - name: Build package
+        run: python -m build
+      - name: Check package metadata
+        run: python -m twine check dist/*

the_third_eye-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build twine
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Validate distributions
+        run: python -m twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

the_third_eye-0.1.0/LICENSE

@@ -0,0 +1,16 @@
+Apache License
+                           Version 2.0, January 2004
+
+Copyright 2026 Ravi Kumar
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

the_third_eye-0.1.0/PKG-INFO

@@ -0,0 +1,398 @@
+Metadata-Version: 2.5
+Name: the-third-eye
+Version: 0.1.0
+Summary: AI model health and governance control plane for Databricks.
+Project-URL: Homepage, https://github.com/dcsgod/theThirdEye
+Project-URL: Repository, https://github.com/dcsgod/theThirdEye
+Project-URL: Documentation, https://github.com/dcsgod/theThirdEye#readme
+Project-URL: Issues, https://github.com/dcsgod/theThirdEye/issues
+Project-URL: Changelog, https://github.com/dcsgod/theThirdEye/releases
+Author-email: Ravi Kumar <93548891+dcsgod@users.noreply.github.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: ai-governance,ai-observability,databricks,mlops,model-monitoring,modelops
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software 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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: all
+Requires-Dist: build>=1.2; extra == 'all'
+Requires-Dist: databricks-sdk>=0.50; extra == 'all'
+Requires-Dist: mlflow>=2.0; extra == 'all'
+Requires-Dist: pyspark>=3.5; extra == 'all'
+Requires-Dist: pytest>=8.0; extra == 'all'
+Requires-Dist: ruff>=0.8; extra == 'all'
+Requires-Dist: twine>=6.0; extra == 'all'
+Provides-Extra: databricks
+Requires-Dist: databricks-sdk>=0.50; extra == 'databricks'
+Requires-Dist: mlflow>=2.0; extra == 'databricks'
+Requires-Dist: pyspark>=3.5; extra == 'databricks'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: databricks-sdk>=0.50; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# The Third Eye
+
+### AI model health and governance control plane for Databricks
+
+> **Watch. Understand. Act.**
+>
+> Databricks provides the signals. The Third Eye turns them into decisions.
+
+[![CI](https://github.com/dcsgod/theThirdEye/actions/workflows/ci.yml/badge.svg)](https://github.com/dcsgod/theThirdEye/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/the-third-eye?style=for-the-badge&color=4267E8)](https://pypi.org/project/the-third-eye/)
+[![Python](https://img.shields.io/pypi/pyversions/third-eye?style=for-the-badge)](https://pypi.org/project/third-eye/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-4267E8?style=for-the-badge)](https://www.apache.org/licenses/LICENSE-2.0)
+
+---
+
+## What is The Third Eye?
+
+The Third Eye is a **Databricks-native AI health and governance control plane**.
+
+It does not replace Model Serving, MLflow, Unity Catalog, Lakehouse Monitoring, Unity Gateway, or Workflows. It sits above those primitives and turns their signals into an explainable operating view:
+
+```text
+Databricks signals
+      │
+      ├── monitoring
+      ├── inference / trace
+      ├── lineage
+      ├── usage / cost
+      └── governance / guardrails
+      │
+      ▼
+The Third Eye
+      │
+      ├── normalize
+      ├── correlate
+      ├── score
+      ├── explain
+      └── recommend
+      │
+      ▼
+governed model health
+      │
+      ├── dashboard
+      ├── Genie
+      └── Teams / Slack
+```
+
+**Positioning:** not another drift detector. Not another dashboard. The Third Eye is the **decision layer above the native Databricks AI stack**.
+
+---
+
+## Why this exists
+
+AI fleets fail in ways that are difficult to diagnose from a single metric.
+
+A model can look healthy in one system while another already shows a warning:
+
+- feature drift is rising
+- quality is deteriorating
+- an upstream table changed
+- token or endpoint cost spiked
+- a gateway policy was breached
+- model criticality makes the event more urgent
+
+The Third Eye correlates these signals into a single evidence-backed health view.
+
+### The core distinction
+
+```text
+Traditional monitoring:
+metric → threshold → alert
+
+The Third Eye:
+signals → correlation → context → risk → explanation → action
+```
+
+---
+
+## Core capabilities
+
+| Capability | What The Third Eye adds |
+|---|---|
+| **Zero-touch discovery** | Builds a governed model inventory from MLflow, Unity Catalog, and Gateway assets |
+| **Signal normalization** | Creates a common index over native Databricks signals |
+| **Evidence correlation** | Links drift, quality, usage, guardrail, and lineage events |
+| **Composite health** | Produces a criticality-aware 0-100 health score |
+| **Confidence** | Separates strong evidence from incomplete evidence |
+| **Root cause** | Generates evidence-grounded narratives |
+| **Remediation** | Produces ranked next actions rather than just alerts |
+| **Model passport** | Produces a compact governance and audit view per model |
+| **Decision surface** | Feeds AI/BI, Genie, Teams, and Slack from governed outputs |
+
+---
+
+## Architecture
+
+```text
+┌──────────────────────── Databricks native layer ────────────────────────┐
+│ Unity Catalog · MLflow · Monitoring · Inference / Trace · Lineage       │
+│ Unity Gateway · Usage · Guardrails · Databricks Workflows               │
+└────────────────────────────────┬────────────────────────────────────────┘
+                                 │
+                                 ▼
+                    ┌──────────────────────────┐
+                    │ Discovery & Sync         │
+                    │ model / asset registry  │
+                    └─────────────┬────────────┘
+                                  ▼
+                    ┌──────────────────────────┐
+                    │ Signal Normalization     │
+                    │ common signal index      │
+                    └─────────────┬────────────┘
+                                  ▼
+                    ┌──────────────────────────┐
+                    │ Correlation & Scoring    │
+                    │ health + confidence      │
+                    └─────────────┬────────────┘
+                                  ▼
+                    governance.model_health.*
+                         │        │        │
+                         ▼        ▼        ▼
+                       AI/BI    Genie   Alerts
+                                  │
+                                  ▼
+                        Root cause / remediation
+```
+
+![The Third Eye](https://github.com/user-attachments/assets/255a6eb7-6836-4570-9f84-2633b03916ed)
+
+---
+
+## Repository structure
+
+The repository remains the full Databricks implementation and deployment reference:
+
+```text
+adapters/         native-signal adapters
+discovery/        model and lineage discovery
+scoring/          correlation and health scoring jobs
+remediation/     root-cause and remediation generation
+passport/         model passport generation
+sql/              Unity Catalog bootstrap + governed tables
+genie/            Genie instructions
+copilot_studio/  notification / topic notes
+workflows/       Databricks Workflow definitions
+demo/             product demonstration assets
+v2_stretch/       planned governed-autonomy components
+third_eye/       reusable Python scoring primitives
+```
+
+---
+
+## Quickstart
+
+### Install the reusable Python package
+
+```bash
+pip install the-third-eye
+```
+
+### Use the portable scoring kernel
+
+```python
+from third_eye.scoring import health_score, health_tier
+
+score = health_score(
+    drift=0.30,
+    quality=0.92,
+    cost=0.15,
+    guardrail=0.05,
+)
+
+print(f"Health: {score:.2f}")
+print(f"Tier:   {health_tier(score)}")
+```
+
+The package is intentionally small. It exposes deterministic scoring primitives while the Databricks-specific orchestration remains in the repository.
+
+### Databricks integrations
+
+```bash
+pip install "the-third-eye[databricks]"
+```
+
+This optional extra installs the Databricks SDK, MLflow, and Spark dependencies used by the workspace integration layer.
+
+---
+
+## Run locally
+
+The Databricks jobs support the existing mock-mode development path:
+
+```bash
+set THIRD_EYE_MOCK_MODE=true
+python scoring/compute_health_score.py
+python scoring/correlate_signals.py
+```
+
+PowerShell:
+
+```powershell
+$env:THIRD_EYE_MOCK_MODE = "true"
+python scoring/compute_health_score.py
+python scoring/correlate_signals.py
+```
+
+---
+
+## The health score
+
+The central composite calculation is:
+
+```text
+health_score = 100 - (
+    w1 · drift
+  + w2 · (1 - quality)
+  + w3 · cost
+  + w4 · guardrail
+) · criticality_weight
+```
+
+The portable Python implementation keeps this kernel deterministic and independent of Databricks runtime concerns.
+
+---
+
+## Evidence before action
+
+The Third Eye follows a **read-first, evidence-before-action** principle.
+
+A single weak signal should not automatically become a production action.
+
+```text
+signal
+  ↓
+corroborating evidence
+  ↓
+criticality context
+  ↓
+risk / confidence
+  ↓
+incident
+  ↓
+root cause
+  ↓
+recommended action
+```
+
+High-impact production actions remain policy-controlled.
+
+---
+
+## Security and governance
+
+The control plane is designed around governed access rather than copying source systems.
+
+Key principles:
+
+- native Databricks tables remain the source of record
+- normalized signals store pointers and snapshots rather than duplicating raw telemetry
+- secrets should be resolved through Databricks Secrets
+- high-impact automation remains policy-controlled
+- evidence and confidence accompany health decisions
+
+---
+
+## Roadmap
+
+### V1
+
+Discovery → normalization → correlation → scoring → diagnosis → governed outputs.
+
+### V2
+
+Governed autonomy:
+
+```text
+health degradation
+      ↓
+candidate retraining
+      ↓
+champion / challenger
+      ↓
+approval gate
+      ↓
+promotion / rollback
+```
+
+Planned work includes blast-radius analysis, multi-workspace federation, silent-failure detection, richer compliance reporting, and cost-of-drift business impact.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/dcsgod/theThirdEye.git
+cd theThirdEye
+
+python -m pip install -e ".[dev]"
+ruff check .
+pytest
+python -m build
+python -m twine check dist/*
+```
+
+---
+
+## Publishing to PyPI
+
+The repository includes a GitHub Actions workflow for **PyPI Trusted Publishing**.
+
+```text
+GitHub Release
+      ↓
+build sdist + wheel
+      ↓
+twine check
+      ↓
+PyPI Trusted Publishing
+```
+
+For the first release, configure a PyPI Trusted Publisher with:
+
+```text
+Owner:       dcsgod
+Repository:  theThirdEye
+Workflow:    publish.yml
+Environment: pypi
+```
+
+Then create a GitHub release such as:
+
+```text
+v0.1.0
+```
+
+The workflow publishes the built distributions to PyPI without a long-lived API token.
+
+---
+
+## License
+
+Apache-2.0.
+
+---
+
+<div align="center">
+
+**The Third Eye**
+
+*Watch. Understand. Act.*
+
+</div>