PDFagendid/firecrawl/pdfskilll.mdown

Faili loomine siinsesse sandboxi ebaõnnestus runtime permission vea tõttu, seega annan sulle **valmis `.md` loomise käsu**, mis teeb faili otse sinu arvutisse.

Allikasena kasutasin siinse vestluse käivituse/backendi logisid: ATOM root `npm run dev`, backend `venv`, `main_api_app.py`, `/clients`, `4490 workflow service`, `8000 backend` ja puuduvad route’id.   

## PowerShell — loo `.md` fail

Kopeeri see PowerShelli:

````powershell
$path = "I:\Devdrive\PDFEDITOR\ATOM\ATOM\atom\ANNATOR_ATOM_BUILDER_HANDOFF.md"

@'
# ANNATOR / ATOM — PDF Editor LLM Orchestrator Handoff

Kuupäev: 2026-07-02  
Projekt: Annator / ATOM / PDF Editor Orkester  
Eesmärk: panna PDF editor tööle LLM-orchestratorina: PDF sisse → LLM planeerib → agendid teevad OCR/edit/validate/export → haldur kinnitab → tulemus salvestatakse.

---

## 1. Praegune seis

| Komponent | Port / URL | Seis |
|---|---:|---|
| Annator frontend / Next.js | http://localhost:3000 | töötab |
| ATOM backend / Uvicorn | http://127.0.0.1:8000 | töötab |
| Workflow mock service | http://127.0.0.1:4490 | töötab |
| OpenClaw gateway | http://127.0.0.1:18789 | töötab |
| Ollama | http://127.0.0.1:11434 | töötab |
| WSL Ubuntu | WSL2 | töötab |

Vestluses lahendatud:
- OpenClaw auth/token probleem.
- Annator frontend käivitus `npm run dev`.
- Backend `.venv` oli katki, kasutada tuleb `backend\venv`.
- Backend käivitus `main_api_app:app` kaudu.
- `/clients` 404 parandati shim route’iga.
- `/healthz`, `/api/autoflow/*`, `/api/skills/list`, `/api/workflows/*` lisati dev shimidega.
- Workflow builder ootas porti `4490`, lisati `annator_workflow_4490.py`.

---

## 2. Käivitusjuhend

### Terminal 1 — frontend

```powershell
cd "I:\Devdrive\PDFEDITOR\ATOM\ATOM\atom"
npm run dev
````

Oodatav:

```text
Local: http://localhost:3000
Ready
```

### Terminal 2 — backend

```powershell
cd "I:\Devdrive\PDFEDITOR\ATOM\ATOM\atom\backend"
$env:PYTHONPATH="I:\Devdrive\PDFEDITOR\ATOM\ATOM\atom;I:\Devdrive\PDFEDITOR\ATOM\ATOM\atom\backend"
.\venv\Scripts\python.exe -m uvicorn main_api_app:app --host 127.0.0.1 --port 8000 --reload
```

Oodatav:

```text
Uvicorn running on http://127.0.0.1:8000
Application startup complete
```

### Terminal 3 — workflow service 4490

```powershell
cd "I:\Devdrive\PDFEDITOR\ATOM\ATOM\atom"
.\backend\venv\Scripts\python.exe ".\annator_workflow_4490.py"
```

Oodatav:

```text
ANNATOR workflow mock service running on http://127.0.0.1:4490
```

### Kontroll

```powershell
Invoke-RestMethod "http://127.0.0.1:8000/clients"
Invoke-RestMethod "http://127.0.0.1:8000/healthz"
Invoke-RestMethod "http://127.0.0.1:8000/api/autoflow/health"
Invoke-RestMethod "http://127.0.0.1:4490/api/workflow-templates"
Invoke-RestMethod "http://127.0.0.1:3000/api/workflow-templates"
```

Kui `4490` vastab, aga `3000/api/workflow-templates` annab `500`, on probleem Next proxy või Next API route’is.

---

## 3. Builderite missioon

Ehita Annator/ATOM PDF Editorist päris LLM-orchestrator, mitte ainult mock UI.

Lõppvoog:

```text
PDF upload / olemasolev PDF
    ↓
PDF loader
    ↓
OCR Agent
    ↓
Annotator Agent
    ↓
Editor Agent
    ↓
Validator Agent
    ↓
Approval Gate
    ↓
Exporter Agent
    ↓
Final PDF + audit trail + events
```

Turvareegel:

```text
plan_only → preview_diff → approval_required → approved → execute → export
```

Mitte ükski agent ei tohi lõplikult PDF-i muuta enne halduri kinnitust.

---

## 4. Tech stack

| Kiht           | Valik                                                   |
| -------------- | ------------------------------------------------------- |
| Backend        | olemasolev ATOM FastAPI või Node.js + TypeScript moodul |
| Frontend       | olemasolev Next.js / React + TypeScript                 |
| PDF render     | pdf.js                                                  |
| PDF write/edit | pdf-lib                                                 |
| OCR            | Tesseract.js MVP või serveripoolne Tesseract            |
| Eventid        | WebSocket                                               |
| LLM            | Ollama local first                                      |
| Orchestrator   | workflowEngine + event bus                              |
| Approval       | kohustuslik enne execute/export                         |

Soovitus:

* A-variant: jätka olemasolevas ATOM/Next/FastAPI struktuuris ja asenda shimid päris route’idega.
* B-variant: tee hiljem eraldi `annator-pdf-orchestrator` Node/TS teenus.

---

## 5. Kohustuslikud API endpointid

Need peavad vastama, et UI ei kukuks:

```text
GET  /clients
GET  /healthz
GET  /api/healthz

GET  /api/autoflow/health
GET  /api/autoflow/providers
POST /api/autoflow/plan
POST /api/autoflow/execute_mock

GET  /api/skills/list

GET  /api/workflows
POST /api/workflows
GET  /api/workflows/definitions
GET  /api/workflows/templates
GET  /api/workflows/executions
POST /api/workflows/executions
GET  /api/workflows/services

GET  /api/workflow-templates

GET  /api/services
GET  /api/integrations
GET  /api/agents
GET  /api/tables
GET  /api/versions

POST /workflow/approve
POST /workflow/rollback
```

---

## 6. Agent contract

```ts
export interface AgentContext {
  docId: string;
  version: number;
  payload: Record<string, unknown>;
  userId?: string;
  mode: "plan_only" | "execute_mock" | "execute_real";
}

export interface AgentEvent {
  id: string;
  docId: string;
  agent: string;
  type:
    | "OCR_COMPLETED"
    | "ANNOTATION_SUGGESTED"
    | "EDIT_APPLIED"
    | "VALIDATION_WARNING"
    | "APPROVAL_REQUIRED"
    | "EXPORT_READY"
    | "ERROR";
  message: string;
  payload?: unknown;
  timestamp: string;
}

export interface AgentResult {
  docId: string;
  version: number;
  nextVersion?: number;
  changes?: unknown;
  summary: string;
  events: AgentEvent[];
}

export interface Agent {
  name: string;
  run(ctx: AgentContext): Promise<AgentResult>;
}
```

---

## 7. Workflow engine skeleton

```ts
import { ocrAgent } from "../agents/ocrAgent";
import { annotatorAgent } from "../agents/annotatorAgent";
import { editorAgent } from "../agents/editorAgent";
import { validatorAgent } from "../agents/validatorAgent";
import { exporterAgent } from "../agents/exporterAgent";
import { publishEvents } from "../events/eventBus";
import type { AgentContext, AgentResult } from "../agents/types";

export async function runWorkflow(docId: string, mode: AgentContext["mode"] = "plan_only") {
  const ctxBase: AgentContext = { docId, version: 1, payload: {}, mode };

  const ocrRes = await ocrAgent.run(ctxBase);
  publishEvents(ocrRes.events);

  const annRes = await annotatorAgent.run({
    ...ctxBase,
    version: ocrRes.nextVersion ?? ctxBase.version,
    payload: ocrRes.changes as Record<string, unknown>,
  });
  publishEvents(annRes.events);

  const editRes = await editorAgent.run({
    ...ctxBase,
    version: annRes.nextVersion ?? annRes.version,
    payload: annRes.changes as Record<string, unknown>,
  });
  publishEvents(editRes.events);

  const valRes = await validatorAgent.run({
    ...ctxBase,
    version: editRes.nextVersion ?? editRes.version,
    payload: editRes.changes as Record<string, unknown>,
  });
  publishEvents(valRes.events);

  if (mode !== "execute_real") {
    const approval: AgentResult = {
      docId,
      version: valRes.nextVersion ?? valRes.version,
      summary: "Workflow paused before export. Approval required.",
      events: [
        {
          id: crypto.randomUUID(),
          docId,
          agent: "approval-gate",
          type: "APPROVAL_REQUIRED",
          message: "Halduri kinnitus on vajalik enne lõplikku PDF eksporti.",
          timestamp: new Date().toISOString(),
        },
      ],
    };
    publishEvents(approval.events);
    return approval;
  }

  const expRes = await exporterAgent.run({
    ...ctxBase,
    version: valRes.nextVersion ?? valRes.version,
    payload: valRes.changes as Record<string, unknown>,
  });
  publishEvents(expRes.events);

  return expRes;
}
```

---

## 8. Event bus MVP

```ts
import WebSocket, { WebSocketServer } from "ws";
import type { AgentEvent } from "./eventTypes";

const wss = new WebSocketServer({ port: 8081 });
const clients = new Set<WebSocket>();

wss.on("connection", (ws) => {
  clients.add(ws);
  ws.on("close", () => clients.delete(ws));
});

export function publishEvents(events: AgentEvent[]) {
  const data = JSON.stringify(events);
  for (const ws of clients) {
    if (ws.readyState === WebSocket.OPEN) ws.send(data);
  }
}
```

---

## 9. Builderite TODO

### Phase 1 — Stabiliseeri olemasolev Annator UI

1. Eemalda ajutised `Add-Content` shimid `main_api_app.py` lõpust ja vii need päris route failidesse.
2. Loo:

   * `backend/api/clients_routes.py`
   * `backend/api/autoflow_routes.py`
   * `backend/api/skills_routes.py`
   * `backend/api/workflow_routes.py`
3. Registreeri:

   ```py
   app.include_router(...)
   ```
4. Tee stabiilseks:

   * `GET /healthz`
   * `GET /api/skills/list`
   * `GET /api/workflow-templates`
5. Kaota vajadus `annator_workflow_4490.py` järele või tee sellest päris workflow service.

Acceptance:

```powershell
Invoke-RestMethod "http://127.0.0.1:8000/healthz"
Invoke-RestMethod "http://127.0.0.1:8000/api/skills/list"
Invoke-RestMethod "http://127.0.0.1:8000/api/autoflow/health"
Invoke-RestMethod "http://127.0.0.1:8000/api/workflow-templates"
```

Kõik peavad andma `ok True`.

### Phase 2 — PDF toolchain

1. `pdfLoader`

   * loeb PDF faili
   * teeb `docId`
   * salvestab originaali
   * teeb version `1`

2. `pdfOCR`

   * OCR tekstikiht
   * bounding boxes
   * lehekülje kaupa JSON

3. `pdfDiff`

   * orig text vs proposed text
   * page-level diff
   * visual diff metadata

4. `pdfWriter`

   * kirjutab uue PDF versiooni
   * ei overwrite’i originaali
   * salvestab:

     ```text
     documents/{docId}/versions/v2.pdf
     documents/{docId}/audit.jsonl
     ```

### Phase 3 — agendid

* `ocrAgent`
* `annotatorAgent`
* `editorAgent`
* `validatorAgent`
* `exporterAgent`
* `approvalGate`

Iga agent tagastab `AgentResult` ja saadab `AgentEvent[]`.

### Phase 4 — UI

* `PdfCanvas`
* `SidePane`
* `DiffView`
* `Approve / Rollback`
* `WorkflowBuilder`

### Phase 5 — Ollama / LLM

Kontroll:

```powershell
Invoke-RestMethod "http://127.0.0.1:11434/api/tags"
```

Lisa:

```text
POST /api/llm/plan
POST /api/llm/validate
```

LLM võib ainult planeerida, pakkuda muudatusi ja hinnata riske. LLM ei tohi otse PDF-i muuta.

---

## 10. Builder prompt — copy/paste

```text
You are the build agent for Annator / ATOM PDF Editor LLM Orchestrator.

Mission:
Turn the current Annator/ATOM PDF Editor UI into a working local LLM-orchestrated PDF workflow system.

Current system:
- Frontend: Next.js running on http://localhost:3000
- Backend: FastAPI/Uvicorn running on http://127.0.0.1:8000
- Workflow mock service currently runs on http://127.0.0.1:4490
- Ollama local LLM is available on http://127.0.0.1:11434
- OpenClaw Gateway is available on http://127.0.0.1:18789

Rules:
1. Do not break the current running UI.
2. Do not remove current fallback/mock routes until real routes are verified.
3. No PDF destructive write without approval.
4. All agent actions must emit events.
5. Every document change must create a new version.
6. Every workflow must support plan_only first.
7. Real execution requires approval.

Immediate tasks:
1. Stabilize these routes in the backend:
   - GET /clients
   - GET /healthz
   - GET /api/autoflow/health
   - GET /api/autoflow/providers
   - POST /api/autoflow/plan
   - POST /api/autoflow/execute_mock
   - GET /api/skills/list
   - GET /api/workflows
   - GET /api/workflows/definitions
   - GET /api/workflows/templates
   - GET /api/workflows/executions
   - GET /api/workflows/services
   - GET /api/workflow-templates

2. Replace temporary shims with real route modules.
3. Implement AgentContext, AgentResult, AgentEvent and Agent interface.
4. Implement ocrAgent, annotatorAgent, editorAgent, validatorAgent, exporterAgent, approvalGate.
5. Implement workflowEngine with plan_only, execute_mock and execute_real behind approval.
6. Implement WebSocket event bus on port 8081.
7. Implement PdfCanvas, SidePane, DiffView, Approve/Rollback buttons.

Acceptance tests:
- http://localhost:3000 opens Annator UI
- Automatsioonid page loads workflow templates without Internal Server Error
- PDF Editor page shows Autoflow online and 3 providers ready
- Generate plan returns structured steps
- No real PDF modification happens before approval
- /healthz returns ok true
- /api/skills/list returns PDF OCR, PDF Editor, PDF Redaction, Bank Statement Reader, LLM Orchestrator
- /api/workflow-templates returns PDF Editor LLM Orchestrator template
```

---

## 11. Järgmine konkreetne arendussamm

Tee päris fail:

```text
backend/api/annator_workflow_routes.py
```

Tõsta sinna kõik praegused shimid:

* `/healthz`
* `/clients`
* `/api/skills/list`
* `/api/autoflow/*`
* `/api/workflows/*`
* `/api/workflow-templates`

Siis `main_api_app.py` lõppu ainult:

```py
from api.annator_workflow_routes import router as annator_router
app.include_router(annator_router)
```

Pärast seda eemaldada ajutised `Add-Content` blokid `main_api_app.py` lõpust.

---

## 12. Lõppkokkuvõte

Praegu pole eesmärk ilus kood.
Eesmärk:

```text
Annator UI ei tohi enam punast näidata.
Workflow templates peavad laadima.
PDF Editor Autoflow peab näitama online.
Generate plan peab andma structured plan.
Päris PDF muutmine tuleb alles pärast approval gate’i.
```

Kui see on stabiilne, siis alles ühendada päris PDF/OCR/LLM execution.
'@ | Set-Content -Encoding UTF8 $path

Write-Host "Created: $path"

````

See loob faili:

```text
I:\Devdrive\PDFEDITOR\ATOM\ATOM\atom\ANNATOR_ATOM_BUILDER_HANDOFF.md
````