sinapsis-aperturedb 0.1.0
Templates for multimodal database operations using ApertureDB API.
Requires Python: >=3.10

<!-- [![sp](https://img.shields.io/badge/lang-sp-red.svg)](https://github.com/Sinapsis-AI/sinapsis-aperturedb/blob/main/README.es.md) -->
<h1 align="center">
<br>
<a href="https://sinapsis.tech/">
  <img
    src="https://github.com/Sinapsis-AI/brand-resources/blob/main/sinapsis_logo/4x/logo.png?raw=true"
    alt="" width="300">
</a><br>
Sinapsis ApertureDB
<br>
</h1>

<h4 align="center">Modular templates for database entity management with ApertureDB</h4>

<p align="center">
<a href="#installation">🐍  Installation</a> •
<a href="#features"> 🚀 Features</a> •
<a href="#example"> 📚 Usage example</a> •
<a href="#webapp"> 🌐 Webapp</a> •
<a href="#documentation">📙 Documentation</a> •
<a href="#license"> 🔍 License </a>
</p>

**Sinapsis ApertureDB** provides a robust and flexible integration for the ApertureDB Python SDK. It enables users to execute complex database operations—such as entity management, status monitoring, and schema retrieval—through a modular, template-based system.


<h2 id="installation"> 🐍  Installation </h2>

Install using your package manager of choice. We encourage the use of <code>uv</code>

Example with <code>uv</code>:

```bash
  uv pip install sinapsis-aperturedb --extra-index-url https://pypi.sinapsis.tech
```

 or with raw <code>pip</code>:

```bash
  pip install sinapsis-aperturedb --extra-index-url https://pypi.sinapsis.tech
```

<h2 id="features">🚀 Features</h2>

<h3>Templates Supported</h3>

- **ApertureDBAddEntitiesFromCSV**: Ingests tabular data from a pandas DataFrame stored within a DataContainer, mapping each row to a unique Entity for bulk insertion into the database.
- **ApertureDBFindEntities**: Executes targeted entity queries within ApertureDB, retrieving records that match a specific set of user-defined constraints and filters.
- **ApertureDBGetStatus**: Polls the ApertureDB server to retrieve real-time health metrics, connectivity status, and operational readiness.
- **ApertureDBGetSchema**: Introspects the database to generate a comprehensive overview of the current data model, including entity types, properties, and relationships.

> [!TIP]
> Use CLI command ```sinapsis info --all-template-names``` to show a list with all the available Template names installed with Sinapsis ApertureDB.

> [!TIP]
> Use CLI command ```sinapsis info --example-template-config TEMPLATE_NAME``` to produce an example Agent config for the Template specified in ***TEMPLATE_NAME***.

For example, for ***ApertureDBGetStatus*** use ```sinapsis info --example-template-config ApertureDBGetStatus``` to produce an example config like:

```yaml
agent:
  name: my_test_agent
templates:
- template_name: InputTemplate
  class_name: InputTemplate
  attributes: {}
- template_name: ApertureDBGetStatus
  class_name: ApertureDBGetStatus
  template_input: InputTemplate
  attributes:
    connect_with_key: false
    connection_params:
      host: localhost
      user: ''
      port: 55555
      password: ''
      key: ''
      use_ssl: false
```

<h2 id='example'>📚 Usage example</h2>

You can begin testing ```sinapsis-aperturedb``` by executing the ```ApertureDBGetStatus``` configuration. To utilize the ```ApertureDB``` templates, you must first establish a connection to an ApertureDB instance. You have three primary options:

- Cloud: Connect to a hosted ApertureDB instance using a generated API key.
- Local: Deploy a local instance using the aperturedb-community Docker image.
- Docker Compose: Automatically deploy the aperturedb service and execute the getStatus configuration in one workflow.

<details>
<summary ><strong><span style="font-size: 1.4em;"> ☁️ ApertureDB Cloud </span></strong></summary>

1. **Generate an API key**: Create an ApertureDB Cloud account and generate your API key by following the official [ApertureDB setup guide](https://docs.aperturedata.io/Setup/server/Cloud).

2. **Configure Environment Variables**: Set the ```APERTUREDB_API_KEY``` variable in your terminal. This key is used by the connect_with_key attribute in your configuration.

    ```bash
    export APERTUREDB_API_KEY="your-api-key-here"
    ```

3. **Prepare the GetStatus Configuration**: Save the following YAML as ```check_status.yaml```. This configuration tells the agent to authenticate using your stored API key.

    ```yaml
    agent:
      name: aperturedb_get_status
      description: Validates connection and retrieves ApertureDB server health status.

    templates:
    - template_name: InputTemplate
      class_name: InputTemplate
      attributes: {}

    - template_name: GetStatus
      class_name: ApertureDBGetStatus
      template_input: InputTemplate
      attributes:
        connect_with_key: true
    ```

4. **Execute via CLI**: Run the configuration using the Sinapsis CLI:

    ```bash
    sinapsis run check_status.yaml
    ```

</details>

<details>
<summary ><strong><span style="font-size: 1.4em;"> 💻 Local ApertureDB instance </span></strong></summary>

For local prototyping and testing of <code>sinapsis-aperturedb</code>, you can deploy a containerized instance of **ApertureDB Community Edition**.

1. **Deploy the container**. Use the following Docker command to run the ApertureDB Community Edition. This setup maps the default port and configures initial credentials.

    ```bash
    docker run -p 55555:55555 -e ADB_MASTER_KEY=admin -e ADB_FORCE_SSL=false  aperturedata/aperturedb-community
    ```

2. **Configure Environment Variables**: Set your connection parameters so sinapsis-aperturedb can authenticate with the local instance.

    ```bash
    export APERTUREDB_HOST="localhost"
    export APERTUREDB_PORT=55555
    ```

3. **Prepare the GetStatus Configuration**: Use the following YAML configuration to verify the connection. Save this as ```check_status.yaml```:

    ```yaml
    agent:
      name: aperturedb_get_status
      description: Validates connection and retrieves ApertureDB server health status.

    templates:
    - template_name: InputTemplate
      class_name: InputTemplate
      attributes: {}

    - template_name: GetStatus
      class_name: ApertureDBGetStatus
      template_input: InputTemplate
      attributes:
        connect_with_key: false
        connection_params:
            host: localhost
            user: admin
            port: 55555
            password: admin
            use_ssl: false
    ```

4. **Execute via CLI**: Run the configuration using the Sinapsis CLI:

    ```bash
    sinapsis run check_status.yaml
    ```

</details>

<details>
<summary id="docker"><strong><span style="font-size: 1.4em;">🐳 Docker Compose</span></strong></summary>

**IMPORTANT** This docker image depends on the sinapsis:base image. Refer to the official [Sinapsis Docker Instructions](https://github.com/Sinapsis-ai/sinapsis?tab=readme-ov-file#docker) to build the base before proceeding.

1. **Build the sinapsis-aperturedb image**: Compile the local environment using the provided compose file.

    ```bash
    docker compose -f docker/compose.yaml build
    ```

2. **Start the app container**: Launch the service in the background or attached mode.

    ```bash
    docker compose -f docker/compose_app.yaml up -d
    ```

3. **Monitor logs and status**: Verify the connection to ApertureDB by tailing the container logs.

    ```bash
    docker logs -f sinapsis-aperturedb-app
    ```

4. **To stop the app**: Gracefully shut down the services and clean up network resources.

    ```bash
    docker compose -f docker/compose_app.yaml down
    ```

</details>

<h2 id="documentation">📙 Documentation</h2>

Documentation for this and other sinapsis packages is available on the [sinapsis website](https://docs.sinapsis.tech/docs)

Tutorials for different projects within sinapsis are available at [sinapsis tutorials page](https://docs.sinapsis.tech/tutorials)

<h2 id="license">🔍 License</h2>

This project is licensed under the AGPLv3 license, which encourages open collaboration and sharing. For more details, please refer to the [LICENSE](LICENSE) file.

For commercial use, please refer to our [official Sinapsis website](https://sinapsis.tech) for information on obtaining a commercial license.