ORE: Instructions file for Codex

AGENTS.md — project context for future assistants and contributors

Read this first when you (or an AI assistant) come back to this repo. It captures the current state and every gotcha so you don't have to rediscover them.

---

1. What this project is

ORE (Kaju Open Source) — a self-hostable AI-powered knowledge repository for academic documents. Three independent teams build it:

Team	Folder	What they ship
🤖 AI	ai-rag/	Python package: PDFs → embeddings
🧠 Backend	backend/	FastAPI HTTP API wrapping the AI package
🎨 Frontend	frontend/	Next.js 16 + React 19 + Tailwind v4 + TS

Current state (early alpha, June 2026):

• ✅ AI team has shipped 3 modules: ingestion, chunking, embedding
• ✅ 10 offline pytest tests passing; 3 marked @pytest.mark.network (need Ollama)
• 🟡 Backend has a scaffold (FastAPI app + 1 smoke test) — not connected to AI yet
• 🟡 Frontend is the default create-next-app boilerplate — not customized yet

---

2. Exact file layout (don't reorganize)

ore/                                          ← repo root
│
├── README.md                    38 lines    ← top-level orientation
├── CONTRIBUTING.md              81 lines    ← team rules
├── COMMANDS.md                 ~186 lines   ← every shell command + troubleshooting
├── AGENTS.md                   ← this file
├── LICENSE
├── .env.example                           ← ONE env var: ORERAG_EMBED_MODEL
├── .gitignore
│
├── docs/
│   ├── GETTING-STARTED.md       57 lines
│   └── architecture.png
│
├── ai-rag/                      🤖 AI team's home
│   ├── ingestion.py             📄 PDF → text (PyMuPDF)
│   ├── chunking.py              ✂️  text → chunks (LangChain RecursiveCharacterTextSplitter)
│   ├── embedding.py             🧠 text → vectors (Ollama)
│   ├── pyproject.toml           name = "orerag", pythonpath = ["."], ruff config
│   ├── README.md                50 lines  (TL;DR + per-team specifics)
│   ├── CONTRIBUTING.md          3 lines   (redirect to root)
│   ├── .gitignore
│   ├── tests/                            ← ALL tests live here
│   │   ├── conftest.py
│   │   ├── data/sample.pdf              ← offline test fixture
│   │   ├── test_ingestion.py
│   │   ├── test_chunking.py
│   │   └── test_embedding.py            (3 tests marked @pytest.mark.network)
│   └── documents/                        (empty placeholder for user uploads)
│
├── backend/                     🧠 Backend team's home
│   ├── app/main.py                       ← FastAPI app (scaffold: /, /health)
│   ├── tests/test_smoke.py               ← one passing test
│   ├── pyproject.toml                    name = "orerag-backend"
│   ├── README.md                18 lines
│   └── .gitignore
│
└── frontend/                    🎨 Frontend team's home
    ├── app/  (page.tsx, layout.tsx, globals.css, favicon.ico)
    ├── public/  (5 default Next.js SVGs)
    ├── package.json / package-lock.json / tsconfig.json / …
    ├── README.md                15 lines
    └── .gitignore