Metadata-Version: 2.4
Name: groundly
Version: 0.6.3
Summary: Local-first course knowledge bases for AI agents: index your materials, study grounded, share the index.
License: MIT License
        
        Copyright (c) 2026 Paul Hondola
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: <3.13,>=3.11
Requires-Dist: docling==2.113.0
Requires-Dist: fastapi>=0.111
Requires-Dist: fastmcp>=2.0
Requires-Dist: flagembedding==1.3.5
Requires-Dist: genanki>=0.13
Requires-Dist: graphrag==3.1.0
Requires-Dist: httpx>=0.27
Requires-Dist: llama-index==0.14.23
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic>=2.7
Requires-Dist: rapidocr==3.9.1
Requires-Dist: rich>=13
Requires-Dist: sentence-transformers==5.6.0
Requires-Dist: sqlite-vec>=0.1
Requires-Dist: transformers<5,>=4.51
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn>=0.30
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: eval
Requires-Dist: ragas>=0.2; extra == 'eval'
Description-Content-Type: text/markdown

# Groundly

**Local-first course knowledge bases for AI agents.** Index your course materials once; then any MCP-capable agent — Claude Code, Claude Desktop, Codex — can answer questions grounded in the actual course content with page-level citations, generate execution-verified tests and flashcards, quiz your weak areas, and track your mastery. Share the finished knowledge base with your coursemates as a single file.

Bachelor thesis project, Universitatea Politehnica Timișoara.

```
$ groundly index <SUBJECT> ./slides/
  ✓ 12 PDFs → 384 chunks → embedded (bge-m3, local) → indexed
$ # wire into Claude Code:  { "command": "groundly", "args": ["mcp"] }
```

Then, inside your agent: *"What did lecture 4 say about deadlock prevention?"* → answer cited to **lecture-04.pdf, page 12, "Deadlocks › Prevention"** — or *"not covered by the course materials"*, never a hallucination.

## Why not NotebookLM / a Claude Project?

1. **Verified generation** — every test question and flashcard passes a verifier: answerable from the cited sources, answer key checked, and code questions' reference solutions **actually executed** before acceptance.
2. **Enforced citations** — structural, page-level, with honest refusal when the corpus doesn't cover it.
3. **A portable index** — `groundly export <SUBJECT>` → one file; a coursemate imports it and their agent uses it directly. The expensive artifacts (knowledge graph, verified decks) are built once and shared.
4. **Cross-host progress** — mastery per topic and study memory persist in local files, whatever agent you talk to. Your queries and results never leave your machine and are never part of an export.

## Features

- **Grounded Q&A** — hybrid retrieval (bge-m3 dense + learned sparse + BM25, reranked; optional GraphRAG for synthesis questions), via MCP tools or `groundly ask`
- **Verified quizzes & coding challenges** — generated by Groundly (your API key) *or by your agent* (no key needed) — either way, nothing unverified is stored
- **Flashcards → Anki** — verified decks exported as `.apkg`
- **Mastery map & study memory** — per-topic mastery from quiz results; "continue studying" warm starts in any host
- **Import/export** — the whole knowledge base as one shareable file, with pinned-model compatibility

## Install

```
uv tool install groundly
```

Local-first honestly stated: first run downloads the embedding models (~2.7GB total). Indexing and search need **no API key**; grounded answer generation and graph builds use your own OpenAI-compatible provider (cloud key, LM Studio, or Ollama).

**Setup guides:** [connect Claude Code / Codex to the MCP server](docs/guides/mcp-hosts.md) · [use LM Studio as a zero-key local provider](docs/guides/lm-studio.md)

**Thesis core:** four-arm RAG vs GraphRAG evaluation on real RO/EN course corpora, plus a measured comparison of enforced vs agent-mediated grounding.
