ahvn.utils.mdb.base module

MongoDB connection wrapper for AgentHeaven.

This module provides a MongoDB connection class that follows the same pattern as the Database class but uses PyMongo for MongoDB operations.

class ahvn.utils.mdb.base.MongoDatabase(database=None, collection=None, connect=False, **kwargs)

Bases: object

MongoDB connection wrapper (PyMongo only, sync operations).

Follows the same pattern as Database (utils/db/base.py): - Uses resolve_mdb_config() to get configuration from HEAVEN_CM - Handles connection string building with defaults - Manages connection lifecycle - Provides generic MongoDB access without UKF-specific logic

Example

```python # Use default config mongo = MongoDatabase() collection = mongo.conn

# Override specific params mongo = MongoDatabase(host=”192.168.1.100”, port=27018)

# Use connection string directly mongo = MongoDatabase(connection_string=”mongodb://localhost:27017/mydb”)

# Context manager (auto-close) with MongoDatabase() as mongo:

collection = mongo.mdb[“test”] collection.insert_one({“name”: “Alice”})

```

Note

This class uses PyMongo for synchronous operations only. Motor (async) support will be added in a future phase.

Parameters:

• database (Optional[str])

• collection (Optional[str])

• connect (bool)

__init__(database=None, collection=None, connect=False, **kwargs)

Initialize MongoDB connection.

Similar to Database.__init__(), resolves configuration from HEAVEN_CM.

Parameters:

• database (Optional[str]) – Database name (optional, defaults to config value)

• collection (Optional[str]) – Collection name (optional, defaults to config value)

• connect (bool) – Whether to connect immediately upon initialization.

• **kwargs – Additional connection parameters that override config values - database: Database name (overrides config) - host: MongoDB host (overrides config) - port: MongoDB port (overrides config) - username: Auth username (overrides config) - password: Auth password (overrides config) - connection_string: Full connection string (overrides all) - maxPoolSize, connectTimeoutMS, etc.

connect()

close()

Close MongoDB connection and cleanup resources.

property client: MongoClient

Get PyMongo client for sync operations.

Returns:

The PyMongo client instance.

Return type:

MongoClient

property mdb: Database

Get the specified database collection.

Returns:

The MongoDB database instance.

Return type:

Database

property conn: Collection

Get the specified database collection.

Returns:

The MongoDB collection instance.

Return type:

Collection

create_index(keys, **kwargs)

Create index on collection.

Parameters:

• keys (List[Tuple[str, int]]) – List of (field, direction) tuples direction: 1 for ascending, -1 for descending

• **kwargs – Additional index options (unique, sparse, etc.)

Example

>>> mongo.create_index([("name", 1)], name="users_name_idx")
>>> mongo.create_index([("type", 1), ("age", -1)], name="users_type_age_idx", unique=True)

create_vector_index(embedding_idx, embedding_field, dim)

Create vector search index on collection.

Parameters:

• embedding_idx (str) – Name of the vector index to create.

• embedding_field (str) – Field name containing the vector embeddings.

• dim (int) – Dimensionality of the embedding vectors.

Note

This only works with MongoDB Atlas, not local MongoDB instances.

__enter__()

Context manager entry: returns self.

__exit__(exc_type, exc_val, exc_tb)

Context manager exit: closes connection.