ANDI-AI: Secure Agentic AI Data Gateway for Enterprise MongoDB 🤖🍃

ANDI stands for Advanced Natural Language Database Interface. It is the Secure Agentic AI Data Gateway for Enterprise MongoDB. We provide a deterministic middleware layer that enables AI agents and software applications to safely execute queries/aggregates on MongoDB clusters using plain text—without sacrificing speed, security, or predictability. By leveraging Agentic workflow, 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 OPENAPI, Andi deeply understands context, deeply nested structures, and relationships to construct highly accurate operations.
• 💾 Persistent Query Caching (New): Add a robust persistence layer to fetch compiled queries directly from cache, avoiding redundant query generation and significantly reducing token usage.
• 🔒 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.
• ⚙️ LLM_INTEGRATION.md: Cloud LLM skillset instructions to set up ANDI-AI as an isolated query orchestration layer and AI firewall in front of MongoDB database.

📦 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.

Detailed Breakdown Example

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

from andi import Andi


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


        connection_string = "mongodb://localhost:27017"

        vector_agent = Andi(db_session=db_session, analyzed_schemas=analyzed_schemas)
        database_name = "test"

        vector_agent.initialize_connection(connection_string=connection_string, database_name=database_name)
        vector_agent.analyze_schemas(base_collections=["users", "wallets", "weekly_leaderboard"])

        #Example 1

        target_email = "test_user_8_fischertimothy@gmail.com"

        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
    classDef payload fill:#e2e8f0,stroke:#475569,stroke-width:2px,color:#0f172a,font-weight:bold;
    classDef stage fill:#f8fafc,stroke:#2563eb,stroke-width:2px,color:#1e3a8a;
    classDef output fill:#f0fdf4,stroke:#16a34a,stroke-width:2px,color:#14532d,font-weight:bold;

    Input["📥 User Intent Payload<br>(Natural Language + Base Collections)"]:::payload

    subgraph andi_Engine ["andi Open-Source Compilation Engine"]
        S1["<b>1. Prompt-to-Task Decomposition</b><br>• Deconstructs intent into filtering, grouping, & projection targets"]:::stage
        S2["<b>2. Schema Resolver & Type Isolation</b><br>• Validates keys against schema & isolates BSON data types"]:::stage
        S3["<b>3. Relationship-to-Schema Mapping</b><br>• Resolves multi-collection references & constructs $lookup joins"]:::stage
        S4["<b>4. Deterministic Pipeline Construction</b><br>• Enforces optimal stage ordering ($match ➔ $lookup ➔ $group)"]:::stage
        S5["<b>5. BSON Query Generator & Validator</b><br>• Binds dynamic kwargs & compiles executable BSON syntax"]:::stage
    end

    Output[("🚀 Executable MongoDB BSON Query<br>(PyMongo / Motor Driver)")]:::output

    Input --> S1
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S5
    S5 --> Output

📖 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.

🔒 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.