{"slug": "readme", "title": "Readme", "summary": "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.", "body_md": "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.\n\nIt accepts pasted source, uploaded `.sql`\n\n/`.pkb`\n\n/`.pks`\n\n/`.txt`\n\nfiles, approved lower-environment Oracle objects, optional supporting documents, and bulk Oracle ingestion. Submitted PL/SQL is never compiled or executed.\n\nThis project does not use Streamlit, Spring, Docker, or a frontend database.\n\n``` php\nflowchart LR\n    UI[React 19 + TypeScript] --> API[FastAPI]\n    API --> G[Typed LangGraph workflow]\n    G --> P[Lexical parser + deterministic facts]\n    G --> R[Exact + Chroma semantic retrieval]\n    G --> Q[Qwen analysis agents]\n    G --> D[DeepSeek audit + merge]\n    P --> M[(Oracle metadata schema or optional local SQLite)]\n    R --> M\n    R --> C[(Persistent Chroma)]\n    Q --> O[Ollama / internal model endpoint]\n    D --> O\n```\n\nThe React application is stateless. Analyst submissions and results remain\n\ntransient. Durable knowledge, reviews, feedback, Oracle ingestion, and\n\ndependency edges remain behind repository interfaces in the backend and are\n\navailable only in Admin mode.\n\nThe application has two deliberately simple access modes:\n\n| Mode | Intended use | Persistent writes |\n|---|---|---|\n| Analyst | Paste or upload PL/SQL and receive its summary, workflow, dependencies, warnings, and other analysis details | None |\n| 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 |\n\nEveryone starts in Analyst mode. Choose **Admin access** in the React header and\n\nenter the admin password only when an administrative action is required. The\n\nbrowser keeps that password in memory for the current page session; it is not\n\nstored in browser storage.\n\nThe environment variable is named `ADMIN_API_KEY`\n\n, but its value is simply the\n\napplication's backend admin password. FastAPI compares it locally before\n\nallowing a protected endpoint. This comparison does not call Ollama, add prompt\n\ntokens, or change the analysis workflow, so it adds no meaningful LLM or\n\nprocessing load.\n\n`ADMIN_API_KEY`\n\nand `OLLAMA_API_KEY`\n\nare separate:\n\n`ADMIN_API_KEY`\n\ncontrols who may change application data.`OLLAMA_API_KEY`\n\nlets FastAPI authenticate to an office-hosted Ollama\ngateway.\n\n```\nplsql-insight-react/\n├── app/                     React application, components, styles, and API client\n├── backend/\n│   ├── app/                 FastAPI, agents, workflow, parser, retrieval, repositories\n│   └── tests/               parser, metadata, storage, workflow, API, and security tests\n├── scripts/                 setup, start/stop, ingestion, Chroma, and Oracle DDL\n├── sample_data/             synthetic PL/SQL including a 2,000+ line package\n├── docs/                    architecture, security, retrieval, and deployment guidance\n├── .env.example             backend configuration\n├── .env.local.example       React API endpoint configuration\n├── package.json             React build and quality commands\n└── Makefile\ncd \"C:\\path\\to\\plsql-insight-react\"\n\npython -m venv .venv\n.\\.venv\\Scripts\\python.exe -m pip install --upgrade pip\n.\\.venv\\Scripts\\python.exe -m pip install -e \".\\backend[dev]\"\n\nnpm ci\n\nCopy-Item .env.example .env\nCopy-Item .env.local.example .env.local\n.\\.venv\\Scripts\\python.exe .\\scripts\\init_local.py\n```\n\nThe initializer never overwrites an existing `.env`\n\n.\n\nConvenience equivalent:\n\n```\n.\\scripts\\dev.ps1 install\n.\\scripts\\dev.ps1 init\nollama pull qwen2.5-coder:7b\nollama pull deepseek-r1:7b\nollama pull nomic-embed-text\nollama list\n```\n\nDefault model routing:\n\n| Responsibility | Model |\n|---|---|\n| Metadata review | `qwen2.5-coder:7b` |\n| Procedure context | `qwen2.5-coder:7b` |\n| Procedure analysis | `qwen2.5-coder:7b` |\n| Table context | `qwen2.5-coder:7b` |\n| Package context | `deepseek-r1:7b` |\n| Independent auditor | `deepseek-r1:7b` |\n| Final merge | `deepseek-r1:7b` |\n| Embeddings | `nomic-embed-text` |\n\nConfigured model names must exist on the target Ollama server. The backend does not silently substitute unrelated models.\n\nStart both services in the background:\n\n```\n.\\scripts\\start.ps1\n```\n\nThen open:\n\n`http://127.0.0.1:3000`\n\n`http://127.0.0.1:8000/docs`\n\nStop the application:\n\n```\n.\\scripts\\stop.ps1\n```\n\nOr run in separate terminals:\n\n```\n# Terminal 1\ncd backend\n..\\.venv\\Scripts\\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload\n\n# Terminal 2, from repository root\nnpm run dev\n```\n\nCopy this entire folder to the office device. No source-code changes are required.\n\n`npm ci`\n\nusing the installation commands above.`.env.example`\n\nto `.env`\n\n.`.env.local.example`\n\nto `.env.local`\n\n.\n\n```\nAPP_ENVIRONMENT=uat\nAPP_MODE=oracle\nMETADATA_DB_BACKEND=oracle\nORACLE_ENABLED=true\nORACLE_USER=plsql_ai\nORACLE_PASSWORD=<load-from-approved-secret-store>\nORACLE_DSN=approved-host:1521/APPDEV\nORACLE_AI_SCHEMA=PLSQL_AI\nORACLE_ALLOWED_OWNERS=APP_OWNER,REFERENCE_OWNER\nADMIN_API_KEY=<load-a-long-random-password-from-the-approved-secret-store>\nADMIN_AUTH_HEADER=X-Admin-Key\n```\n\nDo not reuse the Oracle or Ollama credential. Keep this value only in the\n\nserver-side `.env`\n\nor approved secret store; never put it in `.env.local`\n\nor\n\ncommit it. Staff enter the same value into the React **Admin access** dialog\n\nwhen they need administrative functions. Serve the office application over\n\nHTTPS so the credential is encrypted in transit.\n\n```\nOLLAMA_BASE_URL=https://ollama-server.internal\nOLLAMA_API_KEY=<load-from-approved-secret-store>\nOLLAMA_AUTH_HEADER=Authorization\nOLLAMA_AUTH_SCHEME=Bearer\nMODEL_METADATA_REVIEW=qwen2.5-coder:7b\nMODEL_PROCEDURE_CONTEXT=qwen2.5-coder:7b\nMODEL_PROCEDURE_ANALYSIS=qwen2.5-coder:7b\nMODEL_TABLE_CONTEXT=qwen2.5-coder:7b\nMODEL_PACKAGE_CONTEXT=deepseek-r1:7b\nMODEL_AUDITOR=deepseek-r1:7b\nMODEL_FINAL_MERGE=deepseek-r1:7b\nEMBEDDING_MODEL=nomic-embed-text\n```\n\nThe API key is read only by FastAPI and is never sent to the React browser. If\n\nyour office gateway expects `X-API-Key: <key>`\n\ninstead, set\n\n`OLLAMA_AUTH_HEADER=X-API-Key`\n\nand leave `OLLAMA_AUTH_SCHEME=`\n\nempty. The same\n\ncredential is applied to model discovery, structured generation, and\n\nembeddings.\n\n```\nCHROMA_MODE=http\nCHROMA_HOST=chroma-server.internal\nCHROMA_PORT=8000\nCHROMA_SSL=true\nCORS_ALLOWED_ORIGINS=http://127.0.0.1:3000,http://localhost:3000\n```\n\nFor a network URL, add that exact frontend origin and set `.env.local`\n\n:\n\n```\nVITE_API_URL=http://office-device-hostname:8000\nVITE_ADMIN_AUTH_HEADER=X-Admin-Key\n```\n\nThe frontend setting contains only the header name, not the password.\n\n```\n# Use your approved Oracle client:\n# @scripts/create_oracle_tables.sql\n.\\.venv\\Scripts\\python.exe .\\scripts\\verify_connections.py\n.\\scripts\\start.ps1\n```\n\nThe office configuration uses Oracle for structured metadata; SQLite is not required there.\n\n```\n# React\nnpm run typecheck\nnpm run lint\nnpm test\n\n# Backend\ncd backend\n..\\.venv\\Scripts\\python.exe -m ruff check app tests ..\\scripts\n..\\.venv\\Scripts\\python.exe -m mypy app\n..\\.venv\\Scripts\\python.exe -m pytest\n```\n\nSee [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.", "url": "https://wpnews.pro/news/readme", "canonical_source": "https://dev.to/iamry02/readme-1j7b", "published_at": "2026-08-18 04:51:45+00:00", "updated_at": "2026-08-18 05:12:04.371897+00:00", "lang": "en", "topics": ["developer-tools", "large-language-models", "ai-agents", "ai-infrastructure"], "entities": ["PLSQL Insight", "React", "FastAPI", "LangGraph", "Ollama", "Oracle", "Chroma", "Qwen"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/readme", "markdown": "https://wpnews.pro/news/readme.md", "text": "https://wpnews.pro/news/readme.txt", "jsonld": "https://wpnews.pro/news/readme.jsonld"}}