Skip to content

Commit fb9eba1

Browse files
DMontgomery40DMontgomery40
committed
feat(docs): Revise documentation structure and enhance configuration details
- Updated `mkdocs.yml` to improve site description, copyright information, and theme settings, including a new color palette and font specifications. - Refined the navigation structure in the documentation to provide clearer access to key topics, including architecture, retrieval, and configuration. - Enhanced the `index.md` file with a more concise overview of TriBridRAG, emphasizing the tri-brid retrieval approach and its components. - Removed outdated documentation files related to API endpoints and model configurations to streamline content and focus on current features. - Improved the overall organization and clarity of the documentation, ensuring it aligns with the latest system architecture and user needs. These changes enhance the usability and accessibility of the TriBridRAG documentation, making it easier for users to understand and navigate the system's capabilities.
1 parent aba7d1e commit fb9eba1

56 files changed

Lines changed: 10231 additions & 26303 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/docs-automation.yml‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
name: Documentation Automation
2+
on:
3+
push:
4+
branches: ["main", "develop"]
5+
pull_request:
6+
branches: ["main"]
7+
workflow_dispatch:
8+
inputs:
9+
regenerate_all:
10+
description: 'Regenerate all documentation'
11+
required: false
12+
type: boolean
13+
default: false
14+
15+
permissions:
16+
contents: write
17+
pages: write
18+
id-token: write
19+
pull-requests: write
20+
21+
jobs:
22+
generate-docs:
23+
runs-on: ubuntu-latest
24+
steps:
25+
- uses: actions/checkout@v4
26+
with:
27+
fetch-depth: 0
28+
29+
- name: Set up Python
30+
uses: actions/setup-python@v5
31+
with:
32+
python-version: '3.11'
33+
34+
- name: Install dependencies
35+
run: |
36+
pip install mkdocs mkdocs-material pymdown-extensions
37+
pip install requests pyyaml
38+
pip install mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin
39+
40+
- name: Generate documentation with AI
41+
if: ${{ github.event.inputs.regenerate_all == 'true' }}
42+
env:
43+
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
44+
run: |
45+
python scripts/docs_ai/docs_autopilot_enhanced.py --regenerate-all
46+
47+
- name: Build documentation
48+
run: mkdocs build
49+
50+
- name: Create PR with documentation updates
51+
if: github.event_name == 'workflow_dispatch' && github.event.inputs.regenerate_all == 'true'
52+
uses: peter-evans/create-pull-request@v6
53+
with:
54+
token: ${{ secrets.GITHUB_TOKEN }}
55+
title: "docs: AI-generated documentation updates"
56+
body: |
57+
This PR contains AI-generated documentation updates based on the codebase.
58+
59+
**Please review carefully before merging.**
60+
61+
- [ ] Documentation is accurate
62+
- [ ] No internal/sensitive information exposed
63+
- [ ] Material for MkDocs features utilized
64+
- [ ] Navigation structure is logical
65+
- [ ] No banned terms (Qdrant, Redis, LangChain, cards)
66+
commit-message: "docs: update documentation with AI assistance"
67+
branch: docs/ai-updates-${{ github.run_id }}
68+
base: main
69+
70+
deploy-docs:
71+
needs: generate-docs
72+
if: github.ref == 'refs/heads/main'
73+
runs-on: ubuntu-latest
74+
environment:
75+
name: github-pages
76+
url: ${{ steps.deployment.outputs.page_url }}
77+
steps:
78+
- uses: actions/checkout@v4
79+
with:
80+
fetch-depth: 0
81+
82+
- uses: actions/setup-python@v5
83+
with:
84+
python-version: '3.11'
85+
86+
- name: Install dependencies
87+
run: |
88+
pip install mkdocs mkdocs-material pymdown-extensions
89+
pip install mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin
90+
91+
- name: Build documentation
92+
run: mkdocs build
93+
94+
- name: Setup Pages
95+
uses: actions/configure-pages@v4
96+
97+
- name: Upload artifact
98+
uses: actions/upload-pages-artifact@v3
99+
with:
100+
path: 'site'
101+
102+
- name: Deploy to GitHub Pages
103+
id: deployment
104+
uses: actions/deploy-pages@v4

‎mkdocs.yml‎

Lines changed: 57 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,83 +1,89 @@
11
site_name: TriBridRAG Docs
2+
site_description: Tri-Brid Retrieval-Augmented Generation combining Vector, Sparse, and Graph search
23
site_url: https://dmontgomery40.github.io/tribrid-rag/
34
repo_url: https://github.com/DMontgomery40/tribrid-rag
4-
edit_uri: edit/main/mkdocs/docs/
5-
5+
repo_name: DMontgomery40/tribrid-rag
6+
copyright: Copyright © 2025 TriBridRAG
67
docs_dir: mkdocs/docs
78

89
theme:
910
name: material
1011
language: en
12+
palette:
13+
- scheme: default
14+
primary: deep purple
15+
accent: purple
16+
toggle:
17+
icon: material/brightness-7
18+
name: Switch to dark mode
19+
- scheme: slate
20+
primary: deep purple
21+
accent: purple
22+
toggle:
23+
icon: material/brightness-4
24+
name: Switch to light mode
25+
font:
26+
text: Roboto
27+
code: Roboto Mono
1128
features:
1229
- navigation.instant
30+
- navigation.tracking
1331
- navigation.tabs
14-
- navigation.top
1532
- navigation.sections
16-
- search.suggest
17-
- search.highlight
33+
- navigation.expand
34+
- navigation.top
35+
- toc.follow
1836
- content.code.copy
1937
- content.code.annotate
20-
palette:
21-
- scheme: slate
22-
primary: teal
23-
accent: amber
24-
toggle:
25-
icon: material/brightness-4
26-
name: Switch to light mode
27-
- scheme: default
28-
primary: teal
29-
accent: amber
30-
toggle:
31-
icon: material/brightness-7
32-
name: Switch to dark mode
38+
- content.tabs.link
39+
- search.suggest
40+
- search.highlight
41+
icon:
42+
logo: material/vector-combine
43+
repo: fontawesome/brands/github
44+
45+
plugins:
46+
- search
3347

3448
markdown_extensions:
3549
- admonition
36-
- attr_list
37-
- def_list
38-
- footnotes
39-
- md_in_html
4050
- pymdownx.details
41-
- pymdownx.emoji
51+
- pymdownx.tabbed:
52+
alternate_style: true
53+
- pymdownx.tasklist:
54+
custom_checkbox: true
4255
- pymdownx.highlight:
4356
anchor_linenums: true
4457
- pymdownx.inlinehilite
45-
- pymdownx.keys
46-
- pymdownx.mark
47-
- pymdownx.smartsymbols
48-
- pymdownx.snippets
4958
- pymdownx.superfences:
5059
custom_fences:
5160
- name: mermaid
5261
class: mermaid
53-
- pymdownx.tabbed:
54-
alternate_style: true
62+
format: !!python/name:pymdownx.superfences.fence_code_format
63+
- pymdownx.keys
64+
- attr_list
65+
- md_in_html
66+
- def_list
67+
- footnotes
5568
- tables
56-
- toc:
57-
permalink: true
69+
- pymdownx.emoji:
70+
emoji_index: !!python/name:material.extensions.emoji.twemoji
71+
emoji_generator: !!python/name:material.extensions.emoji.to_svg
5872

59-
plugins:
60-
- search
61-
- glightbox
73+
extra:
74+
social:
75+
- icon: fontawesome/brands/github
76+
link: https://github.com/DMontgomery40/tribrid-rag
6277

6378
extra_javascript:
64-
- https://unpkg.com/mermaid@11/dist/mermaid.min.js
65-
- assets/js/mermaid-init.js
79+
- https://unpkg.com/mermaid@10/dist/mermaid.min.js
6680

6781
nav:
6882
- Home: index.md
69-
- Getting Started:
70-
- Quick Start: getting-started/quickstart.md
71-
- Installation: getting-started/installation.md
72-
- Features:
73-
- Tri-Brid Search: features/tribrid-search.md
74-
- Vector (pgvector): features/pgvector.md
75-
- Graph (Neo4j): features/neo4j-graph.md
76-
- Configuration:
77-
- Models: configuration/models.md
78-
- Settings: configuration/settings.md
79-
- API:
80-
- Endpoints: api/endpoints.md
81-
- Operations:
82-
- Monitoring: operations/monitoring.md
83-
- Troubleshooting: operations/troubleshooting.md
83+
- Architecture: architecture.md
84+
- Retrieval: retrieval/overview.md
85+
- Configuration: configuration.md
86+
- API: api.md
87+
- Indexing: indexing.md
88+
- Deployment: deploy.md
89+
- Glossary: glossary.md

‎mkdocs/docs/api.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
<div class="grid chunk_summaries" markdown>
2+
3+
- :material-information:{ .lg .middle } **API Endpoints**
4+
5+
---
6+
7+
FastAPI endpoints in server/api/
8+
9+
- :material-magnify:{ .lg .middle } **Search & Retrieval**
10+
11+
---
12+
13+
/search, /graph, /chunk_summaries
14+
15+
- :material-cog:{ .lg .middle } **Config & Models**
16+
17+
---
18+
19+
/config, /models, /reranker
20+
21+
</div>
22+
23+
!!! note "Implementation Note"
24+
The API routes map directly to the server modules under server/api. Each endpoint uses Pydantic models for request/response validation.
25+
26+
!!! tip "Pro Tip"
27+
Use the models endpoint (GET /models) as the authoritative list for UI dropdowns. Do not hardcode model lists elsewhere.
28+
29+
!!! warning "Compatibility Warning"
30+
API still uses `repo_id` naming. When scoping operations, prefer `corpus_id` but accept `repo_id` for compatibility.
31+
32+
??? note "Collapsible: Endpoint index"
33+
34+
The API modules expose endpoints and helper functions. Key modules include:
35+
36+
- chunk_summaries.py
37+
- config.py
38+
- reranker.py
39+
- models.py
40+
- index.py
41+
- graph.py
42+
43+
44+
## Selected endpoints and usage
45+
46+
| Endpoint | Method | Purpose | Request model |
47+
|----------|--------|---------|---------------|
48+
| /search | POST | Run tri-brid search | SearchRequest (generated) |
49+
| /config | GET/PUT/PATCH | Read/update server config | TriBridConfig (generated) |
50+
| /models | GET | Serve data/models.json | n/a |
51+
| /chunk_summaries | GET/POST | Read/build chunk summaries | IndexScope / BuildRequest |
52+
| /graph/{corpus_id}/entities | GET | List graph entities | CorpusScope |
53+
54+
55+
```mermaid
56+
flowchart LR
57+
Client --> API[FastAPI]
58+
API --> Search[/search]
59+
API --> Models[/models]
60+
API --> Config[/config]
61+
Search --> Fusion[TriBridFusion]
62+
Fusion --> DB[(Postgres)]
63+
Fusion --> Graph[(Neo4j)]
64+
```
65+
66+
67+
### Example: search call
68+
69+
=== "Python"
70+
```python
71+
import requests
72+
73+
resp = requests.post('http://localhost:8000/search', json={
74+
'query': 'how to run migrations',
75+
'repo_id': 'my_corpus'
76+
}) # (1)
77+
print(resp.json())
78+
```
79+
80+
=== "curl"
81+
```bash
82+
curl -X POST "http://localhost:8000/search" \
83+
-H 'Content-Type: application/json' \
84+
-d '{"query":"how to run migrations","repo_id":"my_corpus"}'
85+
```
86+
87+
=== "TypeScript"
88+
```typescript
89+
import { SearchRequest, SearchResponse } from '../types/generated' // (1)
90+
91+
async function run(query: string, repoId: string): Promise<SearchResponse> {
92+
const res = await fetch('/api/search', {
93+
method: 'POST',
94+
body: JSON.stringify({ query, repo_id: repoId }),
95+
})
96+
return res.json()
97+
}
98+
```
99+
100+
101+
1. Use generated types for request/response shapes
102+
103+
104+
### Reranker endpoints (selected)
105+
106+
| Route | Method | Purpose |
107+
|-------|--------|---------|
108+
| /reranker/status | GET | Check if reranker is loaded |
109+
| /reranker/mine | POST | Mine triplets for training |
110+
| /reranker/train | POST | Train a reranker model |
111+
| /reranker/evaluate | POST | Evaluate reranker performance |
112+
113+
114+
### Chunk summaries endpoints
115+
116+
| Route | Method | Purpose |
117+
|-------|--------|---------|
118+
| /chunk_summaries | GET | List summaries for a corpus |
119+
| /chunk_summaries/build | POST | Trigger background build of chunk summaries |
120+
121+
122+
- [x] Use ++ctrl+c++ to copy curl snippets
123+
- [x] Use generated TypeScript types from Pydantic for API contracts
124+
125+
126+
??? note "Collapsible: Error handling"
127+
128+
FastAPI returns structured errors when validation fails. Check status codes and error messages that include the failing field path.

0 commit comments

Comments
 (0)