FastAPI، SQLite اور MCP کے ساتھ مقامی فائل نالج بیس بنائیں اور استعمال کریں

جائزہ

نالج بیس فیز 1، FastAPI، SQLite اور مقامی فائل سسٹم اسٹوریج کے ذریعے بنایا گیا کم از کم قابلِ عمل فائل نالج بیس ہے۔ یہ تصدیق شدہ دستاویزاتی انتظام، اندرونی فولڈرز، براؤزر کے مقامی پیش نظارے، میٹا ڈیٹا اور ٹیگز، منتظم کے ٹولز، آڈٹ کی معلومات، اور Model Context Protocol، یا MCP، کے ذریعے AI ایجنٹس کے لیے صرف پڑھنے کی سہولت فراہم کرتا ہے۔

یہ مرحلہ جان بوجھ کر ہلکا رکھا گیا ہے۔ اس کے لیے Docker، PostgreSQL، MinIO، LibreOffice، ONLYOFFICE یا چلنے والی کسی دوسری ڈیٹا بیس سروس کی ضرورت نہیں ہے۔ PostgreSQL اور آبجیکٹ اسٹوریج کو بعد کی منتقلی کے لیے رکھا گیا ہے۔

پروجیکٹ کیا فراہم کرتا ہے

• منتظم کے ذریعے بنائے گئے صارفین، لاگ اِن اور JWT تصدیق۔
• اندرونی فولڈرز اور بریڈ کرمب نیویگیشن کے ساتھ عوامی نالج بیسز۔
• فولڈر کے دائرہ کار میں دستاویزات کی فہرست، واحد فائل اپ لوڈ اور بیچ اپ لوڈ۔
• PDF، متن، Markdown، HTML، تصاویر، PowerPoint، Word اور Excel فائلوں کی معاونت۔
• دستاویز کا میٹا ڈیٹا، ٹیگز، مالک اور اپ لوڈ کرنے والے کی معلومات۔
• اصل فائل کا پیش نظارہ اور ڈاؤن لوڈ۔
• متن، Markdown، PDF، DOCX، XLSX، PPTX اور تصاویر کے لیے ایپ کے اندر مطالعہ۔
• پرانے DOC، XLS اور PPT فائلوں سے بہترین کوشش کے تحت متن اخذ کرنا۔
• صرف مالک کے لیے دستاویز میں ترمیم، عارضی حذف، بحالی، فولڈر کا نام تبدیل کرنا اور خالی فولڈر حذف کرنا۔
• حذف شدہ دستاویزات کے لیے ری سائیکل بن۔
• مختلف دائرہ ہائے کار کے درمیان دستاویزات اور فولڈرز کی نقل، جس میں اندرونی فولڈرز کی تکراری نقل اور فزیکل اسٹوریج کی نقل بھی شامل ہے۔
• صرف منتظم کے لیے صارف انتظام، آڈٹ لاگز اور MCP انوکیشن لاگز۔
• صرف پڑھنے کی REST API، تیار کردہ OpenAPI دستاویزات اور MCP انضمام۔

اسٹوریج کیسے کام کرتی ہے

ایپلیکیشن رن ٹائم فائلیں backend/data/ کے اندر بناتی ہے۔ SQLite ڈیٹا بیس backend/data/knowledge_base.db کے طور پر محفوظ ہوتا ہے، جبکہ اپ لوڈ کی گئی فائلیں اور تیار کردہ Markdown فائلیں backend/data/storage/ کے اندر رکھی جاتی ہیں۔

مقامی اسٹوریج میں پاتھ ٹریورسل سے تحفظ شامل ہے۔ موجودہ Docker Compose کنفیگریشن بعد میں PostgreSQL اور آبجیکٹ اسٹوریج کی منتقلی کے لیے ہے اور اس مرحلے کے لیے ضروری نہیں ہے۔

بیک اینڈ انسٹال کریں

1. ماحول کی فائل بنائیں

PowerShell کھولیں، ریپوزٹری کی backend ڈائریکٹری میں جائیں، اور روٹ ماحول کے ٹیمپلیٹ کو backend/.env میں کاپی کریں۔

cd backend
Copy-Item ..\.env.example .env

آپریشنل سیٹنگز .env.example، backend/app/core/config.py اور scripts/ کے اندر موجود PowerShell کنٹرول فائلوں کے ذریعے متعین کی جاتی ہیں۔

2. Python ورچوئل ماحول بنائیں

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

یہ کمانڈز backend ڈائریکٹری سے چلائیں۔ ورچوئل ماحول کو فعال کرنے سے پروجیکٹ کے پیکیجز آپ کی عالمی Python انسٹالیشن سے الگ رہتے ہیں۔

3. SQLite کو ابتدائی حالت میں لائیں

python -m app.db.init_db

یہ کمانڈ مطلوبہ SQLite ٹیبلز کو شروع یا دوبارہ بناتی ہے۔ چونکہ ٹیبلز دوبارہ بنانے سے موجودہ ڈیٹا متاثر ہو سکتا ہے، اس لیے دستاویزات محفوظ کرنا شروع کرنے کے بعد اسے احتیاط سے استعمال کریں۔

4. FastAPI شروع کریں

uvicorn app.main:app --reload

اس کے بعد ڈویلپمنٹ سرور http://127.0.0.1:8000 پر دستیاب ہوگا۔ --reload آپشن سورس فائلوں میں تبدیلی کے وقت ایپلیکیشن کو خودکار طور پر دوبارہ لوڈ کرتا ہے۔

5. API دستاویزات کھولیں

تیار کردہ OpenAPI اینڈ پوائنٹس دیکھنے اور آزمانے کے لیے http://127.0.0.1:8000/docs ملاحظہ کریں۔

انسٹالیشن کی تصدیق کریں

ٹیسٹس کے لیے بیک اینڈ ڈائریکٹری کا PYTHONPATH میں ہونا ضروری ہے۔ Windows Command Prompt میں چلائیں:

set PYTHONPATH=.
python -m pytest

PowerShell میں استعمال کریں:

$env:PYTHONPATH = "."
python -m pytest

ریپوزٹری میں scripts/ کے اندر سروس شروع کرنے، دوبارہ شروع کرنے، روکنے اور اسٹیٹس دیکھنے کے لیے الگ PowerShell کنٹرول فائلیں بھی موجود ہیں۔

REST API کے ساتھ تصدیق کریں

صارفین منتظم کے ذریعے بنائے جاتے ہیں۔ اکاؤنٹ حاصل ہونے کے بعد اپنا صارف نام اور پاس ورڈ لاگ اِن اینڈ پوائنٹ پر بھیجیں۔ جواب میں تصدیق شدہ درخواستوں کے لیے درکار ٹوکن شامل ہوگا۔

$body = @{
  username = "demo"
  password = "password-123"
} | ConvertTo-Json

$response = Invoke-RestMethod `
  -Method Post `
  -Uri http://127.0.0.1:8000/api/v1/auth/login `
  -ContentType "application/json" `
  -Body $body

$response

واپس کیے گئے ایکسیس ٹوکن کو کاپی کریں اور اسے Bearer کریڈنشل کے طور پر استعمال کریں۔ ٹوکن کی اجازتیں تصدیق شدہ صارف کی شناخت اور کردار کے مطابق ہوتی ہیں۔

دستاویز اپ لوڈ کریں

اپ لوڈ اینڈ پوائنٹ multipart form data قبول کرتا ہے۔ نالج بیس ID، اختیاری ٹیگز، فائل اور Bearer ٹوکن فراہم کریں:

$token = "<access_token>"
$knowledgeBaseId = 1

curl.exe `
  -X POST `
  "http://127.0.0.1:8000/api/v1/documents/upload" `
  -H "Authorization: Bearer $token" `
  -F "knowledge_base_id=$knowledgeBaseId" `
  -F "tags=制度,测试" `
  -F "file=@D:\path\to\guide.txt"

پروجیکٹ واحد اور بیچ، دونوں طرح کے اپ لوڈز کو سپورٹ کرتا ہے۔ اپ لوڈ کی گئی اصل فائلیں مقامی اسٹوریج میں برقرار رہتی ہیں، جبکہ معاون مواد ایپ کے اندر موجود ریڈر میں کھولا جا سکتا ہے۔

فولڈرز بنائیں اور استعمال کریں

فولڈر اینڈ پوائنٹ پر اس کی نالج بیس ID اور نام پوسٹ کرکے فولڈر بنائیں:

$body = @{
  knowledge_base_id = 1
  name = "实验方案"
} | ConvertTo-Json

Invoke-RestMethod `
  -Method Post `
  -Uri http://127.0.0.1:8000/api/v1/folders `
  -Headers @{ Authorization = "Bearer $token" } `
  -ContentType "application/json" `
  -Body $body

کسی مخصوص فولڈر میں اپ لوڈ کرنے کے لیے multipart اپ لوڈ فارم میں folder_id شامل کریں۔ ویب انٹرفیس میں فولڈر منتخب کرنے پر یہ خودکار طور پر شامل ہو جاتا ہے۔

نالج بیس سلیکٹر بطور ڈیفالٹ 全部 پر سیٹ ہوتا ہے، جس کا مطلب ہے "سب"۔ یہ منظر تمام عوامی نالج بیسز میں موجود روٹ دستاویزات اور فولڈرز دکھاتا ہے۔ فولڈر بناتے وقت ڈائیلاگ میں اس کے منزل والے نالج بیس کو منتخب کریں۔ تمام نالج بیسز کے منظر سے کی جانے والی اپ لوڈ میں پہلا دستیاب نالج بیس استعمال ہوتا ہے، جب تک کہ کوئی فولڈر منتخب نہ کیا جائے۔

براؤزر میں مقامی پری ویوز کو سمجھیں

فرنٹ اینڈ مستند API کے ذریعے فائلیں حاصل کرتا ہے، انہیں براؤزر کی میموری میں رکھتا ہے، اور مقامی طور پر رینڈر کرتا ہے۔ یہ DOCX، PPTX، XLS، اور XLSX کے لیے vue3-office-preview، PDF کے لیے @vue3-office/vue-pdf، اور Markdown کے لیے @deot/docs-markdown استعمال کرتا ہے۔ PPTX رینڈرنگ میں بنڈل شدہ pptx-renderer استعمال ہوتا ہے۔

اس طریقے کے لیے LibreOffice، ONLYOFFICE، Docker، یا Python document-preview SDK کی ضرورت نہیں ہے۔ اصل فائل مقامی اسٹوریج میں برقرار رہتی ہے۔ Markdown extraction اور پرانی .doc، .xls، اور .ppt فائلوں کی fallback processing بیک اینڈ کی ذمہ داریاں رہتی ہیں۔

MCP کے ذریعے AI ایجنٹ کو مربوط کریں

ریپوزٹری میں ایک الگ read-only MCP سروس شامل ہے۔ یہ FastAPI ایپلیکیشن کے SQLite database، local storage، JWT secret، اور document reader کا اشتراک کرتی ہے۔ Phase 1 کے دستیاب ٹولز یہ ہیں:

• list_knowledge_bases
• list_documents
• search_knowledge
• get_document
• get_document_metadata

MCP process فائلیں upload، move، delete، یا folders manage نہیں کر سکتا۔ اس کی document access صرف ان دستاویزات تک محدود ہے جنہیں متعلقہ صارف پڑھنے کی اجازت رکھتا ہے۔

MCP dependencies انسٹال کریں

backend directory سے ایک مخصوص MCP virtual environment بنائیں:

cd backend
python -m venv .mcp-venv
.\.mcp-venv\Scripts\python.exe -m pip install -r requirements-mcp.txt

معیاری input اور output کے ذریعے MCP چلائیں

MCP process کو API جیسی database اور storage settings کے ساتھ configure کریں۔ login access token کو KB_MCP_TOKEN میں رکھیں، پھر server شروع کریں:

$env:PYTHONPATH = "."
$env:KB_MCP_TOKEN = "<access_token>"
.\.mcp-venv\Scripts\python.exe -m app.mcp_server

مقامی stdio clients کے لیے KB_MCP_TOKEN چھوڑا جا سکتا ہے۔ ایسی صورت میں agent کو صارف کے username اور password کے ساتھ ایک بار authenticate tool call کرنا ہوگا۔ اس کے نتیجے میں بننے والا قلیل مدتی session صرف MCP process کی memory میں موجود رہتا ہے۔

stdio MCP service میں عام print() calls شامل نہ کریں۔ Standard output میں protocol messages منتقل ہوتے ہیں، اس لیے diagnostics کو standard error میں لکھنا چاہیے۔

MCP smoke test چلائیں

$env:PYTHONPATH = "."
.\.mcp-venv\Scripts\python.exe scripts\mcp_stdio_smoke.py

Streamable HTTP کے ذریعے MCP ظاہر کریں

اسی MCP module کو شروع کرنے سے پہلے transport، listening address، port، path، اور stateless mode سیٹ کریں:

$env:PYTHONPATH = "."
$env:MCP_TRANSPORT = "streamable-http"
$env:MCP_HOST = "0.0.0.0"
$env:MCP_PORT = "8020"
$env:MCP_PATH = "/mcp"
$env:MCP_STATELESS_HTTP = "true"
.\.mcp-venv\Scripts\python.exe -m app.mcp_server

HTTPS reverse proxy configure کرنے کے بعد public endpoint https://your-domain/mcp ہو سکتا ہے۔ Remote clients کو Authorization: Bearer <access_token> بھیجنا چاہیے اور API connection جیسا ہی protected Bearer credential استعمال کرنا چاہیے۔

براؤزر صفحہ /mcp-token.html logged-in account کے لیے اس کا password پڑھے یا محفوظ کیے بغیر MCP Token حاصل کر سکتا ہے۔ Administrators صارفین کی status، roles، passwords، اور per-user MCP Token expiration policies manage کرنے کے لیے /admin.html استعمال کر سکتے ہیں، جن میں persistent long-lived Tokens بھی شامل ہیں۔

اعلیٰ سطحی operational tips

• API اور MCP settings کو یکساں رکھیں۔ دونوں services کو ایک ہی SQLite database اور storage paths کی طرف اشارہ کرنا چاہیے اور ایک ہی JWT secret استعمال کرنا چاہیے۔
• کم سے کم اجازت والی identities استعمال کریں۔ MCP agent اپنے token کے user کی قابلِ مطالعہ documents scope inherit کرتا ہے۔
• Bearer tokens محفوظ رکھیں۔ API یا MCP credentials کو source control، logs، یا عام console output میں نہ رکھیں۔
• stdio protocol برقرار رکھیں۔ MCP diagnostics کو standard output کے بجائے standard error پر بھیجیں۔
• Remote استعمال کے لیے HTTPS استعمال کریں۔ Streamable HTTP endpoint کو مقامی machine سے باہر ظاہر کرنے سے پہلے اسے HTTPS reverse proxy کے پیچھے رکھیں۔
• Phase 1 کی حدود یاد رکھیں۔ Docker Compose، PostgreSQL، اور object storage موجودہ runtime requirements نہیں بلکہ migration targets ہیں۔
• Ownership restrictions کا جائزہ لیں۔ Document editing، soft deletion، restoration، folder renaming، اور empty-folder deletion صرف owner انجام دے سکتا ہے۔
• Generated API documentation استعمال کریں۔ یہاں دکھائی گئی مثالوں سے آگے دستیاب request fields اور responses کا جائزہ لینے کا سب سے براہِ راست طریقہ /docs page ہے۔

نتیجہ

Knowledge Base Phase 1 مستند file organization، preview، retrieval، اور agent access کے لیے ایک عملی مقامی بنیاد فراہم کرتا ہے۔ صرف Python، SQLite، اور local storage کے ساتھ آپ service initialize کر سکتے ہیں، منظم document collections upload کر سکتے ہیں، folders اور metadata manage کر سکتے ہیں، اور local stdio یا remote Streamable HTTP MCP transport کے ذریعے read-only knowledge tools کو محفوظ طریقے سے ظاہر کر سکتے ہیں۔