vectordba 0.1.0

Agentic MongoDB NLP Database Interface

VectorDBA: Agentic MongoDB NLP Database Interface 🤖🍃

ANDI (andi-ai) is an agentic Python library designed exclusively for MongoDB development. It transforms your NoSQL database into a secure, natural language interface.

By leveraging the reasoning capabilities of gpt-4o-mini, ANDI instantly translates plain English into precise MongoDB standard queries or complex multi-stage aggregation pipelines—complete with dynamic runtime variables.

Stop building, maintaining, and debugging dozens of rigid, single-purpose CRUD endpoints. Consolidate your data fetching layer into a single, highly flexible, intelligent NLP endpoint.

---

✨ Features

• 🗣️ Text-to-NoSQL Translation: Write complex database requests in plain English. ANDI handles the heavy lifting, translating intent into native MongoDB query syntax.
• 🧠 Agentic Query Planning: Powered by gpt-4o-mini, ANDI deeply understands context, deeply nested structures, and relationships to construct highly accurate operations.
• 🔒 Privacy-First Schema Isolation: ANDI connects to your database, infers the shape of your collections, and caches the structure locally. Only the schema metadata is sent to the LLM—your actual database records are never exposed to the agent.
• ⚡ Secure Runtime Variables: Safely inject dynamic inputs into your natural language prompts at runtime, eliminating string-concatenation and prompt-injection vulnerabilities.
• 🛠️ Complex Aggregations Out-of-the-Box: Seamlessly generates standard find() queries as well as advanced aggregate() pipelines ($lookup, $unwind, $group, etc.).
• 🎯 Single Endpoint Architecture: Perfect for building AI agents, chatbots, or highly dynamic applications that require flexible, ad-hoc data retrieval without writing code for every new UI view.

---

📦 Installation

ANDI is available on PyPI. Install it cleanly using pip:

pip install andi-ai

⚙️ Prerequisites

To run ANDI, ensure you have:

1. A valid MongoDB Connection String URI.
2. An OpenAI API Key configured in your environment variables (OPENAI_API_KEY).

🚀 Quick Start

Here is how easily you can initialize ANDI, map your schema, and execute a natural language query with dynamic runtime bindings:

⚡ How Runtime Variables Work (**kwargs Resolution)

To prevent string-concatenation vulnerabilities and prompt injection, ANDI uses a strict declarative variable binding system. When you define an intent, you declare placeholders using the ${variable_name} syntax.

When executing the query via run_query_executor, you must pass these exact variables as Python keyword arguments (**kwargs).

The Golden Rule of Mappings

The variable key identifier defined inside your runtime_inputs object template must match the Python parameter key exactly.

Location	Key Syntax	Example
1. Inside Intent JSON:	"runtime_inputs": [{"email": "${target_email}"}]	Uses ${target_email} placeholder
2. Inside run_query_executor:	andi.run_query_executor(plan, target_email=variable)	target_email=target_email

---

Detailed Breakdown Example

Here is exactly how the mapping connects from your JSON definition to execution:

import os
from nlp_pymongo import MongoClient

# 1. Initialize ANDI
andi = MongoClient(db_session=None, analyzed_schemas=None)

# 2. Connect to your MongoDB instance
MONGO_URI = os.getenv("MONGO_URI", "mongodb://localhost:27017")
DATABASE_NAME = "database_name"
connection_string = f"mongodb://{MONGO_URI}"

andi.initialize_connection(connection_string=MONGO_URI, database_name=DATABASE_NAME)

# 3. Analyze and locally cache the schema structure for required collections
# (Your database records never leave your local environment)
andi.analyze_schemas(base_collections=["users", "wallets", "weekly_leaderboard"])

# 4. Define a natural language intent with safe runtime variables
target_email = "[e-mail]"

intent = {
    "intent": {
        "goal": "Find the preferred_language and name of the user where email=target_email",
        "runtime_inputs": [
            {
                "email": "${target_email}",
                "datatype": "string"
            }
        ],
        "projection": ["name", "preferred_language"]
    }
}

# 5. Build the optimized NLP query execution plan
query_plan = andi.build_nlp_query(intent, query_identifier=None)
print(query_plan)
# 6. Execute safely against your database. Make sure passing argument name and variable name must match to resolve during runtime.
result = andi.run_query_executor(query_plan, target_email=target_email)

print(result)
[{'name': 'Scott Watkins', 'preferred_language': 'en'}]

🏗️ How It Works

graph TD
    %% Define Styles & Colors
    classDef default fill:#1e1e24,stroke:#333,stroke-width:1px,color:#fff;
    classDef highlight fill:#2e7d32,stroke:#4caf50,stroke-width:2px,color:#fff;
    classDef db fill:#0d47a1,stroke:#1565c0,stroke-width:1px,color:#fff;

    DB[(MongoDB Instance)]:::db
    Schema[1. Local Schema Caching<br/><i>Generates .schema_cache.json</i>]:::default
    LLM[2. OpenAI gpt-4o-mini Agent<br/><i>Translates Intent + Metadata</i>]:::highlight
    Executor[3. Secure Query Executor<br/><i>Compiles bindings & executes locally</i>]:::default
    Result([Clean Python Dict Output]):::default

    %% Flow Connections
    DB -->|Local Structural Scan| Schema
    Schema -->|Schema Metadata Only| LLM
    LLM -->|Valid MongoDB JSON Syntax| Executor
    Executor -->|Runs Native Driver Command| DB
    Executor -->|Returns Data| Result
  

📖 Supported Operations

ANDI features a strict read-only routing engine. It translates natural language exclusively into data-fetching operations, ensuring your production data remains completely safe from AI hallucinations or unauthorized modifications.

Operation	Status	Capabilities	Natural Language Example	Generated Native Syntax
find()	✅ Supported	Standard filtering, sorting, limits, and explicit field projections.	"Find active users registered after 2025, sorted by latest."	{ "status": "active", "reg_date": { "$gt": "2025-01-01" } }
aggregate()	✅ Supported	Multi-stage transformations, relational joins, unwinding arrays, and grouping.	"Join weekly leaderboards with user wallets and get top 10 scores."	[{ "$lookup": {...} }, { "$unwind": ... }, { "$sort": ... }]
insert()	❌ Blocked	Prevent dynamic data insertion via the NLP endpoint.	"Add a new user to the database..."	Operation Denied (Read-Only Guardrail)
update() / delete()	❌ Blocked	Prevent unauthorized mutations, bulk updates, or accidental collections drops.	"Delete all users who haven't logged in..."	Operation Denied (Read-Only Guardrail)

🔒 The Read-Only Safety Guarantee

Security Note: Write operations are intentionally restricted at the core library layer. Even if an LLM structure attempts to formulate a mutation pipeline, ANDI's execution engine will intercept and reject the command before it ever hits your MongoDB driver. This makes it completely safe for exposed API endpoints.

🤝 Contributing

Contributions, issues, and feature requests are welcome! If you'd like to extend support for custom database engines, optimize pipeline construction routing, or suggest features, feel free to open a pull request or check the Issues Page.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.