vectordba 0.1.2

Agentic MongoDB NLP Database Interface

VectorDBA: Agentic MongoDB NLP Database Interface 🤖🍃

VectorDBA 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, VectorDBA 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. VectorDBA handles the heavy lifting, translating intent into native MongoDB query syntax.
• 🧠 Agentic Query Planning: Powered by gpt-4o-mini, VectorDBA deeply understands context, deeply nested structures, and relationships to construct highly accurate operations.
• 🔒 Privacy-First Schema Isolation: VectorDBA 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

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

pip install vectordba

⚙️ Prerequisites

To run VectorDBA, 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 VectorDBA, 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, VectorDBA 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:	vector_agent.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:

from vectordba import VectorAgent

class TestProject:
    def testing_nlp(self, db_session, analyzed_schemas):
        self.db = db_session
        self.analyzed_schemas = analyzed_schemas


        connection_string = "mongodb+srv://dbuser:[e-mail]/?retryWrites=true&w=majority&appName=arasthoo-dev"

        vector_agent = VectorAgent(db_session=db_session, analyzed_schemas=analyzed_schemas)
        database_name = "aristotle"

        status = vector_agent.initialize_connection(connection_string=connection_string, database_name=database_name)

        print(status)

        user_coll = vector_agent.analyze_schemas(base_collections=["users", "wallets", "weekly_leaderboard"])
        print(user_coll)

        #Example 1

        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"]
          }
        }
        query = vector_agent.build_nlp_query(intent=intent, query_identifier=None, retry=False)
        print(query)

        output = vector_agent.run_query_executor(nlp_query=query, target_email=target_email)
        print(output)

🏗️ How It Works

graph TD
    %% Styling and Color Palettes (Enterprise Vibe)
    classDef client fill:#eef2f7,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a;
    classDef engine fill:#eff6ff,stroke:#2563eb,stroke-width:2px,color:#1e40af,font-weight:bold;
    classDef security fill:#fff1f2,stroke:#f43f5e,stroke-width:2px,color:#9f1239;
    classDef database fill:#f0fdf4,stroke:#16a34a,stroke-width:2px,color:#14532d;
    classDef structural fill:#fafafa,stroke:#71717a,stroke-width:1px,color:#27272a;

    %% 1. Ingestion Layer
    subgraph Client_Layer ["Application Interface"]
        API_Call["POST /api/v1/nlp_query<br>(Payload: Intent + Base Collections)"]:::client
    end

    %% 2. Orchestration Layer
    subgraph VectorDBA_Engine ["VectorDBA Agent Engine Core"]
        Init["VectorAgent Initialization<br>(Target Database Setup)"]:::engine
        SchemaAnalzer["vector_agent.analyze_schemas()<br>(Extracts Schemas)"]:::engine
        Builder["vector_agent.build_nlp_query()<br>(Deterministic Query Construction)"]:::engine
    end

    %% 3. Security & Validation Layer
    subgraph Security_Guardrails ["Enterprise Safety Controls"]
        IntentRouter{"Intent Routing<br>& Field Validation"}:::security
        Sanitize{"Injection Scanning<br>& Operator Isolation"}:::security
    end

    %% 4. Data Execution Target
    subgraph Infrastructure ["Enterprise Storage Target"]
        MongoCluster[("NoSQL Cluster<br>(MongoDB)")]:::database
    end

    %% Data Pipeline Connections Flow
    API_Call -->|1. Transmit Payload| Init
    Init -->|2. Scrape Structure Constraints| SchemaAnalzer
    SchemaAnalzer -->|3. Establish Pipeline Context Boundaries| Builder
    
    
    Builder -->|4. Inspect Fields Against Schema| IntentRouter
    IntentRouter -->|Passed: Valid Fields| Sanitize
    IntentRouter -.->|Failed: Reject Intent| API_Call
    
    Sanitize -->|5. Compile Secure BSON Native Pipeline| MongoCluster
    
    MongoCluster -->|6. Standard Isolated Output Cursor| API_Call

    %% Apply Styles to classes
    class Builder,SchemaAnalzer,Init engine;
  

📖 Supported Operations

VectorDBA 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, VectorDBA'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.