Metadata-Version: 2.1
Name: sumtyme
Version: 1.1.1
Summary: Python Client for Embedded Intelligence Platform by sumtyme.ai.
Home-page: https://docs.sumtyme.ai/
Author: sumteam
Author-email: team@sumtyme.ai
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

## Embedded Intelligence Platform

A Python client for interacting with the **Embedded Intelligence Platform (EIP)**

The EIP is powered by **Abstract Generalised Networks (AGNs)**, a proprietary AI architecture designed to model how complex systems evolve. Unlike traditional machine learning, AGNs autonomously rewrite their underlying algorithms as they observe new data. This allows them to holistically understand how directional shifts influence a system in domains like financial markets and weather without the need for training, fine-tuning, or retraining.

This client provides direct access to the EIP's capabilities for understanding directional changes and system evolution, rather than simply predicting the next step.

## Getting Started


### Installation

You can install this package via pip.

```bash
pip install sumtyme
```

### Client Initialisation and API Key
To use the client, you need an API key and must initialise the `EIPClient` with a subdomain.


#### Option 1: Use an Existing API Key
If you already have an API key, we recommend saving it as a config.txt within your environment and passing it to the `apikey_path` variable during initialisation.

**Create a `config.txt` file:**
```dotenv
apikey="your-api-key-here"
```

Then, initialise the client in your code:


```python
from sumtyme import EIPClient

# Replace 'your-subdomain' with your assigned EIP subdomain.
client = EIPClient(subdomain='your-subdomain',apikey_path='config.txt')
```


#### Option 2: Sign Up for a New API Key

If you do not yet have an API key, you can register as a new user and obtain one directly through the client's `user_signup`. This function will send a sign-up request to the EIP, return your API key and automatically save it to a local config.txt file. After signing up, email team@sumtyme.ai for account activation.


```python
# Initialise the client with your subdomain
client = EIPClient(subdomain='your-subdomain',apikey_path=None)

# Register a new user and get your API key
signup_result = client.user_signup(payload={
    "email": "your_email@example.com",
    "password": "min_password_length_8",
    "confirm_password":"min_password_length_8"
})
```

### Core Functionality

AGNs are not autoregressive and analyse the entire data window simultaneously. Therefore, any outputs observed before the last data period of a window should be used for context and not as a prediction. The recommended window size is 5001 data periods.

#### Modelling the Environment

The `model_timeseries_environment` function shows the AGN's modelling process of the entire environment based on the observed data. This function accepts a single dataset of 5,001 to 10,000 data periods.

```python
# See the entire model generated by the AGN for the submitted data

entire_model = client.model_timeseries_environment(
    data_input='folder/ohlc_data.csv', # or can be a pandas dataframe 
    interval=1,
    interval_unit='days',
    reasoning_mode='reactive',
    output_file='saved_output'
)

# Returns a dataframe with columns: [datetime, trend_identified]
# Trend values: 1 (positive change), -1 (negative change), 0 (no clear change)
```

#### Identifying the Latest Directional Change

The 'identify_timeseries_directional_change' function determines if a directional change is forecasted for the final period. This function requires at least 5,001 data periods.

```python 
# Identify if a directional change exists at the last data period

latest_change = client.identify_timeseries_directional_change(
    data_input='folder/ohlc_data.csv', # or can be a pandas dataframe 
    interval=1,
    interval_unit='days',
    reasoning_mode='reactive'
)

# Returns a list: [datetime_string, trend_value]
# Trend values: 1 (positive change), -1 (negative change), 0 (no clear change)
```

#### Rolling Window Analysis

The `get_timeseries_rolling_directional_changes` function performs a rolling analysis on the submitted datato identify if a directional change is forecasted for the final period within each window. This is ideal for backtesting or observing how trends evolve over time.

```python
# Performs a rolling window analysis on the observed data

rolling_trends = client.get_timeseries_rolling_directional_changes(
    data_input='folder/ohlc_data.csv', # or can be a pandas dataframe 
    interval=1,
    interval_unit='days',
    reasoning_mode='proactive',
    window_size=5001,
    output_file='saved_output'
)

# Returns a dataframe with columns: [datetime, trend_identified]
# Trend values: 1 (positive change), -1 (negative change), 0 (no clear change)
```


#### Track Propagations

The `track_propagations` function models a system's directional evolution by tracking how indicators of change propagate across different timeframes. It identifies a "true change" or stable trend only when an initial signal, typically from a shorter timeframe, successfully propagates to a longer one without being contradicted. This process allows you to assess both the existence and the magnitude and stability of a trend as it develops.

```python
# Models how directional indicators propagate across different timeframes to identify stable trends.

propagation_data = client.track_propagations(
    data_input_list=['folder/ohlc_1s','folder/ohlc_2s','folder/ohlc_3s'], # or can be list of dataframes
    propagation_level = 2 # tracks only propagations that reach this specific level.
)

# Returns a dataframe with columns: [datetime,trend_identified,propagation_level]
```

#### Calculate Directional Change

The `calculate_directional_change` function measures the difference between each successful propagation from the initial directional indicator.

```python
# Models how directional indicators propagate across different timeframes to identify stable trends.

directional_change = client.calculate_directional_change(
    price_data='folder/ohlc_data.csv', # or can be a pandas dataframe 
    propagation_data='folder/propagation_data.csv' # or can be a pandas dataframe 
)

# Returns a dataframe with columns: [datetime,open,trend_identified,propagation_level,directional_change]
```

