antstudio 0.1.0__py3-none-any.whl

antstudio/__init__.py

@@ -0,0 +1,2 @@
+"""Ant Studio — Build. Run. Control."""
+__version__ = "0.1.0"

antstudio/backbone/__init__.py

@@ -0,0 +1,94 @@
+"""Backbone — runs on EVERY command automatically."""
+import time, json, os, platform
+from datetime import datetime
+from pathlib import Path
+
+HISTORY_DIR = Path.home() / ".antstudio"
+HISTORY_FILE = HISTORY_DIR / "history.json"
+
+class Backbone:
+    def __init__(self, command: str):
+        self.command = command
+        self.start_time = time.time()
+        self.quality_scores = {}
+        self._guard = None
+        self.guard_active = False
+
+    def start(self):
+        try:
+            from antguard import Guard
+            self._guard = Guard(detect_outbound=True, runtime=True)
+            self._guard.__enter__()
+            self.guard_active = True
+        except ImportError:
+            pass
+        return self
+
+    def evaluate(self, step: str, output, context: str = "") -> dict:
+        text = str(output) if output else ""
+        if not text or len(text) < 3:
+            score = {"score": 0.0, "passed": False, "method": "empty"}
+            self.quality_scores[step] = score
+            return score
+        try:
+            from llmevalkit import Evaluator
+            ev = Evaluator(provider="none", preset="rag", threshold=0.5)
+            r = ev.evaluate(answer=text, context=context)
+            score = {"score": r.overall_score, "passed": r.passed, "method": "llmevalkit"}
+        except ImportError:
+            s = min(len(text) / 200, 0.7)
+            if context:
+                cw = set(context.lower().split()[:30])
+                ow = set(text.lower().split())
+                s += len(cw & ow) / max(len(cw), 1) * 0.3
+            s = min(round(s, 3), 1.0)
+            score = {"score": s, "passed": s >= 0.5, "method": "fallback"}
+        self.quality_scores[step] = score
+        return score
+
+    def route(self, path: str) -> str:
+        try:
+            from adaptive_intelligence import AdaptiveEngine
+            return AdaptiveEngine().route(path)
+        except ImportError:
+            ext = Path(path).suffix.lower() if path else ""
+            if ext in (".pdf", ".docx", ".doc", ".txt"):
+                return "document"
+            elif ext in (".csv", ".xlsx", ".parquet"):
+                return "timeseries"
+            elif ext in (".png", ".jpg", ".jpeg"):
+                return "vision"
+            elif ext in (".wav", ".mp3"):
+                return "audio"
+            return "document"
+
+    def finish(self) -> dict:
+        elapsed = time.time() - self.start_time
+        data_left = False
+        risk = "LOW"
+        if self._guard and self.guard_active:
+            try:
+                self._guard.__exit__(None, None, None)
+                data_left = self._guard.did_data_leave()
+                risk = self._guard.risk_level().name
+            except Exception:
+                pass
+        report = {
+            "command": self.command, "timestamp": datetime.now().isoformat(),
+            "duration_seconds": round(elapsed, 2), "quality_scores": self.quality_scores,
+            "privacy": {"data_left_system": data_left, "risk_level": risk, "antguard_active": self.guard_active},
+            "platform": platform.system(),
+            "passed": all(s.get("passed", False) for s in self.quality_scores.values()) if self.quality_scores else True,
+        }
+        self._save_history(report)
+        return report
+
+    def _save_history(self, report):
+        try:
+            HISTORY_DIR.mkdir(parents=True, exist_ok=True)
+            history = json.loads(HISTORY_FILE.read_text()) if HISTORY_FILE.exists() else []
+            report["id"] = len(history) + 1
+            history.append(report)
+            HISTORY_FILE.write_text(json.dumps(history[-500:], indent=2))
+        except Exception:
+            pass

antstudio/cli.py

@@ -0,0 +1,157 @@
+"""Ant Studio CLI."""
+import click, json
+from pathlib import Path
+
+@click.group()
+@click.version_option("0.1.0", prog_name="antstudio")
+def cli():
+    """Ant Studio — Build. Run. Control."""
+    pass
+
+@cli.group()
+def doc():
+    """Document intelligence (DocQWise)."""
+    pass
+
+@doc.command()
+@click.argument("source")
+@click.option("--fields", "-f", default="vendor,date,amount,invoice_number")
+@click.option("--output", "-o", default="")
+@click.option("--output-db", default="", help="Database connection string")
+@click.option("--table", default="results")
+@click.option("--ocr", is_flag=True)
+@click.option("--engine", default="tesseract")
+@click.option("--model", default="default")
+@click.option("--threshold", default=0.7, type=float)
+@click.option("--extensions", default=".pdf,.docx,.txt,.xlsx,.csv,.png,.jpg,.jpeg")
+def extract(source, fields, output, output_db, table, ocr, engine, model, threshold, extensions):
+    """Extract fields from documents (PDF, DOCX, Excel, images, TXT)."""
+    from antstudio.doc.extract import run
+    run(source=source, fields=[f.strip() for f in fields.split(",")], model=model,
+        ocr=ocr, engine=engine, output=output, output_db=output_db, table=table,
+        threshold=threshold, extensions=extensions)
+
+@doc.command()
+@click.argument("source")
+@click.argument("question")
+@click.option("--rag", default="auto", type=click.Choice(["simple","graph","multimodal","auto"]))
+@click.option("--model", default="")
+@click.option("--system-prompt", default="")
+def ask(source, question, rag, model, system_prompt):
+    """Ask questions about documents."""
+    from antstudio.doc.ask import run
+    run(source=source, question=question, rag=rag, model=model, system_prompt=system_prompt)
+
+@cli.group()
+def ts():
+    """Temporal intelligence (WavQWise)."""
+    pass
+
+@ts.command()
+@click.argument("source")
+@click.option("--target", "-t", default="value")
+@click.option("--horizon", "-h", default=30, type=int)
+@click.option("--model", "-m", default="auto")
+@click.option("--output", "-o", default="")
+@click.option("--chart", default="")
+def forecast(source, target, horizon, model, output, chart):
+    """Forecast time-series data."""
+    from antstudio.ts.forecast import run
+    run(source=source, target=target, horizon=horizon, model=model, output=output, chart=chart)
+
+@ts.command()
+@click.argument("source")
+@click.option("--target", "-t", default="value")
+@click.option("--method", "-m", default="zscore")
+@click.option("--threshold", default=2.0, type=float)
+@click.option("--output", "-o", default="")
+def anomaly(source, target, method, threshold, output):
+    """Detect anomalies in time-series."""
+    from antstudio.ts.anomaly import run
+    run(source=source, target=target, method=method, threshold=threshold, output=output)
+
+@cli.command()
+@click.option("--limit", default=20, type=int)
+def runs(limit):
+    """List past pipeline runs (Kubeflow-style)."""
+    from antstudio.pipeline import list_runs
+    all_runs = list_runs(limit)
+    if not all_runs:
+        print("\n  No pipeline runs yet.\n"); return
+    print(f"\n  {'ID':<10} {'Pipeline':<40} {'Steps':<12} {'Status':<10} {'Time':<8}")
+    print(f"  {'─'*10} {'─'*40} {'─'*12} {'─'*10} {'─'*8}")
+    for r in all_runs:
+        s = r.get("summary", {})
+        print(f"  {r['run_id']:<10} {r['name'][:39]:<40} {s.get('success',0)}/{s.get('total',0)} passed  {r['status']:<10} {r['duration_seconds']:.1f}s")
+    print()
+
+@cli.command()
+@click.argument("run_id")
+def run_detail(run_id):
+    """Show detailed pipeline run (Kubeflow-style)."""
+    from antstudio.pipeline import get_run
+    data = get_run(run_id)
+    if not data:
+        print(f"\n  Run '{run_id}' not found.\n"); return
+    icons = {"success":"+","failed":"x","skipped":"-","pending":"."}
+    print(f"\n  Pipeline: {data['name']} [{data['run_id']}]")
+    print(f"  Status: {data['status'].upper()} | {data['duration_seconds']}s | {data['timestamp']}")
+    print(f"  {'='*60}")
+    for i, step in enumerate(data.get("steps", [])):
+        ic = icons.get(step["status"], "?")
+        dur = f"{step['duration_ms']}ms" if step.get("duration_ms") else ""
+        err = f" ({step['error'][:40]})" if step.get("error") else ""
+        print(f"  [{ic}] {step['name']:<30} {dur:>8}{err}")
+        if i < len(data["steps"]) - 1:
+            print(f"      |"); print(f"      v")
+    print(f"  {'='*60}")
+    s = data.get("summary", {})
+    print(f"  {s.get('success',0)}/{s.get('total',0)} steps passed\n")
+
+@cli.command()
+def history():
+    """Show execution history."""
+    hist_file = Path.home() / ".antstudio" / "history.json"
+    if not hist_file.exists():
+        print("  No runs yet."); return
+    runs = json.loads(hist_file.read_text())
+    print(f"\n  {'ID':<5} {'Command':<45} {'Quality':<10} {'Privacy':<12} {'Time':<8}")
+    print(f"  {'─'*5} {'─'*45} {'─'*10} {'─'*12} {'─'*8}")
+    for r in runs[-20:]:
+        qp = "PASS" if r.get("passed") else "FAIL"
+        dl = "LOCAL" if not r["privacy"]["data_left_system"] else "ALERT"
+        print(f"  {r['id']:<5} {r['command'][:44]:<45} {qp:<10} {dl:<12} {r['duration_seconds']:.1f}s")
+    print()
+
+@cli.command()
+def models():
+    """List available Ollama models."""
+    from antstudio.llm.ollama import list_models
+    mods = list_models()
+    if mods:
+        print(f"\n  Available models ({len(mods)}):")
+        for m in mods: print(f"    - {m}")
+    else:
+        print("\n  No models found. Run: ollama serve")
+    print()
+
+@cli.command()
+def status():
+    """System status."""
+    print(f"\n  Ant Studio v0.1.0")
+    libs = {"docqwise":0,"wavqwise":0,"sightrag":0,"sonarwise":0,"adaptive_intelligence":0,"llmevalkit":0,"antguard":0}
+    for lib in libs:
+        try: __import__(lib); libs[lib] = 1
+        except ImportError: pass
+    print(f"\n  Libraries:")
+    for lib, ok in libs.items():
+        print(f"    [{'+'if ok else '-'}] {lib}")
+    from antstudio.llm.ollama import list_models
+    mods = list_models()
+    print(f"\n  Ollama: {'connected ('+str(len(mods))+' models)' if mods else 'not running'}\n")
+
+def main():
+    cli()
+
+if __name__ == "__main__":
+    main()

antstudio/doc/__init__.py

@@ -0,0 +1 @@
+from antstudio.doc import extract, ask

antstudio/doc/ask.py

@@ -0,0 +1,114 @@
+"""Document Q&A — ask questions with RAG modes."""
+from typing import Optional
+from antstudio.backbone import Backbone
+from antstudio.io.reader import read_input
+from antstudio.doc.loader import load_text
+from antstudio.llm.ollama import ask as ollama_ask
+
+class Answer:
+    def __init__(self, text: str, confidence: float, sources: list, quality: dict, audit: dict):
+        self.text = text
+        self.confidence = confidence
+        self.sources = sources
+        self.quality = quality
+        self.audit = audit
+    def __repr__(self):
+        return f"Answer(confidence={self.confidence}, len={len(self.text)})"
+
+def run(source: str, question: str, rag: str = "auto", model: str = "",
+        system_prompt: str = "", verbose: bool = True, **kwargs) -> Answer:
+
+    bb = Backbone(f"doc ask {source}")
+    bb.start()
+
+    if verbose:
+        print(f"\n  Ant Studio v0.1.0 | DocQWise + Ollama + llmevalkit + AntGuard\n")
+
+    items = read_input(source=source, extensions=".pdf,.docx,.txt")
+    if not items:
+        audit = bb.finish()
+        return Answer("No documents found.", 0, [], {}, audit)
+
+    # Load all texts
+    texts = []
+    for fname, raw, fpath in items:
+        t = load_text(raw, fname)
+        if t and not t.startswith("["):
+            texts.append({"text": t, "source": fname})
+
+    if verbose:
+        print(f"  [1/4] Loading {'.' * 21} {len(texts)} documents")
+
+    # Route RAG mode
+    if rag == "auto":
+        rag = "graph" if len(texts) > 1 else "simple"
+        route = bb.route(source)
+        if verbose:
+            print(f"  [2/4] Routing {'.' * 21} {rag} RAG (adaptive: {route})")
+
+    # Build context
+    if rag == "graph":
+        context = _graph_rag(texts, question)
+    else:
+        context = _simple_rag(texts, question)
+
+    # Generate answer
+    sys = system_prompt or "You are a precise document analyst. Answer only from the provided evidence."
+    prompt = f"Evidence:\n{context[:4000]}\n\nQuestion: {question}\n\nAnswer:"
+    answer_text = ollama_ask(prompt, system=sys, model=model)
+
+    if verbose:
+        print(f"  [3/4] Reasoning {'.' * 19} {len(answer_text)} chars")
+
+    # Quality check
+    q = bb.evaluate("answer", answer_text, context[:1000])
+    audit = bb.finish()
+
+    # Find sources
+    sources = []
+    for t in texts:
+        for sent in t["text"].split(".")[:20]:
+            if any(w in sent.lower() for w in question.lower().split()[:3]):
+                sources.append(f"{t['source']}: {sent.strip()[:80]}")
+                if len(sources) >= 3:
+                    break
+
+    confidence = q.get("score", 0.5)
+
+    if verbose:
+        dl = audit["privacy"]["data_left_system"]
+        print(f"  [4/4] Audit {'.' * 23} data_left: {'YES' if dl else 'NO'}")
+        print(f"\n  Answer: {answer_text[:200]}{'...' if len(answer_text) > 200 else ''}")
+        print(f"  Confidence: {confidence:.0%}")
+        print(f"\n  Done in {audit['duration_seconds']}s\n")
+
+    return Answer(answer_text, confidence, sources, bb.quality_scores, audit)
+
+
+def _simple_rag(texts: list, question: str) -> str:
+    all_text = "\n\n---\n\n".join(t["text"][:2000] for t in texts[:5])
+    return all_text
+
+def _graph_rag(texts: list, question: str) -> str:
+    """Graph-based retrieval — find connected evidence."""
+    try:
+        from antstudio.doc.extract import _extract_regex
+        entities = set()
+        for t in texts:
+            fields = _extract_regex(t["text"], ["vendor", "invoice_number", "amount"])
+            for v in fields.get("fields", {}).values():
+                if v:
+                    entities.add(v.lower())
+
+        # Find sentences mentioning shared entities
+        relevant = []
+        q_words = set(question.lower().split())
+        for t in texts:
+            for sent in t["text"].split("."):
+                sent_lower = sent.lower()
+                if any(e in sent_lower for e in entities) or any(w in sent_lower for w in q_words):
+                    relevant.append(f"[{t['source']}] {sent.strip()}")
+
+        return "\n".join(relevant[:30]) if relevant else _simple_rag(texts, question)
+    except Exception:
+        return _simple_rag(texts, question)

antstudio/doc/extract.py

@@ -0,0 +1,147 @@
+"""Document extraction with pipeline tracking."""
+import re
+from typing import List, Optional
+from antstudio.backbone import Backbone
+from antstudio.pipeline import Pipeline
+from antstudio.io.reader import read_input
+from antstudio.io.writer import Results
+from antstudio.doc.loader import load_text
+
+def run(source: str = "", fields: Optional[List[str]] = None, model: str = "default",
+        ocr: bool = False, engine: str = "tesseract", schema: str = "",
+        db: str = "", query: str = "", url: str = "",
+        output: str = "", output_db: str = "", table: str = "results",
+        threshold: float = 0.7, verbose: bool = True, **kwargs) -> Results:
+
+    if fields is None:
+        fields = ["vendor", "date", "amount", "invoice_number"]
+
+    bb = Backbone(f"doc extract {source}")
+    bb.start()
+
+    pipe = Pipeline(f"Document Extraction: {source}")
+    pipe.start()
+
+    if verbose:
+        print(f"\n  Ant Studio v0.1.0 | DocQWise + llmevalkit + AntGuard\n")
+
+    # Step 1: Read input
+    s1 = pipe.add_step("Scan Input", "file_input", {"source": source, "extensions": kwargs.get("extensions", ".pdf,.docx,.txt")})
+    s1.start()
+    items = read_input(source=source, db=db, query=query, url=url,
+                       extensions=kwargs.pop("extensions", ".pdf,.docx,.txt,.doc,.xlsx,.csv,.png,.jpg,.jpeg,.bmp,.tiff"))
+    if not items:
+        s1.fail(f"No files found: {source}")
+        pipe.finish()
+        if verbose: pipe.print_status()
+        return Results([], audit=bb.finish())
+    s1.succeed({"file_count": len(items)}, f"{len(items)} files found")
+    if verbose:
+        print(f"  [1/4] Scanning {'.' * 20} {len(items)} files found")
+
+    # Step 2: Extract
+    s2 = pipe.add_step("Extract Fields", "docqwise_extract", {"fields": fields, "model": model, "ocr": ocr})
+    s2.start()
+    all_rows = []
+    for i, (fname, raw, fpath) in enumerate(items):
+        text = load_text(raw, fname)
+        if not text or text.startswith("["):
+            all_rows.append({"_source": fname, "_error": text or "empty", "_confidence": 0, "_threshold": threshold})
+            continue
+        extracted = _extract_docqwise(text, fields, model)
+        if not extracted:
+            extracted = _extract_regex(text, fields)
+        row = {"_source": fname, "_path": fpath}
+        row.update(extracted.get("fields", {}))
+        row["_confidence"] = extracted.get("confidence", 0.0)
+        row["_threshold"] = threshold
+        field_text = " ".join(str(v) for v in extracted.get("fields", {}).values() if v)
+        q = bb.evaluate(fname, field_text, text[:500])
+        all_rows.append(row)
+    s2.succeed({"rows": len(all_rows)}, f"{len(all_rows)}/{len(items)} complete")
+    if verbose:
+        print(f"  [2/4] Extracting {'.' * 18} {len(all_rows)}/{len(items)} complete")
+
+    # Step 3: Quality
+    s3 = pipe.add_step("Quality Check", "llmevalkit", {"threshold": threshold})
+    s3.start()
+    passed = sum(1 for r in all_rows if r.get("_confidence", 0) >= threshold)
+    flagged = len(all_rows) - passed
+    s3.quality_score = {"score": passed / max(len(all_rows), 1), "passed": flagged == 0}
+    s3.succeed({"passed": passed, "flagged": flagged}, f"{passed} passed, {flagged} flagged")
+    if verbose:
+        print(f"  [3/4] Quality (llmevalkit) {'.' * 10} {passed} passed, {flagged} flagged")
+
+    # Step 4: Privacy audit
+    s4 = pipe.add_step("Privacy Audit", "antguard", {})
+    s4.start()
+    audit = bb.finish()
+    dl = audit["privacy"]["data_left_system"]
+    risk = audit["privacy"]["risk_level"]
+    s4.succeed({"data_left": dl, "risk": risk}, f"data_left: {'YES' if dl else 'NO'} | risk: {risk}")
+    if verbose:
+        print(f"  [4/4] Privacy (AntGuard) {'.' * 11} data_left: {'YES' if dl else 'NO'} | risk: {risk}")
+
+    pipe.finish()
+    results = Results(all_rows, quality=bb.quality_scores, audit=audit)
+
+    # Output
+    if output:
+        # Step 5: Save output
+        s5 = pipe.add_step("Save Output", "export", {"path": output})
+        s5.start()
+        results.save(output)
+        s5.succeed({"path": output, "rows": results.count})
+        if verbose: print(f"\n  Results saved: {output} ({results.count} rows)")
+
+    if output_db:
+        results.to_database(output_db, table=table)
+
+    if flagged > 0 and output:
+        flagged_path = output.replace(".", "_flagged.")
+        results.flagged.save(flagged_path)
+        if verbose: print(f"  Flagged items: {flagged_path} ({flagged} rows)")
+
+    # Print pipeline view
+    if verbose:
+        pipe.print_status()
+
+    return results
+
+
+def _extract_docqwise(text, fields, model):
+    try:
+        from docqwise import DocQWise
+        dq = DocQWise(model=model)
+        result = dq.extract(text, fields=fields)
+        return {"fields": result.fields, "confidence": result.confidence}
+    except ImportError:
+        return {}
+    except Exception:
+        return {}
+
+def _extract_regex(text, fields):
+    extracted = {}
+    patterns = {
+        "vendor": [r"(?:vendor|supplier|from|company)[:\s]+([A-Z][A-Za-z\s&.,]+?)(?:\n|$)", r"^([A-Z][A-Z\s&.,]{3,30})\s*(?:LLC|Inc|Corp|Ltd)?"],
+        "date": [r"(?:date|dated|invoice date)[:\s]+(\d{1,2}[/-]\d{1,2}[/-]\d{2,4})", r"(\d{1,2}[/-]\d{1,2}[/-]\d{2,4})"],
+        "amount": [r"(?:total|amount|balance|due)[:\s]*\$?([\d,]+\.?\d*)", r"\$\s*([\d,]+\.?\d*)"],
+        "invoice_number": [r"(?:invoice|inv|invoice no|invoice #)[:\s#]*([A-Za-z0-9-]+)"],
+        "gst": [r"(?:gst|gstin|tax id)[:\s]*([A-Z0-9]{10,20})"],
+        "due_date": [r"(?:due date|payment due|due)[:\s]+(\d{1,2}[/-]\d{1,2}[/-]\d{2,4})"],
+    }
+    found = 0
+    for field in fields:
+        key = field.strip().lower().replace(" ", "_")
+        for pk, pats in patterns.items():
+            if key == pk or key.replace("_", "") == pk.replace("_", ""):
+                for pat in pats:
+                    m = re.search(pat, text, re.IGNORECASE | re.MULTILINE)
+                    if m:
+                        extracted[field.strip()] = m.group(1).strip()
+                        found += 1
+                        break
+                break
+        if field.strip() not in extracted:
+            extracted[field.strip()] = ""
+    return {"fields": extracted, "confidence": round(found / max(len(fields), 1), 3)}

antstudio/doc/loader.py

@@ -0,0 +1,68 @@
+"""Load ANY file type — PDF, DOCX, Excel, CSV, images, TXT."""
+
+def load_text(raw_bytes: bytes, filename: str) -> str:
+    ext = filename.lower().rsplit(".", 1)[-1] if "." in filename else ""
+
+    if ext == "pdf":
+        return _load_pdf(raw_bytes)
+    elif ext == "docx":
+        return _load_docx(raw_bytes)
+    elif ext in ("xlsx", "xls"):
+        return _load_excel(raw_bytes, filename)
+    elif ext == "csv":
+        return raw_bytes.decode("utf-8", errors="ignore")
+    elif ext in ("png", "jpg", "jpeg", "bmp", "tiff", "webp"):
+        return _load_image_ocr(raw_bytes, filename)
+    elif ext in ("txt", "md", "json", "xml", "html", "log", "yaml", "yml"):
+        return raw_bytes.decode("utf-8", errors="ignore")
+    else:
+        try:
+            return raw_bytes.decode("utf-8", errors="ignore")
+        except Exception:
+            return f"[Binary file: {filename}]"
+
+def _load_pdf(raw_bytes):
+    try:
+        import fitz
+        doc = fitz.open(stream=raw_bytes, filetype="pdf")
+        return "\n".join(page.get_text() for page in doc)
+    except ImportError:
+        try:
+            from docqwise import DocQWise
+            return DocQWise().load_pdf(raw_bytes)
+        except ImportError:
+            return "[pip install PyMuPDF]"
+
+def _load_docx(raw_bytes):
+    try:
+        import docx, io
+        doc = docx.Document(io.BytesIO(raw_bytes))
+        return "\n".join(p.text for p in doc.paragraphs)
+    except ImportError:
+        return "[pip install python-docx]"
+
+def _load_excel(raw_bytes, filename):
+    try:
+        import pandas as pd, io
+        df = pd.read_excel(io.BytesIO(raw_bytes))
+        return df.to_string(index=False)
+    except ImportError:
+        return "[pip install openpyxl pandas]"
+
+def _load_image_ocr(raw_bytes, filename):
+    try:
+        import pytesseract
+        from PIL import Image
+        import io
+        img = Image.open(io.BytesIO(raw_bytes))
+        return pytesseract.image_to_string(img)
+    except ImportError:
+        try:
+            import easyocr, io, numpy as np
+            from PIL import Image
+            img = np.array(Image.open(io.BytesIO(raw_bytes)))
+            reader = easyocr.Reader(["en"])
+            results = reader.readtext(img)
+            return "\n".join(r[1] for r in results)
+        except ImportError:
+            return f"[Image: {filename} — pip install pytesseract Pillow OR easyocr]"

antstudio/io/reader.py

@@ -0,0 +1,56 @@
+"""Universal input reader."""
+import os
+from pathlib import Path
+from typing import List, Tuple
+
+def read_input(source: str = "", db: str = "", query: str = "",
+               azure: str = "", s3: str = "", container: str = "",
+               path: str = "", url: str = "", extensions: str = ".pdf,.docx,.txt,.csv",
+               recursive: bool = True, max_files: int = 0) -> List[Tuple[str, bytes, str]]:
+    results = []
+    exts = [e.strip().lower() for e in extensions.split(",") if e.strip()]
+
+    if source and os.path.isfile(source):
+        with open(source, "rb") as f:
+            return [(os.path.basename(source), f.read(), os.path.abspath(source))]
+
+    if source and os.path.isdir(source):
+        files = []
+        if recursive:
+            for root, _, fns in os.walk(source):
+                for fn in fns:
+                    if any(fn.lower().endswith(e) for e in exts):
+                        files.append(os.path.join(root, fn))
+        else:
+            files = [os.path.join(source, fn) for fn in os.listdir(source)
+                     if os.path.isfile(os.path.join(source, fn)) and any(fn.lower().endswith(e) for e in exts)]
+        if max_files > 0:
+            files = files[:max_files]
+        for fp in files:
+            try:
+                with open(fp, "rb") as f:
+                    results.append((os.path.basename(fp), f.read(), os.path.abspath(fp)))
+            except Exception:
+                pass
+        return results
+
+    if db:
+        try:
+            import sqlalchemy, pandas as pd
+            engine = sqlalchemy.create_engine(db)
+            df = pd.read_sql(query or "SELECT * FROM documents", engine)
+            import json
+            data = json.dumps(df.to_dict("records")).encode()
+            return [("db_query.json", data, db)]
+        except Exception as e:
+            print(f"  DB error: {e}")
+
+    if url:
+        try:
+            import httpx
+            resp = httpx.get(url, follow_redirects=True, timeout=30)
+            return [(url.split("/")[-1] or "download", resp.content, url)]
+        except Exception as e:
+            print(f"  URL error: {e}")
+
+    return results