Metadata-Version: 2.4
Name: leai
Version: 0.3.22
Summary: Oracle Database reverse engineering, lineage tracing, impact analysis, and RAG/LLM documentation engine
Author: Lucas Sobral
License: MIT
Project-URL: Homepage, https://github.com/lucasbral/leai
Project-URL: Repository, https://github.com/lucasbral/leai
Project-URL: Issues, https://github.com/lucasbral/leai/issues
Keywords: oracle,database,rag,llm,plsql,lineage,documentation,copilot,vector-db
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Documentation
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: License :: OSI Approved :: MIT License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: oracledb>=2.2.0
Requires-Dist: typer>=0.12.3
Requires-Dist: rich>=13.7.1
Requires-Dist: PyYAML>=6.0.1
Requires-Dist: pydantic>=2.7.0
Requires-Dist: prompt_toolkit>=3.0.40
Requires-Dist: boto3>=1.34.0
Provides-Extra: dev
Requires-Dist: coverage>=7.0.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
Requires-Dist: mkdocs-static-i18n>=1.2.0; extra == "docs"
Requires-Dist: mkdocs-minify-plugin>=0.8.0; extra == "docs"

# LEAI — Oracle Database Intelligence & Documentation Engine

<div align="center">

[![Documentation](https://img.shields.io/badge/docs-GitHub_Pages-blue.svg?style=for-the-badge&logo=github)](https://lucasbral.github.io/leai/)
[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg?style=for-the-badge&logo=python)](https://github.com/lucasbral/leai)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)

**Official Bilingual Documentation:** [https://lucasbral.github.io/leai/](https://lucasbral.github.io/leai/) (English & Português)

</div>

**LEAI** (*Lê - Aí* in PT-BR) is an enterprise reverse engineering, impact analysis, and autonomous AI copilot engine for **Oracle Database**, specifically designed to power **Retrieval-Augmented Generation (RAG)**, **LLMs**, and software engineers maintaining complex database ecosystems.

---

> [!IMPORTANT]
> 🔒 **Security & Data Privacy Guarantee:**
>
> **LEAI NEVER accesses, reads, or extracts business data (table records or rows) stored in the database.**
> It strictly reads **data dictionary metadata and DDL definitions**: tables, column types, primary/foreign keys, views, materialized views, stored procedures, packages, triggers, indexes, and synonyms.
>
> 💡 **A database user with metadata-only / audit permissions (such as `SELECT ANY DICTIONARY` or read access to `ALL_*` catalog views) is 100% sufficient.** This ensures full enterprise security and compliance (LGPD / GDPR / SOC2) with zero risk of exposing confidential or sensitive business data.

---

## 📑 Table of Contents / Índice

- [📌 What Is It?](#-what-is-it)
- [⚙️ How It Works (Pipeline)](#️-how-it-works)
- [🤖 Autonomous Agent & Tool Calling Engine](#-autonomous-agent--tool-calling-engine)
- [🔗 Transparent Synonym Resolution](#-transparent-synonym-resolution)
- [✂️ PL/SQL Semantic Compression](#️-plsql-semantic-compression)
- [🚀 Quickstart: Using LEAI in Any Project](#-quickstart-using-leai-in-any-project)
- [📖 CLI Command Reference](#-cli-command-reference)
  - [1. Pipeline & Core Commands (`leai`, `extract`, `annotate`, `compile`, `doc`, `generate`)](#1-pipeline--core-commands)
  - [2. Impact Analysis & Lineage (`leai trace`)](#2-impact-analysis--lineage-leai-trace)
  - [3. AI Copilot & Chat (`leai ask`, `leai chat`, `leai models`, `leai enrich`)](#3-ai-copilot--chat)
  - [4. Interactive Web Studio (`leai serve`)](#4-interactive-web-studio-leai-serve)
  - [5. Specialized Subagents (`leai agent`)](#5-specialized-subagents-leai-agent)
  - [6. Autonomous Workflows (`leai workflow`)](#6-autonomous-workflows-leai-workflow)
  - [7. Business Rules & Canonical Glossary (`leai rule`)](#7-business-rules--canonical-glossary-leai-rule)
  - [8. GitOps Version Control (`leai git`)](#8-gitops-version-control-leai-git)
  - [9. S3 / SeaweedFS Distributed Storage (`leai seaweed`)](#9-s3--seaweedfs-distributed-storage-leai-seaweed)
  - [10. Maintenance & Diagnostics (`leai changes`, `leai init`, `leai doctor`)](#10-maintenance--diagnostics)
- [📁 Directory Structure](#-directory-structure)
- [🧪 Automated Testing](#-automated-testing)

---

## 📌 What Is It?

Enterprise Oracle databases accumulate years of business rules scattered across hundreds of tables, views, triggers, and massive PL/SQL packages (3,000 to 10,000+ lines of code).

Enabling developers or AI assistants to reliably understand such environments is challenging due to three main issues:
1. **Token Inefficiency & Hallucinations:** Sending entire monolithic packages into an LLM context is expensive, slow, and triggers attention degradation ("Lost in the Middle").
2. **Hidden Dependencies:** Altering a single column can silently break triggers, views, and procedures across multiple schemas.
3. **Synonyms and Aliases:** Stored procedures frequently access tables via private or public synonyms (`PUBLIC SYNONYM`), creating the false impression that referenced objects do not exist or belong elsewhere.

LEAI solves this by extracting the Oracle data dictionary, constructing a cross-schema dependency graph, and providing an autonomous multi-step reasoning agent with offline database tools.

---

## ⚙️ How It Works

LEAI operates via a **3-stage decoupled pipeline**:

```mermaid
flowchart LR
    subgraph S1 [1. RAW JSON]
        DB[(Oracle Database)] -->|leai extract| RAW[Technical Snapshots<br/>./raw/*.json]
    end

    subgraph S2 [2. YAML Annotations]
        RAW -->|leai annotate| YAML[Business Annotations<br/>./annotations/*.yml]
        HUMAN[Human DBA / Engineer] -.-> YAML
        AI[LLM Auto-Enrich] -.-> YAML
    end

    subgraph S3 [3. DOCS & RAG]
        RAW & YAML -->|leai compile| DOCS[Markdown + Mermaid<br/>./docs/*.md]
        DOCS --> RAG[Vector Stores & LLMs]
    end
```

---

## 🤖 Autonomous Agent & Tool Calling Engine

When running `leai chat` or `leai ask`, the assistant uses an autonomous **Tool-Calling Reasoning Loop** (`AgentExecutionEngine`) with up to 10 iterations per turn. Instead of guessing or hallucinating, the model invokes specialized in-memory database tools:

| Tool Name | Parameters | Purpose |
| :--- | :--- | :--- |
| **`search_catalog`** | `query`, `object_types`, `schema` | Fast text and regex search across tables, views, procedures, packages, functions, and synonyms. |
| **`get_table_schema`** | `table_name`, `schema` | Full table/view DDL inspection: column data types, nullable constraints, PKs, FKs, unique keys, check constraints, and indexes. |
| **`get_subprogram_source`** | `package_name`, `subprogram_name` | Surgical extraction of standalone procedure/function or specific subprogram inside a package with semantic compression. |
| **`grep_plsql_code`** | `pattern`, `object_name`, `schema` | Fast regex code search across all stored PL/SQL bodies without reading entire packages. |
| **`trace_object_lineage`** | `object_name`, `schema`, `depth`, `direction` | Multi-level upstream/downstream dependency graph with automated refactoring risk score (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`). |
| **`explain_and_tune_sql`** | `sql_query`, `detailed` | Evaluates sargability, non-sargable functions (`TRUNC`, `NVL`, `UPPER`), FTS risks, `NOT IN` NULL pitfalls, compound index ordering, and AI query rewrites. |
| **`validate_oracle_sql`** | `sql_query`, `target_schema` | Validates Oracle dialect compliance, blocks non-Oracle constructs (`LIMIT`, `BOOLEAN`, `ILIKE`, `IFNULL`, `+` concat), and checks against schema catalog. |
| **`lookup_business_term`** | `query`, `tag` | Searches domain glossary for canonical business definitions, calculation rules, and canonical SQL predicates. |

---

## 🔗 Transparent Synonym Resolution

Stored procedures often access objects via `PUBLIC SYNONYM` or remote database links (`@dblink`). LEAI snapshots `ALL_SYNONYMS` and transparently dereferences every alias to its authentic physical entity, avoiding broken chains and LLM hallucinations.

---

## ✂️ PL/SQL Semantic Compression

For massive 10,000-line packages, LEAI extracts only the specific subprogram body requested while producing a lightweight signature skeleton of the rest of the package. This **reduces token consumption by up to 95%** while eliminating prompt distraction.

---

## 🚀 Quickstart: Using LEAI in Any Project

### Step 1: Install LEAI

```bash
# Via pip
pip install leai

# Or via uv (recommended)
uv tool install leai
# Or in an existing project
uv add leai
```

### Step 2: Initialize Configuration

```bash
# In English (default)
leai init

# Or in Brazilian Portuguese
leai init --lang pt-BR
```

Configure your `leai.yml`:

```yaml
language: "en-US"                 # "en-US" (default) or "pt-BR"
update_check: true                # true (default) or false (disable with --no-update-check)
dsn: "oracle://${DB_USER}:${DB_PASS}@${DB_HOST}:1521/${DB_SERVICE}"

schemas:
  - HR
  - SALES

rawPath: "./raw"
annotationsPath: "./annotations"
docPath: "./docs"

ai:
  default_provider: "ollama"      # ollama, local, openai, gemini, anthropic, deepseek, qwen, kimi, grok
  temperature: 0.2
  timeout: 300.0
  max_history_turns: 15           # Chat history turns retained in memory
  max_agent_iterations: 10        # Maximum reasoning tool iterations per turn
  max_subagent_iterations: 5      # Maximum iterations for specialized subagents
  providers:
    ollama:
      base_url: "http://localhost:11434/v1"
      model: "qwen2.5-coder:latest"
      temperature: 0.1
      num_ctx: 32768              # Context window size for Ollama (prevents truncation on large DDLs)
      keep_alive: "1h"            # Keep model memory resident
    local:
      base_url: "http://localhost:1234/v1" # LM Studio, vLLM, LocalAI
      model: "qwen2.5"
      num_ctx: 32768
      max_tokens: 4096
    openai:
      api_key: "${OPENAI_API_KEY}"
      model: "gpt-4o-mini"
      max_tokens: 4096
    gemini:
      api_key: "${GEMINI_API_KEY}"
      model: "gemini-2.5-flash"
```

### Step 3: Run the Full Pipeline

```bash
# 1. Run complete pipeline (extract + annotate + compile)
leai

# 2. Trace impact of modifying a table
leai trace EMPLOYEES --depth 2

# 3. Launch interactive terminal copilot
leai chat

# 4. Or launch the Web Studio in browser
leai serve
```

---

## 📖 CLI Command Reference

### 1. Pipeline & Core Commands

#### `leai` (or `leai generate`)
Executes the full automated pipeline: technical extraction, business annotation synchronization, and final Markdown compilation.

| Flag / Option | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `-L`, `--lang LOCALE` | Option | `en-US` | Interface language (`en-US` or `pt-BR`). |
| `--no-update-check` | Flag | `False` | Disables remote PyPI check for newer versions on startup. |
| `-c`, `--config PATH` | Option | `leai.yml` | Configuration file path. |
| `-s`, `--schemas TEXT` | Option | From config | Specific schema(s) to process. |
| `-t`, `--object-types TEXT` | Option | From config | Filter object types (e.g., `-t tables -t packages`). |
| `--with-traces / --no-traces` | Flag | `True` | Include Mermaid dependency lineage and risk ratings. |
| `--rag-json`, `--rag` | Flag | `False` | Also exports structured JSON chunks for Vector DBs. |
| `-d`, `--depth INT` | Option | `1` | Traversal depth for dependency tree. |
| `--seaweed` | Flag | `False` | Routes metadata through remote S3/SeaweedFS storage. |
| `--no-cache` | Flag | `False` | 100% remote mode without local files. |
| `--force-upload` | Flag | `False` | Forces re-upload to storage, bypassing SHA-256 cache. |

```bash
leai -s HR -t tables -t packages --depth 2 --rag-json
```

#### `leai extract`
Extracts Oracle data dictionary definitions into raw JSON snapshots.

| Flag / Option | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `-c`, `--config PATH` | Option | `leai.yml` | Path to `leai.yml`. |
| `-s`, `--schemas TEXT` | Option | From config | Target schema(s). |
| `-t`, `--object-types TEXT` | Option | From config | Object categories to extract. |
| `-d`, `--days INT` | Option | `None` | **Incremental:** Extract only objects modified in the last N days via `LAST_DDL_TIME`. |
| `--seaweed` | Flag | `False` | Stream snapshots directly to S3. |
| `--no-cache` | Flag | `False` | Avoids saving files to local `rawPath`. |
| `--force-upload` | Flag | `False` | Forces overwrite in storage bucket. |

```bash
# Incremental extraction of objects modified in the last 30 days
leai extract --days 30
```

#### `leai annotate`
Synchronizes YAML business annotation stubs under `annotations/` without overwriting existing human notes.

| Flag / Option | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `-c`, `--config PATH` | Option | `leai.yml` | Path to `leai.yml`. |
| `-s`, `--schemas TEXT` | Option | From config | Target schema(s). |
| `-t`, `--object-types TEXT` | Option | From config | Object categories to synchronize. |
| `--seaweed` | Flag | `False` | Syncs annotations directly in S3. |
| `--no-cache` | Flag | `False` | Zero-cache remote execution. |

#### `leai doc <OBJECT>`
Opens the in-terminal interactive documentation editor for a specific database entity.

```bash
leai doc EMPLOYEES
leai doc PKG_BILLING
```

#### `leai compile`
Recompiles the final Markdown documentation in `docs/` with Mermaid.js diagrams.

| Flag / Option | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `-c`, `--config PATH` | Option | `leai.yml` | Path to `leai.yml`. |
| `-o`, `--object-name TEXT` | Option | `None` | Recompiles an isolated individual entity. |
| `-s`, `--schemas TEXT` | Option | From config | Target schema(s). |
| `-t`, `--object-types TEXT` | Option | From config | Filter object types. |
| `--with-traces / --no-traces` | Flag | `True` | Include Mermaid lineage graphs. |
| `--rag-json`, `--rag` | Flag | `False` | Export JSON chunks for Vector DBs. |
| `-d`, `--depth INT` | Option | `1` | Traversal depth for dependency tree. |
| `--seaweed` | Flag | `False` | Uses remote S3 snapshots. |
| `--no-cache` | Flag | `False` | Pure remote mode. |

---

### 2. Impact Analysis & Lineage (`leai trace`)

Generates multi-level upstream/downstream dependency trees, automated risk scores (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`), and Mermaid diagrams.

| Flag / Option | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `OBJECT` | Argument | **Required** | Target entity name to trace. |
| `-d`, `--depth INT` | Option | `1` | Maximum graph exploration depth. |
| `-s`, `--schema TEXT` | Option | `None` | Schema of the object when resolving ambiguous names. |
| `--offline` | Flag | `False` | **Offline Mode:** Resolves dependencies from local `raw/` without Oracle connection. |
| `-o`, `--output PATH` | Option | `None` | Custom path to save the generated Markdown dossier. |
| `--rag-json`, `--rag` | Flag | `False` | Exports structured JSON chunks for RAG. |
| `--seaweed` | Flag | `False` | Resolves metadata from remote S3. |
| `--no-cache` | Flag | `False` | Pure remote execution. |

```bash
leai trace CONTRACTS_TB --depth 3 --offline --output ./dossier.md
```

---

### 3. AI Copilot & Chat

#### `leai ask <QUESTION>`
Answers one-off natural language queries about database structure and business rules.

```bash
leai ask "Which procedures update customer status to INACTIVE?" -p gemini
```

#### `leai chat`
Launches the interactive terminal copilot console with conversation memory, syntax highlighting, and live tool execution.

| Flag / Option | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `-p`, `--provider TEXT` | Option | From config | Active AI provider. |
| `-m`, `--model TEXT` | Option | From config | Target AI model identifier. |
| `-c`, `--config PATH` | Option | `leai.yml` | Path to `leai.yml`. |
| `-w`, `--web` | Flag | `False` | Launches Web Studio server and opens chat in browser. |
| `--seaweed` | Flag | `False` | Resolves metadata from remote S3. |
| `--no-cache` | Flag | `False` | Pure in-memory execution. |

**In-Session Slash Commands:**
* `/tune <sql>`: Analyze query sargability, FTS risks, compound indexes, and get AI tuning proposals.
* `/validate <sql>`: Validate Oracle SQL dialect compliance and cross-check against schema catalog.
* `/thoughts [on|off]`: Toggle live reasoning/thought token streaming in the terminal.
* `/workflow <name> <obj>`: Execute autonomous workflows (`reverse-procedure`, `impact-analysis`, `safe-refactor`).
* `/agent <role> <task>`: Run specialized subagents (`catalog_researcher`, `plsql_analyst`, `lineage_auditor`, etc.).
* `/copy [all|code|N]`: Copy response or code block directly to OS clipboard.
* `/doc [obj]`: In-terminal YAML annotation & documentation editor.
* `/rule [list|add|del|find]`: Manage global domain glossary and canonical rules.
* `/enrich [obj]`: Auto-enrich business rules with LLM.
* `/compile [obj]`: Recompile Markdown docs (supports single object).
* `/trace <obj>`: Inline dependency & impact X-ray with Mermaid.
* `/tables`: List all catalog tables with column counts and primary keys.
* `/schema [s]`: Show full overview of schema objects.
* `/changes [d]`: Audit objects modified in last N days (Default: 7).
* `/provider <p>`: Switch AI provider dynamically (`ollama`, `openai`, `gemini`, `anthropic`, `local`, etc.).
* `/models [p]`: List available AI models returned by provider API.
* `/model <p> [m]`: Switch AI model dynamically.
* `/audit [last|session|export]`: Inspect AI tool call trace and latency.
* `/tools`: Quick viewer for last turn's tool execution inputs/outputs.
* `/save [file.md]`: Export current conversation transcript to Markdown.
* `/clear`: Clear conversation memory and reset screen.
* `/exit`, `/quit`: Exit interactive copilot session.

**Smart Autocompletion Prefixes:**
* `@`: Autocomplete catalog objects with icons (`📋 TABLE`, `📦 PACKAGE`, `⚙️ PROCEDURE`, `👁️ VIEW`, `⚡ TRIGGER`, `🔢 SEQUENCE`, `🔗 SYNONYM`).
* `#`: Autocomplete business rules and canonical terms from the domain glossary.
* `/`: Autocomplete slash commands and sub-arguments.

#### `leai enrich`
Invokes the LLM to inspect DDLs and draft automated business descriptions for undocumented entities.

```bash
leai enrich -o EMPLOYEES --overwrite -p gemini
```

#### `leai models`
Lists all configured AI providers, benchmarks network latency, and validates API keys.

---

### 4. Interactive Web Studio (`leai serve`)

Launches the visual **LEAI Web Documentation & Annotation Studio** daemon for in-browser collaborative annotation, instant Markdown compilation, and streaming AI copilot chat.

* **Real-time SeaweedFS S3 Sync:** Annotation edits in the browser (`POST /api/annotations`) are saved locally and synced directly to the S3 bucket in real time.
* **Remote Fallback:** Loads annotations directly from SeaweedFS S3 if not present on local disk.

| Flag / Option | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `--port` | Option | `8891` | TCP port for local server. |
| `--host` | Option | `127.0.0.1` | Network interface to bind. |
| `--open-browser / --no-open-browser` | Flag | `True` | Launches default browser on startup. |
| `-c`, `--config PATH` | Option | `leai.yml` | Path to configuration file. |
| `-p`, `--provider TEXT` | Option | From config | AI provider override. |

```bash
leai serve --host 0.0.0.0 --port 9000
```

---

### 5. Specialized Subagents (`leai agent`)

Executes isolated technical personas with restricted, laser-focused database toolsets:

* `leai agent list`: Lists registered subagents.
* `leai agent run <ROLE> <TASK>`: Executes a subagent.

| Subagent Role | Specialist Title | Focus & Permitted Tools |
| :--- | :--- | :--- |
| **`catalog_researcher`** | Catalog Researcher | Explores schema entities, synonyms, column types. Tools: `get_table_schema`, `search_catalog`, `lookup_business_term`. |
| **`plsql_analyst`** | PL/SQL Analyst | Reverse engineers routines, algorithms, and SQL tuning. Tools: `get_subprogram_source`, `grep_plsql_code`, `get_table_schema`, `explain_and_tune_sql`, `validate_oracle_sql`. |
| **`lineage_auditor`** | Lineage Auditor | Evaluates cascading risk and impact before refactoring. Tools: `trace_object_lineage`, `search_catalog`, `get_table_schema`. |
| **`patch_generator`** | Patch Engineer | Generates zero-downtime DDL migration scripts and rollback plans. Tools: `get_table_schema`, `get_subprogram_source`, `grep_plsql_code`, `validate_oracle_sql`, `explain_and_tune_sql`. |
| **`doc_annotator`** | Documentation Annotator | Generates domain-aligned business annotations. Tools: `get_table_schema`, `get_subprogram_source`, `lookup_business_term`. |

```bash
leai agent run plsql_analyst "Explain the interest calculation algorithm in PKG_BILLING and suggest index tuning"
```

---

### 6. Autonomous Workflows (`leai workflow`)

Multi-step orchestrated pipelines for high-risk engineering and reverse-engineering tasks:

* `leai workflow list`: Lists available workflows (`impact-analysis`, `safe-refactor`, `reverse-procedure`).
* `leai workflow run <NAME> <TARGET>`: Executes a workflow.

| Workflow Name | Aliases | Description |
| :--- | :--- | :--- |
| **`impact-analysis`** | `impact`, `lineage` | 4-step impact assessment: entity resolution, graph exploration, risk calculation (`LOW` to `CRITICAL`), and Markdown dossier. |
| **`safe-refactor`** | `refactor`, `patch` | 4-step phased refactoring plan, backward compatibility checks, semantic patch generation, and rollback script. |
| **`reverse-procedure`** | `reverse`, `decomp` | 5-step PL/SQL reverse engineering: source extraction, CRUD access matrix (`SELECT`/`INSERT`/`UPDATE`/`DELETE`), outgoing routine/package calls, business validation rules, and Mermaid flowchart diagram. |

```bash
# Comprehensive impact dossier before modifying a table
leai workflow run impact CUSTOMERS_TB --output ./customers_impact.md

# Safe phased refactoring plan and DDL patch
leai workflow run refactor PKG_BILLING -p claude

# Decompile and specify business rules of a PL/SQL procedure with Mermaid diagram
leai workflow run reverse-procedure PRC_ATUALIZA_SALARIO --output ./specs.md
```

---

### 7. Business Rules & Canonical Glossary (`leai rule`)

Codifies domain concepts and canonical SQL predicates so AI copilots generate accurate queries:

* `leai rule list`: Lists codified business rules.
* `leai rule add <TERM>`: Adds a canonical rule.
* `leai rule show <TERM>`: Displays rule specifications.

```bash
leai rule add "ACTIVE_CUSTOMER" \
  --table "CUSTOMERS_TB" \
  --canonical-filter "RECORD_STATUS = 'A' AND IS_LOCKED = 0" \
  --definition "Customers eligible to place orders and receive billing invoices" \
  --tags "sales,compliance"
```

---

### 8. GitOps Version Control (`leai git`)

Treats documentation as first-class code (**Docs-as-Code**):

* `leai git status [--fetch]`: Inspects repository status across tracked documentation paths.
* `leai git pull`: Pulls latest annotations from remote Git repository.
* `leai git sync [-m "message"]`: Stages, commits, and pushes modified annotations and docs.

```bash
leai git sync -m "docs(billing): update tax calculation business rules"
```

---

### 9. S3 / SeaweedFS Distributed Storage (`leai seaweed`)

Collaborative metadata persistence using S3-compatible Object Storage:

* `leai seaweed status`: Verifies S3 connection and bucket health.
* `leai seaweed push`: Uploads local snapshots to remote S3 bucket.
* `leai seaweed pull`: Downloads snapshots from remote S3 bucket.
* **Web Studio Integration:** Edits made in Web Studio (`/serve`) sync directly to SeaweedFS in real time.
* **Lifecycle Rules:** Compatible with standard S3 lifecycle configurations (`NoncurrentVersionExpiration` on `annotations/`) to purge old non-current versions automatically.

---

### 10. Maintenance & Diagnostics

* **`leai changes`**: Audits database objects modified in the last N days via Oracle's `LAST_DDL_TIME` (`-d`, `--days`, `-u`, `--user`).
* **`leai doctor`** (or `check`): Pre-flight verification of Oracle connectivity, catalog permissions, pipeline directories, and AI credentials.
* **`leai init`**: Generates a starter `leai.yml` (`-L`, `--lang` [`en-US`|`pt-BR`], `-f`, `--force`, `-o`, `--output`).

---


## 📘 External Wiki Integration (Wiki.js)

LEAI can seamlessly integrate with a corporate **Wiki.js** instance to enrich the AI context during chat sessions. Instead of relying solely on database schemas, the agent can autonomously query your external Wiki using the GraphQL API.

To enable this feature, configure the wiki section in your leai.yml:

`yaml
wiki:
  enabled: true
  url: "https://wiki.example.com"
  token: ""
`

When enabled, the AI gains access to the search_wiki and 
ead_wiki_page tools. When asked a business question, it can proactively search your wiki, read relevant markdown pages, and combine that knowledge with the database structure to provide a comprehensive answer.

---

## 📁 Directory Structure

```text
my_project/
├── leai.yml                  <-- Master configuration file
├── raw/                      <-- Raw technical JSON snapshots extracted from Oracle
│   └── HR.json
├── annotations/              <-- Human & AI business rules in YAML (non-destructive)
│   └── HR.yml
└── docs/                     <-- Final compiled Markdown documents for RAG and humans
    └── HR/
        ├── INDEX.md          <-- Master navigation index
        ├── tables/           <-- Tables with Mermaid diagrams and YAML frontmatter
        └── code_objects/     <-- Procedures, packages, functions, views
```

---

## 🧪 Automated Testing

To run the complete automated test suite:

```bash
# Run unit tests with test coverage reporting
uv run coverage run -m unittest discover tests
uv run coverage report -m

# Run code linter
uv run ruff check .
```

---

<div align="center">

**LEAI** — Built for Oracle Engineers, Enterprise RAG, and Autonomous AI Copilots.

</div>
