Initial working prototype

Author: 14r14

.gitignore

@@ -0,0 +1,78 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv/
+env.bak/
+venv.bak/
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# FAISS data files
+data/
+*.faiss
+*.meta
+*.json
+!pyproject.toml
+
+# Streamlit
+.streamlit/
+
+# Docker
+*.log
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Project specific
+*.pdf
+uploads/
+

Dockerfile

@@ -0,0 +1,28 @@
+FROM python:3.11-slim AS base
+
+# Install system deps
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv
+RUN pip install --no-cache-dir uv
+
+WORKDIR /app
+COPY pyproject.toml ./
+
+# Sync deps
+RUN uv sync --frozen --no-dev
+
+# App source
+COPY app ./app
+COPY README.md ./README.md
+
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+EXPOSE 8080
+
+CMD ["uv", "run", "streamlit", "run", "app/main.py", "--server.port", "8080", "--server.address", "0.0.0.0"]
+
+

README.md

@@ -0,0 +1,33 @@
+# IBM Cloud RAG MVP
+
+Streamlit single-page app with RAG pipeline using watsonx.ai (Granite-13B for answers, `ibm/granite-embedding-30m-english` for embeddings), FAISS vector search, and IBM Cloud Object Storage.
+
+## Prerequisites
+- Python 3.11+
+- IBM Cloud account with watsonx.ai, COS, watsonx.data (Milvus), Code Engine
+- `uv` package manager
+
+## Environment
+Set required variables via `.env` or environment. See `app/config.py` and the project plan for details.
+
+## Run locally
+```bash
+uv run streamlit run app/main.py --server.port 8080 --server.address 0.0.0.0
+```
+
+## Container
+```bash
+docker build -t ibm-rag-mvp:latest .
+```
+
+## Deploy (IBM Cloud Code Engine)
+- Push image to IBM Cloud Container Registry (`us.icr.io/<namespace>/ibm-rag-mvp:latest`).
+- Create a Code Engine project and app, set env vars and bind secrets.
+- Expose port 8080.
+
+## Notes
+- FAISS index and metadata are persisted to local files (see `FAISS_INDEX_PATH`, `FAISS_META_PATH`). For persistence across deploys, back them up to COS.
+- COS can use IAM (no HMAC). Presigned URLs require HMAC; IAM mode uses internal access.
+- Keep services in the same region for best latency.
+
+

app/config.py

@@ -0,0 +1,69 @@
+import os
+from dataclasses import dataclass
+
+
+@dataclass
+class Settings:
+    ibm_cloud_api_key: str
+    watsonx_region: str
+    watsonx_project_id: str
+    watsonx_embed_model: str
+    watsonx_gen_model: str
+
+    cos_endpoint: str
+    cos_bucket: str
+    cos_instance_crn: str
+    cos_api_key: str | None
+    cos_auth_endpoint: str
+    cos_hmac_access_key_id: str
+    cos_hmac_secret_access_key: str
+
+    milvus_host: str
+    milvus_port: int
+    milvus_db: str | None
+    milvus_tls: bool
+
+    faiss_index_path: str
+    faiss_meta_path: str
+
+    chunk_size: int
+    chunk_overlap: int
+    top_k: int
+    temperature: float
+    embedding_dim: int
+
+    @staticmethod
+    def _get_bool(value: str | None, default: bool = False) -> bool:
+        if value is None:
+            return default
+        return value.lower() in {"1", "true", "t", "yes", "y"}
+
+    @classmethod
+    def from_env(cls) -> "Settings":
+        return cls(
+            ibm_cloud_api_key=os.getenv("IBM_CLOUD_API_KEY", ""),
+            watsonx_region=os.getenv("WATSONX_REGION", "us-south"),
+            watsonx_project_id=os.getenv("WATSONX_PROJECT_ID", ""),
+            watsonx_embed_model=os.getenv("WATSONX_EMBED_MODEL", "ibm/granite-embedding-30m-english"),
+            watsonx_gen_model=os.getenv("WATSONX_GEN_MODEL", "ibm/granite-13b-instruct-v2"),
+            cos_endpoint=os.getenv("COS_ENDPOINT", ""),
+            cos_bucket=os.getenv("COS_BUCKET", ""),
+            cos_instance_crn=os.getenv("COS_INSTANCE_CRN", ""),
+            cos_api_key=os.getenv("COS_API_KEY") or os.getenv("IBM_CLOUD_API_KEY"),
+            cos_auth_endpoint=os.getenv("COS_AUTH_ENDPOINT", "https://iam.cloud.ibm.com/identity/token"),
+            cos_hmac_access_key_id=os.getenv("COS_HMAC_ACCESS_KEY_ID", ""),
+            cos_hmac_secret_access_key=os.getenv("COS_HMAC_SECRET_ACCESS_KEY", ""),
+            milvus_host=os.getenv("MILVUS_HOST", "localhost"),
+            milvus_port=int(os.getenv("MILVUS_PORT", "19530")),
+            milvus_db=os.getenv("MILVUS_DB"),
+            milvus_tls=cls._get_bool(os.getenv("MILVUS_TLS"), False),
+            faiss_index_path=os.getenv("FAISS_INDEX_PATH", "data/index.faiss"),
+            faiss_meta_path=os.getenv("FAISS_META_PATH", "data/meta.json"),
+            chunk_size=int(os.getenv("CHUNK_SIZE", "1200")),
+            chunk_overlap=int(os.getenv("CHUNK_OVERLAP", "150")),
+            top_k=int(os.getenv("TOP_K", "6")),
+            temperature=float(os.getenv("TEMPERATURE", "0.2")),
+            embedding_dim=int(os.getenv("EMBEDDING_DIM", "1024")),
+        )
+
+

app/main.py

@@ -0,0 +1,74 @@
+import uuid
+from dotenv import load_dotenv
+import streamlit as st
+
+from app.config import Settings
+from app.rag.pipeline import IngestionPipeline, QueryPipeline
+
+
+def init_state():
+    if "messages" not in st.session_state:
+        st.session_state["messages"] = []
+    if "ingested_docs" not in st.session_state:
+        st.session_state["ingested_docs"] = []
+
+
+def sidebar_uploader(ingestion: IngestionPipeline):
+    st.sidebar.header("Upload PDFs")
+    uploaded_files = st.sidebar.file_uploader(
+        "Choose PDF files", type=["pdf"], accept_multiple_files=True
+    )
+    if uploaded_files and st.sidebar.button("Ingest Selected PDFs"):
+        for f in uploaded_files:
+            doc_id = str(uuid.uuid4())
+            with st.spinner(f"Uploading and ingesting {f.name}..."):
+                source_uri = ingestion.upload_to_cos(doc_id, f.name, f)
+                count = ingestion.ingest_pdf(doc_id, f.name, source_uri)
+            st.session_state["ingested_docs"].append((doc_id, f.name, source_uri, count))
+        st.sidebar.success("Ingestion complete.")
+
+    if st.session_state["ingested_docs"]:
+        st.sidebar.subheader("Ingested Documents")
+        for doc_id, name, uri, count in st.session_state["ingested_docs"]:
+            st.sidebar.write(f"- {name} ({count} chunks)")
+
+
+def chat_ui(query_pipeline: QueryPipeline):
+    st.title("IBM Cloud RAG MVP")
+    st.caption("Granite-13B-Instruct + Milvus + COS + Streamlit")
+
+    for role, content in st.session_state["messages"]:
+        with st.chat_message(role):
+            st.markdown(content)
+
+    user_input = st.chat_input("Ask a question about your PDFs…")
+    if user_input:
+        st.session_state["messages"].append(("user", user_input))
+        with st.chat_message("user"):
+            st.markdown(user_input)
+
+        with st.chat_message("assistant"):
+            with st.spinner("Thinking…"):
+                answer, sources = query_pipeline.answer(user_input)
+                citations = "\n\n" + "\n".join([f"- {s}" for s in sources]) if sources else ""
+                st.markdown(answer + citations)
+                st.session_state["messages"].append(("assistant", answer + citations))
+
+
+def main():
+    # Load local .env for development
+    load_dotenv()
+    settings = Settings.from_env()
+    init_state()
+
+    ingestion = IngestionPipeline(settings)
+    query_pipeline = QueryPipeline(settings)
+
+    sidebar_uploader(ingestion)
+    chat_ui(query_pipeline)
+
+
+if __name__ == "__main__":
+    main()
+
+

app/models.py

@@ -0,0 +1,20 @@
+from pydantic import BaseModel
+from typing import List, Optional
+
+
+class ChunkRecord(BaseModel):
+    id: str
+    doc_id: str
+    page_num: int
+    chunk_index: int
+    text: str
+    embedding: List[float]
+    source_uri: str
+
+
+class QueryResult(BaseModel):
+    answer: str
+    sources: List[str]
+    matched_chunks: Optional[List[ChunkRecord]] = None
+
+

app/rag/chunker.py

@@ -0,0 +1,16 @@
+from typing import List
+
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+
+
+def chunk_pages(pages: List[str], chunk_size: int, chunk_overlap: int) -> List[str]:
+    splitter = RecursiveCharacterTextSplitter(
+        chunk_size=chunk_size,
+        chunk_overlap=chunk_overlap,
+        length_function=len,
+        separators=["\n\n", "\n", " ", ""],
+    )
+    full_text = "\n\n".join(pages)
+    return splitter.split_text(full_text)
+
+

app/rag/cos_client.py

@@ -0,0 +1,57 @@
+import io
+import time
+from typing import BinaryIO
+
+import ibm_boto3
+from ibm_botocore.client import Config
+
+from app.config import Settings
+
+
+class COSClient:
+    def __init__(self, settings: Settings):
+        self.settings = settings
+        if not settings.cos_endpoint or not settings.cos_bucket or not settings.cos_instance_crn:
+            raise ValueError(
+                "Missing COS configuration. Please set COS_ENDPOINT, COS_BUCKET, and COS_INSTANCE_CRN."
+            )
+        # Prefer HMAC if keys are present; otherwise use IAM
+        if settings.cos_hmac_access_key_id and settings.cos_hmac_secret_access_key:
+            self.mode = "hmac"
+            self.client = ibm_boto3.client(
+                "s3",
+                aws_access_key_id=settings.cos_hmac_access_key_id,
+                aws_secret_access_key=settings.cos_hmac_secret_access_key,
+                config=Config(signature_version="s3v4"),
+                endpoint_url=settings.cos_endpoint,
+            )
+        else:
+            self.mode = "iam"
+            self.client = ibm_boto3.client(
+                "s3",
+                ibm_api_key_id=settings.cos_api_key,
+                ibm_service_instance_id=settings.cos_instance_crn,
+                ibm_auth_endpoint=settings.cos_auth_endpoint,
+                config=Config(signature_version="oauth"),
+                endpoint_url=settings.cos_endpoint,
+            )
+
+    def upload_fileobj(self, key: str, fileobj: BinaryIO, content_type: str = "application/pdf") -> str:
+        self.client.upload_fileobj(
+            Fileobj=fileobj,
+            Bucket=self.settings.cos_bucket,
+            Key=key,
+            ExtraArgs={"ContentType": content_type},
+        )
+        return f"s3://{self.settings.cos_bucket}/{key}"
+
+    def generate_presigned_url(self, key: str, expires_in: int = 3600) -> str:
+        if self.mode != "hmac":
+            raise RuntimeError("Presigned URLs require HMAC credentials; IAM mode does not support presign.")
+        return self.client.generate_presigned_url(
+            ClientMethod="get_object",
+            Params={"Bucket": self.settings.cos_bucket, "Key": key},
+            ExpiresIn=expires_in,
+        )
+
+