Readme

PLSQL Insight, a private, evidence-grounded application for understanding Oracle PL/SQL, has been released as a React 19 edition. The application, built by a developer, integrates FastAPI, LangGraph, Ollama, Oracle, Chroma, and a lexical parser to analyze PL/SQL code without compiling or executing it. It features Analyst and Admin modes, with the React frontend being stateless and all persistent data managed in the backend.

PLSQL Insight is a private, evidence-grounded application for understanding Oracle PL/SQL. This repository is the React edition: a modern React 19 interface over the existing FastAPI, LangGraph, Ollama, Oracle, Chroma, parser, retrieval, and auditing implementation. It accepts pasted source, uploaded .sql / .pkb / .pks / .txt files, approved lower-environment Oracle objects, optional supporting documents, and bulk Oracle ingestion. Submitted PL/SQL is never compiled or executed. This project does not use Streamlit, Spring, Docker, or a frontend database. php flowchart LR UI React 19 + TypeScript -- API FastAPI API -- G Typed LangGraph workflow G -- P Lexical parser + deterministic facts G -- R Exact + Chroma semantic retrieval G -- Q Qwen analysis agents G -- D DeepSeek audit + merge P -- M Oracle metadata schema or optional local SQLite R -- M R -- C Persistent Chroma Q -- O Ollama / internal model endpoint D -- O The React application is stateless. Analyst submissions and results remain transient. Durable knowledge, reviews, feedback, Oracle ingestion, and dependency edges remain behind repository interfaces in the backend and are available only in Admin mode. The application has two deliberately simple access modes: | Mode | Intended use | Persistent writes | |---|---|---| | Analyst | Paste or upload PL/SQL and receive its summary, workflow, dependencies, warnings, and other analysis details | None | | Admin | Ingest approved Oracle objects, add supporting knowledge, publish generated context for review, approve or reject context, submit feedback, and run maintenance | Yes, to the configured metadata store and Chroma | Everyone starts in Analyst mode. Choose Admin access in the React header and enter the admin password only when an administrative action is required. The browser keeps that password in memory for the current page session; it is not stored in browser storage. The environment variable is named ADMIN API KEY , but its value is simply the application's backend admin password. FastAPI compares it locally before allowing a protected endpoint. This comparison does not call Ollama, add prompt tokens, or change the analysis workflow, so it adds no meaningful LLM or processing load. ADMIN API KEY and OLLAMA API KEY are separate: ADMIN API KEY controls who may change application data. OLLAMA API KEY lets FastAPI authenticate to an office-hosted Ollama gateway. plsql-insight-react/ ├── app/ React application, components, styles, and API client ├── backend/ │ ├── app/ FastAPI, agents, workflow, parser, retrieval, repositories │ └── tests/ parser, metadata, storage, workflow, API, and security tests ├── scripts/ setup, start/stop, ingestion, Chroma, and Oracle DDL ├── sample data/ synthetic PL/SQL including a 2,000+ line package ├── docs/ architecture, security, retrieval, and deployment guidance ├── .env.example backend configuration ├── .env.local.example React API endpoint configuration ├── package.json React build and quality commands └── Makefile cd "C:\path\to\plsql-insight-react" python -m venv .venv .\.venv\Scripts\python.exe -m pip install --upgrade pip .\.venv\Scripts\python.exe -m pip install -e ".\backend dev " npm ci Copy-Item .env.example .env Copy-Item .env.local.example .env.local .\.venv\Scripts\python.exe .\scripts\init local.py The initializer never overwrites an existing .env . Convenience equivalent: .\scripts\dev.ps1 install .\scripts\dev.ps1 init ollama pull qwen2.5-coder:7b ollama pull deepseek-r1:7b ollama pull nomic-embed-text ollama list Default model routing: | Responsibility | Model | |---|---| | Metadata review | qwen2.5-coder:7b | | Procedure context | qwen2.5-coder:7b | | Procedure analysis | qwen2.5-coder:7b | | Table context | qwen2.5-coder:7b | | Package context | deepseek-r1:7b | | Independent auditor | deepseek-r1:7b | | Final merge | deepseek-r1:7b | | Embeddings | nomic-embed-text | Configured model names must exist on the target Ollama server. The backend does not silently substitute unrelated models. Start both services in the background: .\scripts\start.ps1 Then open: http://127.0.0.1:3000 http://127.0.0.1:8000/docs Stop the application: .\scripts\stop.ps1 Or run in separate terminals: Terminal 1 cd backend ..\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload Terminal 2, from repository root npm run dev Copy this entire folder to the office device. No source-code changes are required. npm ci using the installation commands above. .env.example to .env . .env.local.example to .env.local . APP ENVIRONMENT=uat APP MODE=oracle METADATA DB BACKEND=oracle ORACLE ENABLED=true ORACLE USER=plsql ai ORACLE PASSWORD=<load-from-approved-secret-store ORACLE DSN=approved-host:1521/APPDEV ORACLE AI SCHEMA=PLSQL AI ORACLE ALLOWED OWNERS=APP OWNER,REFERENCE OWNER ADMIN API KEY=<load-a-long-random-password-from-the-approved-secret-store ADMIN AUTH HEADER=X-Admin-Key Do not reuse the Oracle or Ollama credential. Keep this value only in the server-side .env or approved secret store; never put it in .env.local or commit it. Staff enter the same value into the React Admin access dialog when they need administrative functions. Serve the office application over HTTPS so the credential is encrypted in transit. OLLAMA BASE URL=https://ollama-server.internal OLLAMA API KEY=<load-from-approved-secret-store OLLAMA AUTH HEADER=Authorization OLLAMA AUTH SCHEME=Bearer MODEL METADATA REVIEW=qwen2.5-coder:7b MODEL PROCEDURE CONTEXT=qwen2.5-coder:7b MODEL PROCEDURE ANALYSIS=qwen2.5-coder:7b MODEL TABLE CONTEXT=qwen2.5-coder:7b MODEL PACKAGE CONTEXT=deepseek-r1:7b MODEL AUDITOR=deepseek-r1:7b MODEL FINAL MERGE=deepseek-r1:7b EMBEDDING MODEL=nomic-embed-text The API key is read only by FastAPI and is never sent to the React browser. If your office gateway expects X-API-Key: <key instead, set OLLAMA AUTH HEADER=X-API-Key and leave OLLAMA AUTH SCHEME= empty. The same credential is applied to model discovery, structured generation, and embeddings. CHROMA MODE=http CHROMA HOST=chroma-server.internal CHROMA PORT=8000 CHROMA SSL=true CORS ALLOWED ORIGINS=http://127.0.0.1:3000,http://localhost:3000 For a network URL, add that exact frontend origin and set .env.local : VITE API URL=http://office-device-hostname:8000 VITE ADMIN AUTH HEADER=X-Admin-Key The frontend setting contains only the header name, not the password. Use your approved Oracle client: @scripts/create oracle tables.sql .\.venv\Scripts\python.exe .\scripts\verify connections.py .\scripts\start.ps1 The office configuration uses Oracle for structured metadata; SQLite is not required there. React npm run typecheck npm run lint npm test Backend cd backend ..\.venv\Scripts\python.exe -m ruff check app tests ..\scripts ..\.venv\Scripts\python.exe -m mypy app ..\.venv\Scripts\python.exe -m pytest See Oracle deployment //docs/oracle-deployment.md , security //docs/security.md , agent workflow //docs/agent-workflow.md , and retrieval //docs/retrieval.md for deeper operational guidance.