baucli 1.0.1__py3-none-any.whl

baucli/api.py

@@ -0,0 +1,914 @@
+"""BAUCLI — REST API client for BAU Server.
+
+All communication with the BAU Server goes through this module.
+Base URL: https://begbrokerdev.begcloud.com/ords/bauctx/api/v1
+"""
+
+import json
+from typing import Optional
+import requests
+
+from baucli import __version__, __product__
+
+
+class BauApiError(Exception):
+    """BAU API error with status and message."""
+    def __init__(self, message: str, status_code: int = 0, response: dict = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response or {}
+
+
+class BauSessionError(BauApiError):
+    """Session token missing/invalid/expired/revoked. Caller should `baucli login`."""
+
+
+SESSION_ERROR_TAGS = {
+    "session_missing", "session_invalid", "session_revoked",
+    "session_expired", "session_tenant_mismatch",
+}
+
+
+class BauApi:
+    """REST API client for BAU Server."""
+
+    def __init__(self, api_url: str, api_key: str = None,
+                 session_token: str = None, timeout: int = 30):
+        self.api_url = api_url.rstrip("/")
+        self.api_key = api_key
+        self.session_token = session_token
+        self.timeout = timeout
+        self.session = requests.Session()
+        self.session.headers.update({
+            "User-Agent": f"{__product__}/{__version__}",
+            "Accept": "application/json",
+        })
+        if api_key:
+            self.session.headers["Authorization"] = f"Bearer {api_key}"
+        if session_token:
+            self.session.headers["X-Bau-Session"] = session_token
+
+    def _request(self, method: str, path: str, json_data: dict = None,
+                 params: dict = None, auth_required: bool = True,
+                 timeout: int = None) -> dict:
+        """Make an HTTP request to the BAU API.
+
+        timeout: per-call override in seconds. Falls back to self.timeout.
+        Long server-side endpoints pass a higher floor here (e.g. rag_index).
+        """
+        url = f"{self.api_url}/{path.lstrip('/')}"
+        eff_timeout = timeout or self.timeout
+
+        headers = {}
+        if not auth_required and self.api_key:
+            # Remove Bearer for public endpoints
+            headers["Authorization"] = ""
+
+        try:
+            if not auth_required:
+                # Use a clean session without Bearer for public endpoints
+                resp = requests.request(
+                    method, url, json=json_data, params=params,
+                    timeout=eff_timeout,
+                    headers={"User-Agent": f"{__product__}/{__version__}",
+                             "Accept": "application/json",
+                             "Content-Type": "application/json"},
+                )
+            else:
+                resp = self.session.request(
+                    method, url, json=json_data, params=params,
+                    timeout=eff_timeout,
+                )
+        except requests.ConnectionError:
+            raise BauApiError(f"Cannot connect to BAU Server at {self.api_url}")
+        except requests.Timeout:
+            raise BauApiError(f"Request timeout ({eff_timeout}s) to {url}")
+
+        data = self._parse_body(resp)
+
+        if resp.status_code == 401:
+            msg = (data or {}).get("message", "Unauthorized") if isinstance(data, dict) else "Unauthorized"
+            if msg in SESSION_ERROR_TAGS:
+                raise BauSessionError(msg, 401, data or {})
+            raise BauApiError(msg, 401, data or {})
+
+        if data is None:
+            # Plain-text response (e.g. deploy DDL script).
+            return {"status": "ok", "text": resp.text}
+
+        if isinstance(data, dict) and data.get("status") == "error":
+            raise BauApiError(
+                data.get("message", "Unknown error"),
+                resp.status_code, data
+            )
+
+        return data
+
+    @staticmethod
+    def _parse_body(resp) -> Optional[dict]:
+        """Parse response body as JSON. Handles the ORDS plsql/block quirk
+        where OWA_UTIL.MIME_HEADER emits `Content-type: ...\\n\\n{json}` into
+        the body instead of an HTTP header. Returns None for plain-text bodies.
+        """
+        try:
+            return resp.json()
+        except (json.JSONDecodeError, ValueError):
+            pass
+        text = resp.text
+        if text.lstrip().lower().startswith("content-type:"):
+            sep = text.find("\n\n")
+            if sep > 0:
+                try:
+                    return json.loads(text[sep + 2:])
+                except (json.JSONDecodeError, ValueError):
+                    pass
+        return None
+
+    # ── Public endpoints (no auth) ──────────────────────────
+
+    def health(self) -> dict:
+        """GET /health — Server health check."""
+        return self._request("GET", "health", auth_required=False)
+
+    def license_activate(self, license_key: str) -> dict:
+        """POST /license/activate — Activate license, receive config."""
+        return self._request("POST", "license/activate",
+                             json_data={"license_key": license_key},
+                             auth_required=False)
+
+    def license_validate(self, license_key: str) -> dict:
+        """POST /license/validate — Validate license (heartbeat)."""
+        return self._request("POST", "license/validate",
+                             json_data={"license_key": license_key},
+                             auth_required=False)
+
+    # ── Protected endpoints (Bearer token) ──────────────────
+
+    def environments(self) -> dict:
+        """GET /environments — read-only tenant promotion ladder (no secrets).
+
+        Topology + connectivity (engine/host/service) + the SQLcl named
+        connection HINT per env. Lets a thin client discover the ladder without
+        a direct BAUCTX login; credentials stay local (wallet/keyring)."""
+        return self._request("GET", "environments")
+
+    # ── Agent verification (Phase 1A) — read-only fact-check ─
+    # Structural ground-truth from the catalog. Every response carries
+    # ok/source/confidence/stale/in_project + exists:false first-class.
+
+    def verify_object(self, schema: str, object: str) -> dict:
+        """GET /verify/object — does the table/view/PL-SQL/sequence exist? Type,
+        status_doc, purpose, source/confidence, in_project."""
+        return self._request("GET", "verify/object",
+                             params={"schema": schema, "object": object})
+
+    def verify_column(self, schema: str, table: str, column: str) -> dict:
+        """GET /verify/column — a single column's ground-truth: data_type,
+        nullable, PK/FK/UK, fk_ref, semantic_domain, sensitive, label, default,
+        sample_values, description + source/confidence."""
+        return self._request("GET", "verify/column",
+                             params={"schema": schema, "table": table, "column": column})
+
+    def agent_columns(self, schema: str, table: str) -> dict:
+        """GET /columns — compact list of every column of a table (name/type/
+        nullable/pk/fk/uk/domain/label/default)."""
+        return self._request("GET", "columns",
+                             params={"schema": schema, "table": table})
+
+    def agent_fk(self, schema: str, table: str) -> dict:
+        """GET /fk — foreign keys: references (this→other) + referenced_by
+        (other→this). Kills invented joins."""
+        return self._request("GET", "fk",
+                             params={"schema": schema, "table": table})
+
+    def agent_domain(self, schema: str, table: str, column: str) -> dict:
+        """GET /domain — closed enum of a column (CHECK values + PT/EN labels).
+        Kills invented enum values."""
+        return self._request("GET", "domain",
+                             params={"schema": schema, "table": table, "column": column})
+
+    def agent_constraints(self, schema: str, table: str) -> dict:
+        """GET /constraints — PK/UK/FK/CHECK of a table (+ friendly DOCERRMSG
+        message per constraint)."""
+        return self._request("GET", "constraints",
+                             params={"schema": schema, "table": table})
+
+    def conventions(self, schema: str) -> dict:
+        """GET /conventions — house style DERIVED from the catalog (PK/FK naming,
+        audit columns, active flag + values, top semantic domains) + the schema's
+        AI_CONTEXT prose (form/report standard). For generating new code that
+        matches the rest of the schema."""
+        return self._request("GET", "conventions", params={"schema": schema})
+
+    def task_brief(self, schema: str, task: str = None, tables: str = None,
+                   scope: str = None, budget: int = 8000) -> dict:
+        """GET /task_brief — one curated context pack for a task: target tables
+        (resolved from `tables` CSV > `scope` code > keyword match on `task`),
+        each with compact columns/FKs/closed-domains, plus lean house conventions
+        and the business flows that touch them. Budget-aware (`budget` chars)."""
+        params = {"schema": schema, "budget": budget}
+        if task:   params["task"] = task
+        if tables: params["tables"] = tables
+        if scope:  params["scope"] = scope
+        return self._request("GET", "task_brief", params=params)
+
+    def validate_change(self, schema: str, intent: dict) -> dict:
+        """POST /validate-change — validate a structured change intent (write-loop)
+        against structure, conventions, impact and data profile. Returns
+        verdict PASS/WARN/FAIL + checks + a house-style suggested_ddl. Read-only.
+        intent: {action: ADD_COLUMN|MODIFY_NOT_NULL|ADD_UNIQUE|ADD_INDEX|ADD_FK,
+        table, column, data_type?, nullable?, references?, ref_column?}."""
+        return self._request("POST", "validate-change", json_data=intent,
+                             params={"schema": schema})
+
+    def propose(self, schema: str, intent: dict) -> dict:
+        """POST /propose — validate + STORE a change proposal (status PROPOSED).
+        Returns {proposal_id, verdict, validation}."""
+        return self._request("POST", "propose", json_data=intent,
+                             params={"schema": schema})
+
+    def proposals(self, schema: str = None, status: str = None) -> dict:
+        """GET /proposals — list change proposals (optionally by schema/status)."""
+        p = {}
+        if schema: p["schema"] = schema
+        if status: p["status"] = status
+        return self._request("GET", "proposals", params=p)
+
+    def proposal(self, proposal_id: int) -> dict:
+        """GET /proposals/{id} — full proposal detail (DDL + validation)."""
+        return self._request("GET", f"proposals/{proposal_id}")
+
+    def proposal_regen_purpose(self, proposal_id: int) -> dict:
+        """POST /proposals/{id}/regen-purpose — (re)generate the AI motive
+        (purpose) for a proposal. Returns {ok, id, purpose}."""
+        return self._request("POST", f"proposals/{proposal_id}/regen-purpose")
+
+    def proposal_status(self, proposal_id: int, status: str, notes: str = None) -> dict:
+        """POST /proposals/{id}/status — approve/reject/apply a proposal."""
+        body = {"status": status}
+        if notes: body["notes"] = notes
+        return self._request("POST", f"proposals/{proposal_id}/status", json_data=body)
+
+    def profile(self, schema: str, table: str) -> dict:
+        """GET /profile — a table's DATA PROFILE (per column: num_distinct,
+        null_pct, histogram, top_values) from optimizer stats. Grounds the
+        agent in the real data distribution."""
+        return self._request("GET", "profile", params={"schema": schema, "table": table})
+
+    def profile_ingest(self, body: dict) -> dict:
+        """POST /profile/ingest — upload a data profile collected locally from
+        the client DB optimizer stats. Body: {schema, tables:[{name, num_rows,
+        columns:[{name, num_distinct, num_nulls, null_pct, sample_size,
+        histogram, top_values}]}]}."""
+        return self._request("POST", "profile/ingest", json_data=body)
+
+    def golden(self, schema: str) -> dict:
+        """GET /golden — the schema's GOLDEN entities (canonical/source-of-truth
+        core tables, PL/SQL objects and flows), each with rationale + source
+        (AI/HEURISTIC/MANUAL). The authoritative map to build on."""
+        return self._request("GET", "golden", params={"schema": schema})
+
+    def quality(self, schema: str = None, check: str = None,
+                only_doc: bool = False) -> dict:
+        """GET /quality — open documentation-quality issues for the tenant
+        (optionally a schema). Each issue has check/severity/object/message.
+        only_doc=True narrows to the "uncertain documentation" checks
+        (DOCTAB.DOC_UNCERTAIN / DOCPL.DOC_UNCERTAIN)."""
+        params = {}
+        if schema:
+            params["schema"] = schema
+        if check:
+            params["check"] = check
+        if only_doc:
+            params["only_doc"] = "Y"
+        return self._request("GET", "quality", params=params)
+
+    def quality_scan(self, schema: str) -> dict:
+        """POST /quality/scan — (re)run the quality detectors for a schema and
+        return open-issue counts by check. Cheap; safe to run any time."""
+        return self._request("POST", "quality/scan", params={"schema": schema})
+
+    def golden_classify(self, schema: str, force: bool = False) -> dict:
+        """POST /golden/classify — enqueue the async GOLDEN classification job
+        (heuristic + AI). Server-gated: only runs when the schema is fully
+        documented AND golden is out of date (unless force). Returns
+        {queued, job_id} or {queued: false, message}."""
+        params = {"schema": schema}
+        if force:
+            params["force"] = "Y"
+        return self._request("POST", "golden/classify", params=params)
+
+    def golden_status(self, schema: str, timeout: int = None) -> dict:
+        """GET /golden/status — lightweight signal for the dev nudge:
+        {golden_needed, fully_documented, golden_last_at}."""
+        return self._request("GET", "golden/status", params={"schema": schema},
+                             timeout=timeout)
+
+    # ---- Semantic layer (Phase 6): verified query library ----
+    def semantic_queries(self, schema: str, kind: str = None,
+                         entity: str = None, verified_only: bool = False) -> dict:
+        """GET /semantic/queries — the schema's SEMANTIC query library
+        (metrics, golden queries, rule-checks). Each item: code, kind, name,
+        question, entity, verified, verified_at, rowcount. Use verified queries
+        instead of inventing SQL."""
+        params = {"schema": schema}
+        if kind:
+            params["kind"] = kind
+        if entity:
+            params["entity"] = entity
+        if verified_only:
+            params["verified"] = "Y"
+        return self._request("GET", "semantic/queries", params=params)
+
+    def semantic_query(self, schema: str, code: str) -> dict:
+        """GET /semantic/query — one library entry with the FULL SQL text and
+        last verified sample."""
+        return self._request("GET", "semantic/query",
+                             params={"schema": schema, "code": code})
+
+    def semantic_search(self, schema: str, q: str, k: int = 3) -> dict:
+        """GET /semantic/search — resolve a query by CODE (exact) or by MEANING
+        (natural-language question, via RAG over kind='QUERY'). Returns
+        {match:'code', query} or {match:'semantic', results:[{code, question,
+        entity, verified, distance, sql}]} or {match:'none', note}.
+
+        NB: o param vai como `question` (NÃO `q`) — `q` é reservado pelo ORDS
+        (filtro ?q={JSON}) e derruba a request com 400 (ver server script 216)."""
+        return self._request("GET", "semantic/search",
+                             params={"schema": schema, "question": q, "k": k})
+
+    def semantic_pending(self, schema: str) -> dict:
+        """GET /semantic/pending — library entries not yet verified by
+        execution. `semantic verify` fetches these, runs them read-only against
+        the local DB, and posts the result back."""
+        return self._request("GET", "semantic/pending", params={"schema": schema})
+
+    def semantic_register(self, body: dict) -> dict:
+        """POST /semantic/register — register/upsert a query by (schema, code).
+        Body: {schema, code, kind, name, question, description, grain, entity,
+        sql, result_kind}. Changing the SQL resets its verified flag."""
+        return self._request("POST", "semantic/register", json_data=body)
+
+    def semantic_suggest(self, schema: str, max_n: int = 15) -> dict:
+        """POST /semantic/suggest — ASSÍNCRONO: enfileira um job SEMANTIC_SEED em
+        que a IA propõe métricas/rule-checks das tabelas/CHECKs/colunas de
+        domínio DOCUMENTADAS e grava as NOVAS como não-verificadas (source=AI)
+        para curadoria. Retorna {ok, queued, job_id, message} na hora — a IA roda
+        no drain do servidor (a chamada síncrona estourava o timeout do gateway).
+        As sugestões aparecem quando o job concluir (App 601 › Consultas
+        Semânticas / baucli semantic list)."""
+        return self._request("POST", "semantic/suggest",
+                             params={"schema": schema, "max": max_n})
+
+    def semantic_verify(self, schema: str, code: str, result: dict) -> dict:
+        """POST /semantic/verify — report the outcome of running a query
+        read-only. result: {source, rowcount, ms, sample, error}. error=None
+        marks it verified; a non-null error keeps it unverified."""
+        return self._request("POST", "semantic/verify",
+                             params={"schema": schema, "code": code},
+                             json_data=result)
+
+    def scope(self, code: str) -> dict:
+        """GET /scopes/{code} — a project scope set (BAU_SCOPE_SETS) as JSON:
+        the named object subset a project needs. Used by `sync --scope` to send
+        only the listed objects. Returns {"error": ...} when the code is unknown."""
+        return self._request("GET", f"scopes/{code}")
+
+    def scopes_list(self) -> dict:
+        """GET /scopes — all scope sets of the tenant."""
+        return self._request("GET", "scopes")
+
+    def scope_create(self, code: str, name: str, schema: str,
+                     description: str = None) -> dict:
+        """POST /scopes — create a scope set (schema must be registered)."""
+        body = {"code": code, "name": name, "schema": schema}
+        if description:
+            body["description"] = description
+        return self._request("POST", "scopes", json_data=body)
+
+    def scope_add_item(self, code: str, otype: str, owner: str, name: str,
+                       subprogram: str = None, include_kind: str = None,
+                       note: str = None) -> dict:
+        """POST /scopes/{code}/items — add one object to a scope set."""
+        body = {"type": otype, "owner": owner, "name": name}
+        if subprogram:
+            body["subprogram"] = subprogram
+        if include_kind:
+            body["include_kind"] = include_kind
+        if note:
+            body["note"] = note
+        return self._request("POST", f"scopes/{code}/items", json_data=body)
+
+    def scope_remove_item(self, code: str, item_id: int) -> dict:
+        """DELETE /scopes/{code}/items/{id} — remove one scope item."""
+        return self._request("DELETE", f"scopes/{code}/items/{item_id}")
+
+    def scope_resolve(self, code: str) -> dict:
+        """POST /scopes/{code}/resolve — bind scope items to the synced catalog
+        rows (BAU_SCOPE_ITEMS.*_ID). Returns {ok,linked,total,unresolved}."""
+        return self._request("POST", f"scopes/{code}/resolve", json_data={})
+
+    # ---- DOCMIG (migração de legado -> APEX) --------------------------
+    def docmig_import(self, payload: dict) -> dict:
+        """POST /docmig/import — upsert the legacy-screen inventory (common
+        model: project/screens/blocks/fields/actions/reports). The server
+        resolves blocks/fields to the documented DOCTAB tables/columns."""
+        return self._request("POST", "docmig/import", json_data=payload)
+
+    def docmig_projects(self) -> dict:
+        """GET /docmig/projects — migration projects of the tenant."""
+        return self._request("GET", "docmig/projects")
+
+    def docmig_project(self, code: str) -> dict:
+        """GET /docmig/projects/{code} — project overview + screens/reports."""
+        return self._request("GET", f"docmig/projects/{code}")
+
+    def docmig_screen(self, screen_id: int) -> dict:
+        """GET /docmig/screens/{id} — full screen inventory with DOCTAB
+        bindings (labels, domains, form item types) — the AI blueprint."""
+        return self._request("GET", f"docmig/screens/{screen_id}")
+
+    def docmig_report(self, report_id: int) -> dict:
+        """GET /docmig/reports/{id} — legacy report + columns."""
+        return self._request("GET", f"docmig/reports/{report_id}")
+
+    # ---- DOCAGENT (Advisor de Agentes de IA) --------------------------
+    def agents_list(self) -> dict:
+        """GET /agents — agentes de IA sugeridos do tenant (DOCAGENT)."""
+        return self._request("GET", "agents")
+
+    def agent(self, code: str) -> dict:
+        """Alias of agent_get (kept for the bau_agents MCP tool)."""
+        return self.agent_get(code)
+
+    def agent_get(self, code: str) -> dict:
+        """GET /agents/{code} — um agente sugerido + refs de ancoragem."""
+        return self._request("GET", f"agents/{code}")
+
+    def agents_suggest(self, schema: str, max_agents: int = 6) -> dict:
+        """POST /agents/suggest — enfileira análise assíncrona do negócio de um schema."""
+        return self._request("POST", "agents/suggest",
+                             json_data={"schema": schema, "max": max_agents})
+
+    def agent_approve(self, code: str) -> dict:
+        """POST /agents/{code}/approve — aprova um agente sugerido."""
+        return self._request("POST", f"agents/{code}/approve")
+
+    def impact(self, schema: str, obj: str, direction: str = "DOWN",
+               depth: int = 5, report: bool = False, lang: str = "pt_BR") -> dict:
+        """GET /impact/:schema/:object[/report] — dependency-graph impact analysis.
+
+        report=False → grafo JSON (conjunto impactado); report=True → laudo de
+        negócio gerado por IA (Markdown, dentro de {"report": ...}).
+        """
+        path = f"impact/{schema}/{obj}" + ("/report" if report else "")
+        params = {"dir": direction, "depth": depth}
+        if report:
+            params["lang"] = lang
+        # O laudo (/report) faz uma chamada de IA síncrona no servidor — pode
+        # passar dos 30s default. Piso maior só para o report; o grafo é rápido.
+        return self._request("GET", path, params=params,
+                             timeout=(max(self.timeout, 180) if report else None))
+
+    def impact_report_queue(self, schema: str, obj: str, direction: str = "DOWN",
+                            depth: int = 5, lang: str = "pt_BR") -> dict:
+        """POST /impact/:schema/:object/report/queue — enfileira um job
+        assíncrono que gera o laudo de impacto por IA e persiste em BAU_REPORTS
+        (IMPACT/HTML). Retorna {queued, job_id, message}. O resultado aparece em
+        App 601 › Análise de Impacto (p71) / Relatórios. Substitui a chamada
+        síncrona que estourava o timeout do gateway."""
+        return self._request("POST", f"impact/{schema}/{obj}/report/queue",
+                             params={"dir": direction, "depth": depth, "lang": lang})
+
+    def audit_enqueue(self, schema: str, tables: str = None, schedule: str = None,
+                      provider_id: int = None, reason: str = None) -> dict:
+        """POST /audit — enfileira o DA virtual (auditoria de modelagem por IA)
+        como job assíncrono e volta NA HORA. Audita o schema inteiro ou só
+        `tables` (CSV). Cada achado sério vira uma proposta no App 601 (validada
+        pelo write-loop). Retorna {ok, job_id, enqueued, status:'QUEUED',
+        custo_ia_est}. Acompanhe com audit_status / audit_findings."""
+        body = {"schema": schema}
+        if tables:      body["tables"] = tables
+        if schedule:    body["schedule"] = schedule
+        if provider_id: body["provider_id"] = provider_id
+        if reason:      body["reason"] = reason
+        return self._request("POST", "audit", json_data=body)
+
+    def audit_status(self, job_id: int) -> dict:
+        """GET /audit/{job}/status — progresso do run (itens_total/feitos/falha,
+        propostas_geradas, iniciado/concluido_em, status QUEUED|RUNNING|DONE|FAILED)."""
+        return self._request("GET", f"audit/{int(job_id)}/status")
+
+    def audit_findings(self, job_id: int) -> dict:
+        """GET /audit/{job}/findings — as propostas geradas pelo run (App 601):
+        proposal_id, tabela, coluna, severidade, categoria, achado, action,
+        suggested_ddl, verdict."""
+        return self._request("GET", f"audit/{int(job_id)}/findings")
+
+    def flows_list(self, schema: str) -> dict:
+        """GET /flows/{schema} — index of structured business flows (DOCFLOW)."""
+        return self._request("GET", f"flows/{schema}")
+
+    def flow(self, schema: str, obj: str, subprogram: str = None,
+             include_draft: bool = False) -> dict:
+        """GET /flows/{schema}/{object} — structured business flow JSON
+        (steps / refs / rules). Only DOCUMENTED unless include_draft."""
+        params = {}
+        if subprogram:
+            params["subprogram"] = subprogram
+        if include_draft:
+            params["draft"] = "Y"
+        return self._request("GET", f"flows/{schema}/{obj}", params=params or None)
+
+    def rag_index(self, schema: str) -> dict:
+        """POST /rag/index/{schema} — refresh chunks + embed IN-DB (server-side,
+        via VECTOR_EMBEDDING). Sem cálculo na borda. Retorna {chunks, embedded,
+        pending, model, ok}. Long server-side embed: floor the timeout at 300s
+        so a low configured default doesn't kill the call."""
+        return self._request("POST", f"rag/index/{schema}", json_data={},
+                             timeout=max(self.timeout, 300))
+
+    def rag_search(self, schema: str, query: str, top_k: int = 8) -> dict:
+        """POST /rag/search/{schema} — busca semântica por TEXTO; o servidor
+        embeda a pergunta IN-DB e devolve top-k chunks do catálogo aprovado."""
+        return self._request("POST", f"rag/search/{schema}",
+                             json_data={"query": query, "top_k": top_k})
+
+    def docs_system(self, application_id: int, audience: str = "USER",
+                    fmt: str = "HTML", language: str = "pt_BR") -> dict:
+        """POST /docs/system — generate the System Documentation for an APEX app
+        and stream it back. Returns {content: bytes, report_id, content_type}.
+
+        Deterministic composer (no AI): reuses the approved DOCFLOW/DOCTAB/DOCPL
+        catalog. audience USER=user manual, TECH=+field tables & data model.
+        format HTML or DOCX (Word-compatible)."""
+        url = f"{self.api_url}/docs/system"
+        try:
+            resp = self.session.request(
+                "POST", url,
+                json={"application_id": application_id, "audience": audience,
+                      "format": fmt, "language": language},
+                timeout=max(self.timeout, 120),
+            )
+        except requests.ConnectionError:
+            raise BauApiError(f"Cannot connect to BAU Server at {self.api_url}")
+        except requests.Timeout:
+            raise BauApiError(f"Request timeout to {url}")
+        if resp.status_code == 401:
+            raise BauApiError("Unauthorized", 401)
+        if resp.status_code == 404:
+            raise BauApiError("Aplicação não encontrada no BAU (rode 'baucli apex sync' antes)", 404)
+        if resp.status_code >= 400:
+            raise BauApiError(f"Server error {resp.status_code}", resp.status_code)
+        return {
+            "content": resp.content,
+            "report_id": resp.headers.get("X-Bau-Report-Id"),
+            "content_type": resp.headers.get("Content-Type", ""),
+        }
+
+    def ai_limits(self) -> dict:
+        """GET /limits — per-analyst AI limits of the tenant + live month usage.
+
+        Read-only oversight (management is done in App 601). Returns
+        {"status":"ok","text": <json array>} or the parsed list."""
+        return self._request("GET", "limits")
+
+    def sync_status(self, schema: str) -> dict:
+        """GET /sync/status?schema=X — Get sync recommendation."""
+        return self._request("GET", "sync/status", params={"schema": schema})
+
+    def sync_batch(self, schema: str, db_engine: str, objects: list,
+                   db_version: str = None,
+                   overwrite_undocumented: bool = False,
+                   dependencies: list = None,
+                   sequences: list = None,
+                   db_name: str = None) -> dict:
+        """POST /sync/batch — Send objects to BAU Server.
+
+        dependencies: array de deps do dicionario (grafo). Enviado numa chamada
+        dedicada (objects=[]); o servidor faz replace por schema em BAU_DEP_RAW.
+        db_name: nome do database registrado. Enviado para que um tenant com
+        MAIS DE UM database ativo resolva sem ambiguidade (senao o servidor
+        levanta ORA-20453 ao auto-selecionar).
+        """
+        payload = {
+            "schema": schema,
+            "db_engine": db_engine,
+            "objects": objects,
+        }
+        if db_version:
+            payload["db_version"] = db_version
+        if overwrite_undocumented:
+            payload["overwrite_undocumented"] = "Y"
+        if dependencies is not None:
+            payload["dependencies"] = dependencies
+        if sequences is not None:
+            payload["sequences"] = sequences
+        if db_name:
+            payload["db_name"] = db_name
+        return self._request("POST", "sync/batch", json_data=payload)
+
+    def source_upload(self, schema: str, name: str, obj_type: str,
+                      source: str, db_engine: str = "ORACLE") -> dict:
+        """POST /source/upload — Upload single object source."""
+        return self._request("POST", "source/upload", json_data={
+            "schema": schema, "name": name, "type": obj_type,
+            "source": source, "db_engine": db_engine,
+        })
+
+    def get_source(self, schema: str, name: str) -> dict:
+        """GET /source/{schema}/{name} — Get current source."""
+        return self._request("GET", f"source/{schema}/{name}")
+
+    def get_source_hashes(self, schema: str) -> dict:
+        """GET /source/hashes/{schema} — Current source hash per object (drift)."""
+        return self._request("GET", f"source/hashes/{schema}")
+
+    def get_source_history(self, schema: str, name: str) -> dict:
+        """GET /source/history/{schema}/{name} — All source revisions for one object."""
+        return self._request("GET", f"source/history/{schema}/{name}")
+
+    def get_table_hashes(self, schema: str) -> dict:
+        """GET /tables/hashes/{schema} — Canonical column signature hash per table (drift)."""
+        return self._request("GET", f"tables/hashes/{schema}")
+
+    def get_table_columns_diff(self, schema: str, table: str) -> dict:
+        """GET /tables/columns/{schema}/{table} — Column list shaped for per-column diff."""
+        return self._request("GET", f"tables/columns/{schema}/{table}")
+
+    def get_columns_ui(self, schema: str, table: str) -> dict:
+        """GET /columns/{schema}/{table} — Rich UI metadata used by `apex-rebuild`.
+
+        Returns {"columns": [...]} where each entry carries label, align_form,
+        align_report, format_mask, text_case, hidden, read_only, show_in_forms,
+        show_in_reports, *_display_order, lov_display_order, description,
+        form_item_type (exact APEXlang token, e.g. "checkbox"/"selectList") and
+        domain_values ([{value,label}, ...] from the column's CHECK constraint)
+        — the last two let `apex-rebuild` retype an item and synthesize its
+        static LOV / single-checkbox checked&unchecked values from the domain.
+        """
+        return self._request("GET", f"columns/{schema}/{table}")
+
+    def objects_changed(self, days: int = 30, schema_name: str = None) -> dict:
+        """GET /objects/changed — Modified objects."""
+        params = {"days": days}
+        if schema_name:
+            params["schema_name"] = schema_name
+        return self._request("GET", "objects/changed", params=params)
+
+    def deploys_pending(self, schema: str = None, status: str = None) -> dict:
+        """GET /deploys/pending — Pending deploy queue."""
+        params = {}
+        if schema:
+            params["schema"] = schema
+        if status:
+            params["status"] = status
+        query = "&".join(f"{k}={v}" for k, v in params.items())
+        endpoint = "deploys/pending"
+        if query:
+            endpoint += "?" + query
+        return self._request("GET", endpoint)
+
+    def deploy_review(self, deploy_id: int, action: str,
+                      reviewer: str = None, notes: str = None) -> dict:
+        """POST /deploys/{id}/review — Approve or reject."""
+        payload = {"action": action}
+        if reviewer:
+            payload["reviewer"] = reviewer
+        if notes:
+            payload["notes"] = notes
+        return self._request("POST", f"deploys/{deploy_id}/review", json_data=payload)
+
+    def deploy_script(self, deploy_id: int) -> dict:
+        """GET /deploys/{id}/script — Download DDL script."""
+        return self._request("GET", f"deploys/{deploy_id}/script")
+
+    def deploy_confirm(self, deploy_id: int, success: bool, error: str = None) -> dict:
+        """POST /deploys/{id}/confirm — Mark deploy APPLIED or FAILED after local execution."""
+        payload = {"success": "Y" if success else "N"}
+        if error:
+            payload["error"] = error[:4000]
+        return self._request("POST", f"deploys/{deploy_id}/confirm", json_data=payload)
+
+    # ── DOCTAB deploy queue (ANNOTATIONS / COMMENT ON per table) ──────────
+    def doctab_deploys_pending(self, schema: str = None, status: str = None,
+                              limit: int = 100) -> dict:
+        """GET /doctab/deploys/pending — Pending DOCTAB deploys."""
+        params = {"p_limit": limit}
+        if schema:
+            params["schema"] = schema
+        if status:
+            params["status"] = status
+        return self._request("GET", "doctab/deploys/pending", params=params)
+
+    def doctab_deploy_script(self, deploy_id: int) -> dict:
+        """GET /doctab/deploys/{id}/script — Download DOCTAB DDL script."""
+        return self._request("GET", f"doctab/deploys/{deploy_id}/script")
+
+    def doctab_deploy_preview(self, deploy_id: int) -> dict:
+        """GET /doctab/deploys/{id}/preview — Preview DOCTAB deploy metadata."""
+        return self._request("GET", f"doctab/deploys/{deploy_id}/preview")
+
+    def doctab_deploy_confirm(self, deploy_id: int, success: bool,
+                             error: str = None) -> dict:
+        """POST /doctab/deploys/{id}/confirm — Mark DOCTAB deploy APPLIED or FAILED."""
+        payload = {"success": "Y" if success else "N"}
+        if error:
+            payload["error"] = error[:4000]
+        return self._request("POST", f"doctab/deploys/{deploy_id}/confirm",
+                            json_data=payload)
+
+    def deploy_preview(self, deploy_id: int) -> dict:
+        """GET /deploys/{id}/preview — Preview header and metadata."""
+        return self._request("GET", f"deploys/{deploy_id}/preview")
+
+    def doctab_get_script(self, schema_name: str) -> dict:
+        """GET /doctab/script/{schema_name} — Full COMMENT ON DDL script."""
+        return self._request("GET", f"doctab/script/{schema_name}")
+
+    def annotations_get_table(self, schema: str, table: str) -> dict:
+        """GET /annotations/{schema}/{table}/script — Oracle 23ai+ DDL for one table."""
+        return self._request("GET", f"annotations/{schema}/{table}/script")
+
+    def annotations_get_file(self, schema: str) -> dict:
+        """GET /annotations/{schema}/file — Oracle 23ai+ DDL for every table in the schema."""
+        return self._request("GET", f"annotations/{schema}/file")
+
+    def get_ui_kit(self, schema: str, engine: str = "ORACLE",
+                   language: str = "EN", only: str = None) -> str:
+        """GET /ui-kit/{schema} — UI Kit bundle (domains + errors + APEX handler).
+
+        Returns the script as plain text. `only` accepts a CSV combo of
+        DOMAINS, ERRORS, HANDLER (None or empty = all three).
+        """
+        params = {"engine": engine, "lang": language}
+        if only:
+            params["only"] = only
+        result = self._request("GET", f"ui-kit/{schema}", params=params)
+        return result.get("text", "") if isinstance(result, dict) else str(result)
+
+    def context_languages(self, schema: str) -> dict:
+        """GET /context/{schema}/languages — JSON {primary, languages[]} for a schema.
+
+        Drives the bilingual decision in `bau context`: when len(languages) > 1
+        and the user didn't pin a single `--language`, the agent fetches one
+        context per language and writes a file per locale.
+        """
+        return self._request("GET", f"context/{schema}/languages")
+
+    def viewer_list(self, schema: str, status: str = None, obj_type: str = None) -> dict:
+        """GET /viewer/{schema} — List objects + tables for viewer."""
+        params = {}
+        if status:
+            params["status"] = status
+        if obj_type:
+            params["type"] = obj_type
+        query = "&".join(f"{k}={v}" for k, v in params.items())
+        endpoint = f"viewer/{schema}"
+        if query:
+            endpoint += "?" + query
+        return self._request("GET", endpoint)
+
+    def viewer_detail(self, category: str, item_id: int, language: str = None) -> dict:
+        """GET /viewer/detail/{OBJ|TBL}/{id} — Full documentation detail.
+
+        When `language` is set (e.g. 'pt_BR'), the server replaces EN canonical
+        text (purpose, description, prompt, business_domain) with the matching
+        translation from BAU_DOCTRANSLATE_VALUES. Falls back to EN when no
+        translation exists.
+        """
+        params = {"language": language} if language else None
+        return self._request("GET", f"viewer/detail/{category}/{item_id}", params=params)
+
+    def get_context(self, schema: str, language: str = "EN",
+                    tables: str = None, objects: str = None,
+                    scope: str = None) -> dict:
+        """GET /context/{schema} — AI context markdown.
+
+        `tables` and `objects` are optional comma-separated names that
+        narrow the markdown to just those tables / PL/SQL objects. When
+        both are NULL the full schema context is returned (legacy behavior).
+        """
+        params = {"language": language}
+        if tables:
+            params["tables"] = tables
+        if objects:
+            params["objects"] = objects
+        if scope:
+            params["scope"] = scope  # 'preamble' = business context only
+        return self._request("GET", f"context/{schema}", params=params)
+
+    def database_register(self, db_name: str, db_engine: str,
+                          db_version: str = None, host: str = None,
+                          port: int = None, native_identifier: str = None) -> dict:
+        """POST /database/register — Register database UUID."""
+        payload = {"db_name": db_name, "db_engine": db_engine}
+        if db_version:
+            payload["db_version"] = db_version
+        if host:
+            payload["host"] = host
+        if port:
+            payload["port"] = port
+        if native_identifier:
+            payload["native_identifier"] = native_identifier
+        return self._request("POST", "database/register", json_data=payload)
+
+    def database_validate(self, bau_database_uuid: str) -> dict:
+        """POST /database/validate — Validate database fingerprint."""
+        return self._request("POST", "database/validate",
+                             json_data={"bau_database_uuid": bau_database_uuid})
+
+    def get_quota(self) -> dict:
+        """GET /quota — Full quota status."""
+        return self._request("GET", "quota")
+
+    # ── DOCAPEX endpoints ──
+
+    def apex_sync(self, payload: dict) -> dict:
+        """POST /apex/sync — Send full APEX app snapshot to the server.
+
+        `payload` must follow the SYNC_APEX_APP contract: {schema, app, pages,
+        regions, items, proc, da}. Use OracleExtractor.extract_apex to build it.
+        """
+        return self._request("POST", "apex/sync", json_data=payload)
+
+    def apex_hashes(self, schema: str, application_id: int) -> dict:
+        """GET /apex/hashes/{schema}/{app_id} — Per-row HASH_CURRENT for drift."""
+        return self._request("GET", f"apex/hashes/{schema}/{application_id}")
+
+    def apex_screenshot_plan(self, schema: str, application_id: int) -> dict:
+        """GET /apex/screenshot-plan/{schema}/{app} — capture recipe per modal.
+
+        Returns {"status":"ok","modals":[{page_id, launch_page, launch_items,
+        launch_selector, dialog_selector, wait_ms}, ...]} documented by the
+        analyst in App 601 (p42). Used to open modal pages deterministically.
+        """
+        return self._request(
+            "GET", f"apex/screenshot-plan/{schema}/{application_id}")
+
+    def apex_upload_screenshot(self, application_id: int, page_no: int,
+                               image_bytes: bytes,
+                               mime: str = "image/png") -> dict:
+        """POST /apex/apps/{app}/pages/{page_no}/screenshot — raw image bytes.
+
+        Uploads a page screenshot by NATURAL KEY (APEX app id + page number);
+        the server resolves the BAU_DOCAPEX_PAGES row and routes to DB or the
+        OCI bucket per config. `image_bytes` is the raw PNG/JPEG/WEBP content.
+        """
+        url = (f"{self.api_url}/apex/apps/{application_id}"
+               f"/pages/{page_no}/screenshot")
+        try:
+            resp = self.session.request(
+                "POST", url, data=image_bytes,
+                headers={"Content-Type": mime},
+                timeout=max(self.timeout, 60),
+            )
+        except requests.ConnectionError:
+            raise BauApiError(f"Cannot connect to BAU Server at {self.api_url}")
+        except requests.Timeout:
+            raise BauApiError(f"Request timeout ({max(self.timeout, 60)}s) to {url}")
+
+        data = self._parse_body(resp)
+        if resp.status_code == 401:
+            msg = (data or {}).get("message", "Unauthorized") if isinstance(data, dict) else "Unauthorized"
+            if msg in SESSION_ERROR_TAGS:
+                raise BauSessionError(msg, 401, data or {})
+            raise BauApiError(msg, 401, data or {})
+        if isinstance(data, dict) and data.get("status") == "error":
+            raise BauApiError(data.get("message", "Unknown error"),
+                              resp.status_code, data)
+        if data is None:
+            return {"status": "ok", "text": resp.text}
+        return data
+
+    def apex_ai_generate(self, level: str, row_id: int,
+                         provider_id: int = None) -> dict:
+        """POST /apex/ai/generate/{level}/{id} — Trigger AI doc generation.
+
+        level: APP | PAGE | REGION | ITEM | PROC | DA
+        """
+        body = {}
+        if provider_id is not None:
+            body["provider_id"] = provider_id
+        return self._request("POST", f"apex/ai/generate/{level}/{row_id}",
+                             json_data=body)
+
+    def apex_ai_approve(self, level: str, row_id: int,
+                        approver: str = None) -> dict:
+        """POST /apex/ai/approve/{level}/{id} — Approve AI draft."""
+        body = {}
+        if approver:
+            body["approver"] = approver
+        return self._request("POST", f"apex/ai/approve/{level}/{row_id}",
+                             json_data=body)
+
+    # ── Session auth (Bearer required, session NOT required) ──
+
+    def auth_login(self, email: str, password: str) -> dict:
+        """POST /auth/login — Exchange email+password for a session token."""
+        return self._request("POST", "auth/login",
+                             json_data={"email": email, "password": password})
+
+    def auth_logout(self) -> dict:
+        """POST /auth/logout — Revoke the active session (X-Bau-Session header)."""
+        return self._request("POST", "auth/logout")