feat: services package

services/featherless_provider.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+import json
+import urllib.request
+
+FEATHERLESS_API_BASE = "https://api.featherless.ai/v1"
+
+def generate(model_id: str, prompt: str, system: str = "",
+             api_key: str = "", max_tokens: int = 1024, temperature: float = 0.3) -> str:
+    """Featherless.ai (OpenAI-compatible) — Nemotron reasoning tasks."""
+    url = f"{FEATHERLESS_API_BASE}/chat/completions"
+    messages = []
+    if system:
+        messages.append({"role": "system", "content": system})
+    messages.append({"role": "user", "content": prompt})
+    payload = {"model": model_id, "messages": messages,
+               "max_tokens": max_tokens, "temperature": temperature}
+    data = json.dumps(payload).encode("utf-8")
+    headers = {"Content-Type": "application/json",
+               "Authorization": f"Bearer {api_key}"}
+    req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+    with urllib.request.urlopen(req, timeout=120) as resp:
+        result = json.loads(resp.read().decode("utf-8"))
+    return result["choices"][0]["message"]["content"]

services/hf_provider.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+import json
+import urllib.request
+
+HF_API_BASE = "https://api-inference.huggingface.co/models"
+
+def generate(model_id: str, prompt: str, system: str = "",
+             api_key: str = "", max_tokens: int = 1024, temperature: float = 0.3) -> str:
+    """Text generation — used for MiniCPM concept extraction and Tiny Aya translation."""
+    url = f"{HF_API_BASE}/{model_id}"
+    messages = []
+    if system:
+        messages.append({"role": "system", "content": system})
+    messages.append({"role": "user", "content": prompt})
+    payload = {"inputs": {"messages": messages},
+               "parameters": {"max_new_tokens": max_tokens, "temperature": temperature}}
+    data = json.dumps(payload).encode("utf-8")
+    headers = {"Content-Type": "application/json"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+    with urllib.request.urlopen(req, timeout=60) as resp:
+        result = json.loads(resp.read().decode("utf-8"))
+    if isinstance(result, list): return result[0].get("generated_text", str(result[0]))
+    if isinstance(result, dict): return result.get("generated_text", result.get("text", str(result)))
+    return str(result)
+
+def vision_generate(model_id: str, image_b64: str, prompt: str,
+                    api_key: str = "", max_tokens: int = 1024) -> str:
+    """Vision+language — MiniCPM-V for OCR and visual understanding."""
+    url = f"{HF_API_BASE}/{model_id}"
+    payload = {"inputs": {"image": image_b64, "question": prompt},
+               "parameters": {"max_new_tokens": max_tokens}}
+    data = json.dumps(payload).encode("utf-8")
+    headers = {"Content-Type": "application/json"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+    with urllib.request.urlopen(req, timeout=90) as resp:
+        result = json.loads(resp.read().decode("utf-8"))
+    if isinstance(result, list): return str(result[0])
+    if isinstance(result, dict): return result.get("generated_text", result.get("text", str(result)))
+    return str(result)
+
+def transcribe(model_id: str, audio_bytes: bytes, api_key: str = "") -> str:
+    """ASR — Whisper via HuggingFace for voice input."""
+    url = f"{HF_API_BASE}/{model_id}"
+    headers = {"Content-Type": "audio/wav"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    req = urllib.request.Request(url, data=audio_bytes, headers=headers, method="POST")
+    with urllib.request.urlopen(req, timeout=60) as resp:
+        result = json.loads(resp.read().decode("utf-8"))
+    return result.get("text", "")

services/ingestion.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+import os
+import base64
+from typing import Tuple
+
+def load_file(path: str) -> Tuple[str, str]:
+    """
+    Returns (text, image_b64).
+    - text: extracted text layer (empty if image-only)
+    - image_b64: base64 image (empty if plain text)
+    Callers decide which to use. For PDF: both may be non-empty.
+    """
+    if not os.path.exists(path):
+        raise FileNotFoundError(f"File not found: {path}")
+    ext = os.path.splitext(path)[1].lower()
+    if ext in {".txt", ".md"}:
+        return _read_text(path), ""
+    if ext == ".pdf":
+        return _pdf_text(path), _pdf_first_page_b64(path)
+    if ext in {".png", ".jpg", ".jpeg", ".webp"}:
+        return "", _image_b64(path)
+    return _read_text(path), ""
+
+def _read_text(path: str) -> str:
+    with open(path, "r", encoding="utf-8", errors="replace") as f:
+        return f.read()
+
+def _pdf_text(path: str) -> str:
+    try:
+        import fitz
+        doc = fitz.open(path)
+        text = "\n".join(page.get_text("text") for page in doc).strip()
+        doc.close()
+        return text
+    except Exception:
+        return ""
+
+def _pdf_first_page_b64(path: str) -> str:
+    try:
+        import fitz
+        doc = fitz.open(path)
+        pix = doc[0].get_pixmap(dpi=150)
+        b64 = base64.b64encode(pix.tobytes("png")).decode("utf-8")
+        doc.close()
+        return b64
+    except Exception:
+        return ""
+
+def _image_b64(path: str) -> str:
+    with open(path, "rb") as f:
+        return base64.b64encode(f.read()).decode("utf-8")

services/json_parser.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+import json
+import re
+
+def extract_json(text: str) -> dict:
+    """
+    Robustly extract JSON from LLM response.
+    Handles: raw JSON, markdown code fences, leading/trailing prose.
+    """
+    text = text.strip()
+    text = re.sub(r"```(?:json)?\s*", "", text).replace("```", "")
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+    for pattern in (r"\{[\s\S]*\}", r"\[[\s\S]*\]"):
+        match = re.search(pattern, text)
+        if match:
+            try:
+                return json.loads(match.group())
+            except json.JSONDecodeError:
+                pass
+    raise ValueError(f"No valid JSON found in response. First 200 chars: {text[:200]}")

services/model_router.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+from services import hf_provider, featherless_provider
+
+class ModelRouter:
+    """
+    Routes tasks to the correct model and provider.
+    understand() → MiniCPM-V (HF) — all document tasks
+    reason()     → Nemotron 4B (Featherless) — all reasoning tasks
+    translate()  → Tiny Aya (HF) — multilingual
+    transcribe() → Whisper (HF) — speech to text
+    """
+    def __init__(self, ocr_model: str, reasoning_model: str,
+                 multilingual_model: str, speech_model: str,
+                 hf_api_key: str = "", featherless_api_key: str = "",
+                 max_tokens: int = 1024, temperature: float = 0.3):
+        self._ocr_model = ocr_model
+        self._reason_model = reasoning_model
+        self._multi_model = multilingual_model
+        self._speech_model = speech_model
+        self._hf_key = hf_api_key
+        self._fl_key = featherless_api_key
+        self._max_tokens = max_tokens
+        self._temperature = temperature
+
+    def understand(self, prompt: str, image_b64: str = "") -> str:
+        """MiniCPM-V via HuggingFace — OCR, diagram reading, concept extraction."""
+        if image_b64:
+            return hf_provider.vision_generate(
+                self._ocr_model, image_b64, prompt,
+                self._hf_key, self._max_tokens)
+        return hf_provider.generate(
+            self._ocr_model, prompt, api_key=self._hf_key,
+            max_tokens=self._max_tokens, temperature=self._temperature)
+
+    def reason(self, prompt: str, system: str = "") -> str:
+        """Nemotron 3 Nano 4B via Featherless — quests, questions, tutor."""
+        return featherless_provider.generate(
+            self._reason_model, prompt, system,
+            self._fl_key, self._max_tokens, self._temperature)
+
+    def translate(self, prompt: str, system: str = "") -> str:
+        """Tiny Aya 3.3B via HuggingFace — multilingual explanations."""
+        return hf_provider.generate(
+            self._multi_model, prompt, system,
+            self._hf_key, self._max_tokens, self._temperature)
+
+    def transcribe(self, audio_bytes: bytes) -> str:
+        """Whisper via HuggingFace — speech to text."""
+        return hf_provider.transcribe(self._speech_model, audio_bytes, self._hf_key)