Metadata-Version: 2.4
Name: python-eigen-ingenuity
Version: 0.5.26b1
Summary: A python library used to query data from the Eigen Ingenuity system
Home-page: https://www.eigen.co/
Author: Murray Callander
Author-email: info@eigen.co
License: Apache License 2.0
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pyserial
Requires-Dist: setuptools
Requires-Dist: urllib3
Requires-Dist: msal
Requires-Dist: cryptography
Requires-Dist: keyring
Requires-Dist: pyarrow
Requires-Dist: neo4j>=5.17.0
Requires-Dist: requests>=2.31.0
Requires-Dist: dateparser
Requires-Dist: importlib-metadata>=1.0; python_version < "3.8"
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: requires-dist
Dynamic: summary

# Python Eigen Ingenuity SDK

## Overview

**Python Eigen Ingenuity** is a comprehensive Python library for accessing industrial data from Eigen Ingenuity instances. It enables seamless integration with time-series data, asset models, event logs, and SQL databases for analytics, automation, and ML workflows.

Supports Python 3.12+

---

## Table of Contents

- [Python Eigen Ingenuity SDK](#python-eigen-ingenuity-sdk)
  - [Overview](#overview)
  - [Table of Contents](#table-of-contents)
  - [Core Modules](#core-modules)
    - [1. Historian Multi](#1-historian-multi)
    - [2. Asset Model](#2-asset-model)
    - [3. Eventlog](#3-eventlog)
    - [4. SQL](#4-sql)
    - [5. Common Menu](#5-common-menu)
    - [6. Elastic (Deprecated)](#6-elastic-deprecated)
    - [7. Historian (Deprecated)](#7-historian-deprecated)
  - [Authentication](#authentication)
  - [Key Features](#key-features)
  - [Further Documentation](#further-documentation)
  - [Support](#support)

---

## Core Modules

Each module is queried by first instantiating a client object that manages onnection to a certain api. e.g. `get_histoiran_multi()` then all queries are performed as methods on the returned class

e.g.

```
hm = get_historian_multi("demo.eigen.co", "Demo-influxdb")
current = hm.getCurrentDataPoints("DEMO_02TI301.PV")
```

### 1. Historian Multi

Query time-series data from multiple historians simultaneously. Handles reading, writing, and managing data point metadata.

**Connection Function:**

- `get_historian_multi` — Initialize Historian Multi client

**Reading Data Functions:**

- `getCurrentDataPoints` — Fetch the latest tag values instantly
- `getInterpolatedPoints` — Retrieve interpolated data at specific timestamps
- `getInterpolatedRange` — Get interpolated data across a time range
- `getRawDatapoints` — Fetch raw historian data without interpolation
- `getClosestRawPoint` — Find the nearest raw data point to a specific time

**Aggregation Functions:**

- `getAggregates` — Compute statistics (min, max, avg, stdDev, median, count, etc.)
- `getAggregateIntervals` — Calculate aggregates over regular time intervals

**Metadata Functions:**

- `listHistorians` — List all available historian connections
- `listDataTags` — Retrieve all data tags from a historian
- `getMetaData` — Fetch metadata for specific tags
- `createTag` — Create a new data tag
- `updateTag` — Modify existing tag configuration

**Writing Data Functions:**

- `writePoints` — Write individual data points to tags
- `writePointsBatch` — Batch write multiple data points efficiently
- `createPoint` — Create a formatted data point object
- `createAndPopulateTag` — Create a new tag and immediately populate it with data

---

### 2. Asset Model

Navigate the Neo4J asset model to browse assets, their properties, related assets, and associated measurements.

**Connection Function:**

- `get_assetmodel` — Initialize Asset Model Client

**Core Functions:**

- `getRelatedAssets` — Retrieve all instruments or components related to an asset
- `getProperties` — Get metadata fields and custom properties from assets
- `getMeasurements` — Fetch all timeseries measurements configured for an asset
- `executeRawQuery` — Run custom Neo4J Cypher queries against the asset model
- `getDocuments` — Retrieve reference documents attached to assets
- `getLabels` — Get asset classification labels
- `getMatchingNodes` — Find assets matching specific criteria

---

### 3. Eventlog

Query, filter, and manage event records in the Ingenuity event log system.

**Connection Function:**

- `get_eventlog` — Initialize Eventlog client

**Query Functions:**

- `getEvents` — Execute raw queries with filters (severity, type, source, etc.)
- `getEventsBySource` — Filter events by source identifier (partial or exact match)
- `getEventsByType` — Filter events by event type
- `getEventsById` — Retrieve events by event ID, external ID, or episode ID

**Management Functions:**

- `pushToEventlog` — Create and push new events to the event log
- `deleteEventsById` — Remove unwanted events in bulk

---

### 4. SQL

Execute read-only queries against SQL databases connected to Ingenuity instances.

**Connection Function:**

- `get_sql` — Initialize SQL client

**Query Functions:**

- `executeRawQuery` — Execute raw SQL queries with multiple output formats (JSON, DataFrame, CSV file)
- `listDatabases` — Retrieve list of available SQL databases
- `listTables` — List tables within a specific database

---

### 5. Common Menu

Query asset relationships, measurements, properties, and documents through a unified interface.

**Connection Function:**

- `get_common_menu` — Initialize Common Menu client

**Functions:**

- `getRelatedAssets` — Query related assets
- `getProperties` — Fetch asset properties
- `getMeasurements` — Get measurements for assets
- `getDocuments` — Retrieve associated documents
- `getEvents` — Query events from the Common Menu perspective
- `getDrivers` — Get driver information

---

### 6. Elastic (Deprecated)

Legacy module for querying Elasticsearch-backed data sources. Flagged for removal in a future release. **Use Eventlog instead.**

**Connection Function:**

- `get_elastic` — Initialize legacy Elastic client

---

### 7. Historian (Deprecated)

Legacy single-historian client. Flagged for removal in a future release. **Use Historian Multi instead.**

**Connection Function:**

- `get_historian` — Initialize legacy Historian client for a single data source

---

## Authentication

The library supports Azure authentication with:

- **User Credentials Flow** — Interactive authentication
- **CLIENT_CREDENTIALS Flow** — Service principal authentication
- **API Token** — Direct token-based access

**Configuration Functions:**

- `set_azure_tenant_id` — Specify Azure tenant
- `set_azure_client_id` — Specify client/application ID
- `set_azure_client_secret` — Specify client secret (for CLIENT_CREDENTIALS)
- `set_api_token` — Set API token alternative to Azure auth
- `set_auth_scope` — Configure OAuth scope
- `disable_azure_auth` — Skip Azure authentication
- `disable_auth_token_cache` — Disable token caching for security
- `clear_auth_token_cache` — Remove cached tokens

---

## Key Features

✅ **Multi-Source Data Access** — Query historians, asset models, SQL, and events in one library  
✅ **Aggregations & Statistics** — Built-in support for min, max, average, standard deviation, median, and more  
✅ **Batch Operations** — Efficient bulk writes and queries  
✅ **Azure Authentication** — Enterprise authentication support  
✅ **Flexible Output** — JSON, DataFrames, files, or raw responses  
✅ **Time-Series Focused** — Purpose-built for industrial data workflows  
✅ **Neo4J Integration** — Direct access to asset model graph database

---

## Further Documentation

For complete function signatures, detailed parameters, and code examples, visit:

**📖 [https://docs.eigeningenuity.co/developing-with-eigen/python-library/](https://docs.eigeningenuity.co/developing-with-eigen/python-library/)**

---

## Support

- **Documentation Portal:** https://docs.eigeningenuity.co/
- **Support Tickets:** https://eigen.freshdesk.com
