raqa 0.0.1__tar.gz

raqa-0.0.1/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: raqa
+Version: 0.0.1
+Author-email: Jordi Carrera Ventura <jordi.carrera.ventura@gmail.com>
+Project-URL: GitHub repository, https://github.com
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: build
+Requires-Dist: faiss-cpu
+Requires-Dist: numpy
+Requires-Dist: openai
+Requires-Dist: python-frontmatter
+Requires-Dist: sentence-transformers
+Requires-Dist: tqdm
+Requires-Dist: typer[all]
+Requires-Dist: twine
+Dynamic: license-file
+
+# RAQA
+
+**R**etrieval-**A**ugmented **Q**uestion-**A**nswering
+
+Retrieval-augmented, pip-installable, CLI-based question answering over arbitrary document collections.
+
+# Usage
+
+## Installation
+
+```
+pip install raqa
+```
+
+**Locally**
+
+`pip install -e .`
+
+## Run
+
+### BASH via Python interpreter
+
+1. Build DB
+
+    `python cli.py build --path ./docs`
+
+2. Chat
+
+    `python cli.py chat`
+
+3. One-shot retrieval
+
+    `python cli.py search "what is retrieval augmented generation?"`
+
+4. Rebuild and chat
+
+    `python cli.py rebuild-and-chat`
+
+5. Get stats
+
+    `python cli.py stats`
+
+### BASH natively
+
+```
+raqa build --path ./markdown_files
+raqa chat
+raqa search "what is RAG?"
+raqa stats
+raqa rebuild-and-chat
+```
+
+
+## Python
+
+### Build database
+
+```
+from db import VectorDB
+from config import MARKDOWN_ROOT
+
+db = VectorDB()
+db.build(MARKDOWN_ROOT)
+```
+
+### Run
+
+```
+from agent import RAGAgent
+
+agent = RAGAgent()
+agent.chat()
+```
+
+
+## Build instructions
+
+Next steps:
+
+1. If any changes are made, update `pyproject.toml`.
+2. Building the package before uploading:
+    `cd raqa; python -m build`.
+3. Upload the package to pypi:
+    `python -m twine upload --repository {pypi|testpypi} dist/*`
+
+## Next steps
+
+### Real tool-calling (instead of implicit RAG)
+
+Define OpenAI tool:
+
+```
+{
+  "name": "search_docs",
+  "description": "...",
+  "parameters": { "query": "string" }
+}
+```
+
+### Hybrid search
+
+Combine BM25 (rank-bm25) + embeddings

raqa-0.0.1/README.md

@@ -0,0 +1,102 @@
+# RAQA
+
+**R**etrieval-**A**ugmented **Q**uestion-**A**nswering
+
+Retrieval-augmented, pip-installable, CLI-based question answering over arbitrary document collections.
+
+# Usage
+
+## Installation
+
+```
+pip install raqa
+```
+
+**Locally**
+
+`pip install -e .`
+
+## Run
+
+### BASH via Python interpreter
+
+1. Build DB
+
+    `python cli.py build --path ./docs`
+
+2. Chat
+
+    `python cli.py chat`
+
+3. One-shot retrieval
+
+    `python cli.py search "what is retrieval augmented generation?"`
+
+4. Rebuild and chat
+
+    `python cli.py rebuild-and-chat`
+
+5. Get stats
+
+    `python cli.py stats`
+
+### BASH natively
+
+```
+raqa build --path ./markdown_files
+raqa chat
+raqa search "what is RAG?"
+raqa stats
+raqa rebuild-and-chat
+```
+
+
+## Python
+
+### Build database
+
+```
+from db import VectorDB
+from config import MARKDOWN_ROOT
+
+db = VectorDB()
+db.build(MARKDOWN_ROOT)
+```
+
+### Run
+
+```
+from agent import RAGAgent
+
+agent = RAGAgent()
+agent.chat()
+```
+
+
+## Build instructions
+
+Next steps:
+
+1. If any changes are made, update `pyproject.toml`.
+2. Building the package before uploading:
+    `cd raqa; python -m build`.
+3. Upload the package to pypi:
+    `python -m twine upload --repository {pypi|testpypi} dist/*`
+
+## Next steps
+
+### Real tool-calling (instead of implicit RAG)
+
+Define OpenAI tool:
+
+```
+{
+  "name": "search_docs",
+  "description": "...",
+  "parameters": { "query": "string" }
+}
+```
+
+### Hybrid search
+
+Combine BM25 (rank-bm25) + embeddings

raqa-0.0.1/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=75.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "raqa"
+version = "0.0.1"
+authors = [
+  { name="Jordi Carrera Ventura", email="jordi.carrera.ventura@gmail.com" },
+]
+description = ""
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+  "build",
+  "faiss-cpu",
+  "numpy",
+  "openai",
+  "python-frontmatter",
+  "sentence-transformers",
+  "tqdm",
+  "typer[all]",
+  "twine"
+]
+
+[project.urls]
+"GitHub repository" = "https://github.com"
+
+[project.scripts]
+raqa = "raqa.cli:app"

raqa-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

raqa-0.0.1/src/raqa/agent.py

@@ -0,0 +1,56 @@
+from openai import OpenAI
+
+from .db import VectorDB
+from .utils import get_openai_key
+
+class RAGAgent:
+    def __init__(self):
+        self.db = VectorDB()
+        self.db.load()
+
+        api_key = get_openai_key()
+        self.client = OpenAI(api_key=api_key)
+
+    def retrieve(self, query: str):
+        results = self.db.search(query)
+        filtered = self.db.nucleus_filter(results)
+
+        context = "\n\n".join(
+            f"[{r['data']['source']}]\n{r['data']['text']}"
+            for r in filtered
+        )
+
+        return context
+
+    def chat(self):
+        print("💬 RAG Agent ready. Type 'exit' to quit.")
+
+        messages = [{"role": "system", "content": "You are a helpful assistant."}]
+
+        while True:
+            user_input = input("\nYou: ")
+            if user_input.lower() in ("exit", "quit"):
+                break
+
+            context = self.retrieve(user_input)
+
+            augmented_prompt = f"""
+Use the context below if relevant:
+
+{context}
+
+User question:
+{user_input}
+"""
+
+            messages.append({"role": "user", "content": augmented_prompt})
+
+            response = self.client.chat.completions.create(
+                model="gpt-4.1-mini",
+                messages=messages
+            )
+
+            reply = response.choices[0].message.content
+            messages.append({"role": "assistant", "content": reply})
+
+            print("\nAssistant:", reply)

raqa-0.0.1/src/raqa/cli.py

@@ -0,0 +1,105 @@
+import typer
+from typing import Optional
+
+from .db import VectorDB
+from .agent import RAGAgent
+from .config import MARKDOWN_ROOT
+
+app = typer.Typer(help="📚 Markdown RAG CLI")
+
+
+# ---------------------------
+# BUILD DATABASE
+# ---------------------------
+@app.command()
+def build(
+    path: str = typer.Option(
+        MARKDOWN_ROOT,
+        help="Path to markdown folder"
+    )
+):
+    """
+    Build vector database from markdown files.
+    """
+    db = VectorDB()
+    db.build(path)
+
+    typer.secho("✅ Database built successfully.", fg=typer.colors.GREEN)
+
+
+# ---------------------------
+# SEARCH ONLY (DEBUG TOOL)
+# ---------------------------
+@app.command()
+def search(
+    query: str = typer.Argument(..., help="Search query"),
+    k: int = typer.Option(10, help="Top K results")
+):
+    """
+    Run retrieval without LLM (debugging).
+    """
+    db = VectorDB()
+    db.load()
+
+    results = db.search(query, k=k)
+
+    typer.secho("\n🔎 Raw Results:\n", fg=typer.colors.BLUE)
+
+    for i, r in enumerate(results):
+        typer.echo(f"\n--- Result {i+1} ---")
+        typer.echo(f"Score: {r['score']:.4f}")
+        typer.echo(f"Source: {r['data']['source']}")
+        typer.echo(r["data"]["text"][:500])
+
+
+# ---------------------------
+# CHAT (MAIN ENTRYPOINT)
+# ---------------------------
+@app.command()
+def chat():
+    """
+    Start conversational RAG agent.
+    """
+    agent = RAGAgent()
+    agent.chat()
+
+
+# ---------------------------
+# REBUILD + CHAT (CONVENIENCE)
+# ---------------------------
+@app.command()
+def rebuild_and_chat(
+    path: str = typer.Option(
+        MARKDOWN_ROOT,
+        help="Markdown folder"
+    )
+):
+    """
+    Rebuild database and immediately start chat.
+    """
+    db = VectorDB()
+    db.build(path)
+
+    typer.secho("\n🚀 Starting chat...\n", fg=typer.colors.GREEN)
+
+    agent = RAGAgent()
+    agent.chat()
+
+
+# ---------------------------
+# INSPECT DB
+# ---------------------------
+@app.command()
+def stats():
+    """
+    Show database stats.
+    """
+    db = VectorDB()
+    db.load()
+
+    typer.echo("📊 Database Stats:")
+    typer.echo(f"Total chunks: {len(db.metadata)}")
+
+
+if __name__ == "__main__":
+    app()

raqa-0.0.1/src/raqa/config.py

@@ -0,0 +1,24 @@
+from pathlib import Path
+
+# User folder for raqa configs
+HOME = Path.home()
+RAQA_HOME = HOME / ".raqa"
+
+# OpenAI credential file
+ENV_FILE = RAQA_HOME / "env"
+
+# Database folder (moved from project data)
+DATA_DIR = RAQA_HOME / "data"
+
+# Embeddings & chunk config
+EMBEDDING_MODEL = "joeddav/xlm-roberta-large-xnli"
+CHUNK_WINDOW = 3
+TOP_K = 50
+SIMILARITY_RADIUS = 0.4
+
+# Default markdown folder (can override via CLI)
+MARKDOWN_ROOT = "./markdown_files"
+
+# Ensure directories exist
+RAQA_HOME.mkdir(parents=True, exist_ok=True)
+DATA_DIR.mkdir(parents=True, exist_ok=True)

raqa-0.0.1/src/raqa/db.py

@@ -0,0 +1,119 @@
+import os
+import json
+from pathlib import Path
+
+import faiss
+import numpy as np
+import frontmatter
+from sentence_transformers import SentenceTransformer
+
+from .utils import split_sentences, window_chunks
+from .config import *
+
+os.environ["TOKENIZERS_PARALLELISM"] = True
+
+
+class VectorDB:
+    def __init__(self):
+        self.model = SentenceTransformer(EMBEDDING_MODEL)
+        self.index = None
+        self.metadata = []
+
+    def ingest_markdown(self, root_dir: str):
+        all_chunks = []
+
+        for path in Path(root_dir).rglob("*.md"):
+            with open(path, "r", encoding="utf-8") as f:
+                post = frontmatter.load(f)
+
+            text = post.content
+            meta = post.metadata
+
+            sentences = split_sentences(text)
+            chunks = window_chunks(sentences, CHUNK_WINDOW)
+
+            for c in chunks:
+                all_chunks.append({
+                    "text": c["text"],
+                    "source": str(path),
+                    "meta": meta,
+                    "position": c["index"]
+                })
+
+        return all_chunks
+
+    def build(self, root_dir: str):
+        print("📥 Ingesting markdown...")
+        chunks = self.ingest_markdown(root_dir)
+
+        print("🧠 Encoding...")
+        texts = [c["text"] for c in chunks]
+        embeddings = self.model.encode(texts, show_progress_bar=True)
+
+        dim = embeddings.shape[1]
+        # self.index = faiss.IndexFlatIP(dim)
+        self.index = faiss.IndexHNSWFlat(dim, 32)
+
+        # normalize for cosine similarity
+        faiss.normalize_L2(embeddings)
+        self.index.add(embeddings)
+
+        self.metadata = chunks
+
+        self.save()
+
+    def save(self):
+        DATA_DIR.mkdir(exist_ok=True)
+
+        faiss.write_index(self.index, str(DATA_DIR / "index.faiss"))
+
+        with open(DATA_DIR / "meta.json", "w", encoding="utf-8") as f:
+            json.dump(self.metadata, f)
+
+    def load(self):
+        if not (DATA_DIR / "index.faiss").exists():
+            raise FileNotFoundError(f"No database found at {DATA_DIR}. Please run build first.")
+
+        self.index = faiss.read_index(str(DATA_DIR / "index.faiss"))
+
+        with open(DATA_DIR / "meta.json", "r", encoding="utf-8") as f:
+            self.metadata = json.load(f)
+
+    def search(self, query: str, k=TOP_K):
+        q_emb = self.model.encode([query])
+        faiss.normalize_L2(q_emb)
+
+        scores, indices = self.index.search(q_emb, k)
+
+        results = []
+        for score, idx in zip(scores[0], indices[0]):
+            results.append({
+                "score": float(score),
+                "data": self.metadata[idx]
+            })
+
+        return results
+
+    def nucleus_filter(self, results):
+        if not results:
+            return []
+
+        best = results[0]["score"]
+
+        filtered = [
+            r for r in results
+            if (best - r["score"]) <= SIMILARITY_RADIUS
+        ]
+
+        # softmax sampling
+        scores = np.array([r["score"] for r in filtered])
+        probs = np.exp(scores) / np.sum(np.exp(scores))
+
+        sampled_indices = np.random.choice(
+            len(filtered),
+            size=min(len(filtered), 10),
+            replace=False,
+            p=probs
+        )
+
+        return [filtered[i] for i in sampled_indices]

raqa-0.0.1/src/raqa/utils.py

@@ -0,0 +1,49 @@
+import os
+import re
+from pathlib import Path
+from typing import List
+
+from .config import ENV_FILE
+
+def split_sentences(text: str) -> List[str]:
+    # simple but effective
+    sentences = re.split(r'(?<=[.!?])\s+', text)
+    return [s.strip() for s in sentences if s.strip()]
+
+
+def window_chunks(sentences: List[str], window: int = 3):
+    chunks = []
+
+    for i in range(len(sentences)):
+        left = sentences[max(0, i - window): i]
+        center = [sentences[i]]
+        right = sentences[i + 1: i + 1 + window]
+
+        chunk_text = " ".join(left + center + right)
+
+        chunks.append({
+            "text": chunk_text,
+            "center": sentences[i],
+            "index": i
+        })
+
+    return chunks
+
+
+def get_openai_key() -> str:
+    """
+    Load the OpenAI API key from ENV_FILE, prompt user if missing.
+    """
+    if ENV_FILE.exists():
+        key = ENV_FILE.read_text().strip()
+        if key:
+            return key
+
+    # Prompt user
+    print(f"🔑 OpenAI API key not found. Enter your key (it will be saved at {ENV_FILE}):")
+    key = input("API Key: ").strip()
+
+    # Save to file
+    ENV_FILE.write_text(key)
+    print(f"✅ Key saved at {ENV_FILE}")
+    return key

raqa-0.0.1/src/raqa.egg-info/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: raqa
+Version: 0.0.1
+Author-email: Jordi Carrera Ventura <jordi.carrera.ventura@gmail.com>
+Project-URL: GitHub repository, https://github.com
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: build
+Requires-Dist: faiss-cpu
+Requires-Dist: numpy
+Requires-Dist: openai
+Requires-Dist: python-frontmatter
+Requires-Dist: sentence-transformers
+Requires-Dist: tqdm
+Requires-Dist: typer[all]
+Requires-Dist: twine
+Dynamic: license-file
+
+# RAQA
+
+**R**etrieval-**A**ugmented **Q**uestion-**A**nswering
+
+Retrieval-augmented, pip-installable, CLI-based question answering over arbitrary document collections.
+
+# Usage
+
+## Installation
+
+```
+pip install raqa
+```
+
+**Locally**
+
+`pip install -e .`
+
+## Run
+
+### BASH via Python interpreter
+
+1. Build DB
+
+    `python cli.py build --path ./docs`
+
+2. Chat
+
+    `python cli.py chat`
+
+3. One-shot retrieval
+
+    `python cli.py search "what is retrieval augmented generation?"`
+
+4. Rebuild and chat
+
+    `python cli.py rebuild-and-chat`
+
+5. Get stats
+
+    `python cli.py stats`
+
+### BASH natively
+
+```
+raqa build --path ./markdown_files
+raqa chat
+raqa search "what is RAG?"
+raqa stats
+raqa rebuild-and-chat
+```
+
+
+## Python
+
+### Build database
+
+```
+from db import VectorDB
+from config import MARKDOWN_ROOT
+
+db = VectorDB()
+db.build(MARKDOWN_ROOT)
+```
+
+### Run
+
+```
+from agent import RAGAgent
+
+agent = RAGAgent()
+agent.chat()
+```
+
+
+## Build instructions
+
+Next steps:
+
+1. If any changes are made, update `pyproject.toml`.
+2. Building the package before uploading:
+    `cd raqa; python -m build`.
+3. Upload the package to pypi:
+    `python -m twine upload --repository {pypi|testpypi} dist/*`
+
+## Next steps
+
+### Real tool-calling (instead of implicit RAG)
+
+Define OpenAI tool:
+
+```
+{
+  "name": "search_docs",
+  "description": "...",
+  "parameters": { "query": "string" }
+}
+```
+
+### Hybrid search
+
+Combine BM25 (rank-bm25) + embeddings

raqa-0.0.1/src/raqa.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/raqa/__init__.py
+src/raqa/agent.py
+src/raqa/cli.py
+src/raqa/config.py
+src/raqa/db.py
+src/raqa/utils.py
+src/raqa.egg-info/PKG-INFO
+src/raqa.egg-info/SOURCES.txt
+src/raqa.egg-info/dependency_links.txt
+src/raqa.egg-info/entry_points.txt
+src/raqa.egg-info/requires.txt
+src/raqa.egg-info/top_level.txt

raqa-0.0.1/src/raqa.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

raqa-0.0.1/src/raqa.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+raqa = raqa.cli:app

raqa-0.0.1/src/raqa.egg-info/requires.txt

@@ -0,0 +1,9 @@
+build
+faiss-cpu
+numpy
+openai
+python-frontmatter
+sentence-transformers
+tqdm
+typer[all]
+twine

raqa-0.0.1/src/raqa.egg-info/top_level.txt

@@ -0,0 +1 @@
+raqa