In this post, I’ll walk you through the FastAPI-based backend of BingeMate and how it integrates with MindsDB to enable semantic search, metadata filtering, and even conversational agent responses using a SQL-powered interface.

🧠 What Is BingeMate?

BingeMate is a semantic search and recommendation engine that helps users find the perfect movie or series using natural language queries like:

• “Top-rated Netflix thrillers after 2020”
• “Feel-good anime with high IMDb ratings”
• “Is ‘Dark’ similar to ‘Stranger Things’?”

The backend is powered by FastAPI and connects to a MindsDB knowledge base, which stores semantically indexed chunks of content using LLMs and vectors.

git clone https://github.com/your-username/BingeMate-Backend.git
cd BingeMate-Backend

pip install -r requirements.txt

docker run --name mindsdb_container -e MINDSDB_APIS=http,mysql -p 47334:47334 -p 47335:47335 mindsdb/mindsdb

ollama run granite-embedding
ollama run mistral

CREATE KNOWLEDGE_BASE my_bingekb
USING

⚙️ Backend Tech Stack

• FastAPI: Lightweight, high-performance Python web framework for building APIs.
• MindsDB SDK: Python client to query MindsDB knowledge bases and agents
• Pandas: For formatting query results
• Uvicorn: ASGI server for FastAPI
• JSON-based filtering: For flexible metadata queries

📁 Project Structure

📦 bingemate-backend/
├── main.py                  # FastAPI app with routes
├── bingewatch.csv           # CSV file that contains movie/series data
├── mindsdb_client.py        # MindsDB SDK helper functions
├── requirements.txt         # Dependencies

🧪 API Endpoints

/query — Search Knowledge Base

@app.get("/query")
def search_kb(
    request: Request,
    q: str = Query(..., description="Search query, e.g., 'best series'"),
    min_relevance: float = Query(0.25, description="Minimum relevance threshold"),
):
    query_params = dict(request.query_params)
    query_params.pop("q", None)
    query_params.pop("min_relevance", None)

    results = query_knowledge_base(
        search_query=q, 
        min_relevance=min_relevance, 
        metadata=query_params
    )
    return {"count": len(results), "results": results}

• 🔎 Accepts a natural language query like "popular kdrama in 2023"
• 📊 Supports dynamic metadata filters like ?type=Series&genre=Drama
• 🔁 Filters results by minimum relevance score

/agent — Ask a Question via Agent

@app.get("/agent")
def create_agent(
    query: str = Query(..., description="Question to ask the agent"),
    description: Optional[str] = Query(None, description="Description of the agent")
):
    result = query_agent(query=query)
    return {"result": result}

This endpoint interacts with a MindsDB agent that answers natural language questions based on pre-trained or fine-tuned SQL logic.

/api/projects/mindsdb/jobs — Simulated Job Endpoint

@app.post("/api/projects/mindsdb/jobs")
def create_job(
    project: str,
    job_name: str,
    query: str
):
    return {
        "message": f"Job '{job_name}' created in project '{project}' with query: {query}"
    }

✏️ Note : The MindsDB Job endpoint is used to schedule specific timepoints at which an SQL query will be executed.

🔧 mindsdb_client.py — Query Logic

This module handles communication with MindsDB via SQL.

Search the Knowledge Base

def query_knowledge_base(search_query: str, min_relevance: float = 0.25, metadata: dict = None):
    conditions = [f'content = "{search_query}"', f"relevance >= {min_relevance}"]
    if metadata:
        for key, value in metadata.items():
            conditions.append(f"{key} = '{value}'")
    sql = f"SELECT * FROM my_bingekb WHERE {' AND '.join(conditions)};"
    query = server.query(sql)
    df = query.fetch()
    ...

• ✅ Uses SQL to query my_bingekb table
• 🧠 Automatically filters results using relevance and metadata (e.g., type, genre)
• 🔄 Converts results to a JSON-friendly format

Ask a Question to an Agent

def query_agent(query: str):
    sql = f"""
    SELECT answer FROM my_agent WHERE question = "{query}";
    """
    df = server.query(sql).fetch()
    return df

This enables direct Q&A via a SQL-like agent interface. You can map semantic questions to custom-trained answers.

🧪 requirements.txt

fastapi
uvicorn
mindsdb_sdk
pandas

🚀 To run:

pip install -r requirements.txt
uvicorn main:app --reload

🌐 Example Usage

GET /query?q=best%20series%20on%20netflix&genre=Drama&type=Series

GET /agent?query=Is%20Breaking%20Bad%20better%20than%20Ozark

💡 Final Thoughts

FastAPI + MindsDB gives you a supercharged backend for semantic search and conversational interfaces. Whether you’re building a movie recommender, travel planner, or knowledge assistant—this stack is lightweight, extensible, and LLM-ready.

Now go and check out the implementation of this backend -- BingeMate!

🔗 Connect with me

𝕏 Twitter | 👨🏻‍💻 GitHub | ✉ Gmail | ▶ YouTube | 🇮🇳 LinkedIn