josephkirk/wiki_agent · kb_agent/template_files/default
Generated index for {{TITLE}}.
Open source Repository Open in the app JSON README (API)
About
<!-- Generated by scripts/maintain.py. Do not edit the sections below. -->
{{INDEX_SECTIONS}}
Details
- Kind
- OKF bundles
- Topic
- No topic detected
- Publisher
- josephkirk
- Origin
- okf_github
- Category
- dados
- Version
- 0.2
- Last push
- 2026-08-06T02:08:25Z
- Repository state
- ativo
- Language
- Python
- Added
- 2026-09-08 02:18:52
- Updated
- 2026-09-08 02:18:52
- Origin id
josephkirk/wiki_agent:kb_agent/template_files/default/index.md
README
# Knowledge Base Wiki Agent
A reusable FastAPI service for creating, adapting, maintaining, and querying
Git-backed Wiki.js knowledge bases. The application repository contains only agent
code, reusable templates, tests, and deployment configuration; knowledge content
lives in target Git repositories.
## What it does
- Creates a new knowledge-base structure from user-defined sections.
- Adapts an existing Git repository into the accepted structure.
- Adds a manifest, `AGENTS.md`, generated `index.md`, and append-only `log.md`.
- Adds Wiki.js frontmatter to existing Markdown while preserving valid metadata.
- Routes misplaced Markdown into configured sections.
- Extracts and converts PDF, DOCX, and HTML documents into Markdown pages.
- Accepts later document ingestion into any initialized knowledge repository.
- Presents a complete Git diff before any commit or push.
- Pulls again at approval time and stops on conflicting upstream changes.
- Answers questions through lightweight Markdown search and verified source links.
## Target repository contract
Every managed repository contains `.knowledgebase.yml`:
```yaml
version: 1
title: Engineering Knowledge
description: Shared engineering guides and decisions.
wiki_url: https://wiki.example.com
sections:
- key: guides
title: Guides
description: Reusable procedures and operating guides.
scoped: false
- key: projects
title: Projects
description: Project-specific decisions and implementation notes.
scoped: true
agent_page: AGENTS.md
index_page: index.md
log_page: log.md
extra_root_markdown: []
support_directories:
- assets
support_files:
- .gitattributes
- .gitignore
```
Normal sections store pages directly, such as `guides/deployment.md`. Scoped
sections require a named subfolder, such as
`projects/project-atlas/material-pipeline.md`. Section keys and scope folders are
lowercase URL-safe slugs.
The manifest lets each wiki use its own subject area and information architecture.
## Installation
Requirements:
- [uv](https://docs.astral.sh/uv/)
- Git
- A corporate OpenAI-compatible chat-completions endpoint
- Git credentials with read and push access to target repositories
```powershell
uv sync --extra dev
Copy-Item .env.example .env
```
Configure `.env`:
| Variable | Purpose |
| --- | --- |
| `KB_DATA_DIR` | Uploads, JSON job state, patches, reader caches, and temporary clones |
| `KB_GIT_AUTHOR_NAME` | Author used for approved commits |
| `KB_GIT_AUTHOR_EMAIL` | Email used for approved commits |
| `KB_WIKI_URL` | Base URL used when returning Wiki.js source links |
| `OPENAI_BASE_URL` | Corporate OpenAI-compatible `/v1` endpoint |
| `OPENAI_API_KEY` | Corporate API credential |
| `OPENAI_MODEL` | Deployed chat model |
| `KB_ALLOWED_ORIGINS` | Comma-separated Wiki.js origins allowed by CORS |
| `KB_MAX_UPLOAD_MB` | Maximum size of each uploaded document |
Keep `KB_DATA_DIR` outside both this application repository and all managed
knowledge repositories in production. Do not put credentials in repository URLs;
use the host Git credential helper, SSH agent, or CI credentials.
Run the service:
```powershell
uv run uvicorn kb_agent.main:app --host 0.0.0.0 --port 8000 --reload
```
API documentation is available at `/api/docs`.
## Create a knowledge repository
The remote may be empty. Supply the desired structure to
`POST /api/repositories`:
```json
{
"repository": "git@gitlab.example.com:knowledge/engineering.git",
"branch": "main",
"title": "Engineering Knowledge",
"description": "Shared engineering guides and decisions.",
"wiki_url": "https://wiki.example.com",
"adapt_existing": false,
"sections": [
{
"key": "guides",
"title": "Guides",
"description": "Reusable procedures and operating guides.",
"scoped": false
},
{
"key": "projects",
"title": "Projects",
"description": "Project-specific decisions and notes.",
"scoped": true
}
]
}
```
The background job creates the manifest, root templates, and section directories,
then returns a reviewable diff. Poll `GET /api/jobs/{id}` and approve with:
```json
{"approved": true}
```
Approval is sent to `POST /api/jobs/{id}/approve`.
## Adapt an existing knowledge repository
Use the same request with `adapt_existing: true`. The adapter:
1. clones the requested branch;
2. preserves already valid pages;
3. adds Wiki.js frontmatter to unformatted Markdown;
4. routes documents into the closest configured section;
5. parses PDF, DOCX, and HTML files into Markdown;
6. preserves non-document directories and files as declared support paths;
7. creates missing root templates and the manifest;
8. validates links and paths, then returns the complete diff.
If a document belongs to a scoped section and the scope is unknown, the job enters
`needs_input`. Resume through the approval endpoint:
```json
{
"approved": true,
"scopes": {
"projects": "Project Atlas"
}
}
```
No changes are committed until the resulting diff is explicitly approved.
## Ingest documents into any initialized repository
`POST /api/ingest` accepts Markdown, PDF, DOCX, and HTML multipart uploads:
```powershell
curl.exe -X POST http://localhost:8000/api/ingest `
-F "repository=git@gitlab.example.com:knowledge/engineering.git" `
-F "branch=main" `
-F 'scopes={"projects":"Project Atlas"}' `
-F "files=@architecture-decision.docx" `
-F "instructions=Keep the rollout and rollback procedures."
```
The corporate model receives the target manifest, `AGENTS.md`, generated index,
related page excerpts, supplied scopes, and extracted source content. It may update
multiple established pages or create new ones, but it can only use configured
sections and supplied scope names.
## Chat and source access
Chat requests identify the target repository:
```json
{
"repository": "git@gitlab.example.com:knowledge/engineering.git",
"branch": "main",
"message": "How do we roll back the service?",
"max_sources": 6
}
```
`POST /api/chat` returns sanitized Markdown as server-sent events followed by
verified sources. Retrieve an individual page with:
```text
GET /api/source/guides/deployment?repository=REPOSITORY&branch=main
```
## Wiki.js widget
```html
<script
src="https://agent.example.com/widget/chat-widget.js"
data-api-url="https://agent.example.com"
data-wiki-url="https://wiki.example.com"
data-repository="git@gitlab.example.com:knowledge/engineering.git"
data-branch="main"
data-title="Knowledge Assistant">
</script>
```
The widget renders sanitized Markdown in an isolated shadow root and opens verified
sources in Wiki.js.
## Maintenance CLI
Validate or update any initialized checkout:
```powershell
uv run kb-maintain --repo C:\knowledge\engineering
uv run kb-maintain --repo C:\knowledge\engineering --check
```
Maintenance validates the repository-specific manifest, Wiki.js frontmatter,
section paths, scoped folders, duplicate routes, and internal links. It rebuilds
`index.md` in manifest order and appends unrecorded non-bot commits to `log.md`.
Check mode restores generated files before exiting.
## Verification
```powershell
uv run pytest
uv run ruff check .
node --check widget/chat-widget.js
```