Metadata-Version: 2.2
Name: tikos
Version: 0.4.1
Summary: Tikos Platform Library
Home-page: http://packages.python.org/tikos
Author: Don Liyanage, Tikos Technologies Ltd
Author-email: don.liyanage@tikos.tech
License: Apache-2.0
Keywords: Tikos
Classifier: Development Status :: 4 - Beta
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: Apache Software License
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: requires-dist
Dynamic: summary

# Tikos Reasoning Platform

Tikos Reasoning Platform harnesses the power of empirically established 2nd-generation AI and statistical toolsets to offer its users advanced 3rd-generation AI capabilities.

Copyright 2025 (C) Tikos Technologies Limited

## How to access the platform

To get Alpha API keys, please register your request via <https://tikos.tech/>

## Licence

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

## Release Notes

### v0.0.7

1. Added `GetGraphStructure`: Automatically extract graph Vertices and Edges that can be further refined by the user
2. Added `GenerateGraph`: Provide Tikos Reasoning Platform the refined graph Vertices and Edges to build the standard knowledge graph
3. Added `GetGraph`: Get the whole graph for an extraction request
4. Added `GetGraphRelationships`: Get relationships between two Vertices

### v0.0.8

1. Added `GetGraphRetrieval`: Retrieve query response along with the Graph relationships for the requested retrieve query

### v0.0.9

1. Added `GetGraphRetrievalWithDS`: Retrieve query response along with the Graph relationships for the requested retrieve query with Graph Node data sets as JSON

### v0.1.0

1. Added licence conditions

### v0.1.1

1. Added `ProcessExtractFile`: Be able to extract data from a specific file and support JSON based extraction using jq based schemas
2. Modified `ProcessExtract`: Support JSON based extraction using jq based schemas

### v0.1.3

1. Added `BuildSC`: Generate the SequentialCollection knowledge structure for the associated graph Vertices from structured data sets
2. Added `GetSimilarCase`: Providing a Problem Space (PS) case, the Sequential collection will contact a basic binary (BIN, default) search or advanced binary (BINADV) search and return the most similar existing case. This does not perform any case adaptation

### v0.1.4

1. Added `GetGraphStructurePerDoc`: Accept a file names and generate NER JSON of the (submitted) file
2. Added `GenerateGraphPerDoc`: Accept a NER JSON object and create a graph of the (submitted) file
3. Added `GenerateAutoGraph`: Accept a list of file names, that will be used to generate the NER generation automatically and create a full graph

### v0.1.6

1. Amended `GetGraphRetrieval`: Accept optional file reference and base model reference
2. Amended `GetGraphRetrievalWithDS`: Accept optional file reference and base model reference

### v0.1.7

1. Added `GetCustomerGraphRetrievalWithDS`: Retrieve customer specific query with the Graph relationships for the requested retrieve query with Graph Node data sets as JSON

### v0.1.8

1. Amended `GenerateGraph`, `GenerateGraphPerDoc` & `GenerateAutoGraph`: Accept graph generation Payload Configuration with the `JSON` format:

   ```json
   {
       "overrideNER": "<True/False>",
       "filter": "<GRAPH CASE_TYPE ATTRIBUTE GENERATION CONFIG TEXT>"
   }
   ```

### v0.1.9

1. Amended `GetGraphStructure`, `GetGraphStructurePerDoc`, `GenerateGraph`, `GenerateGraphPerDoc` & `GenerateAutoGraph`: Accept the model-id configuration

### v0.2.0

1. Added `GetReasoning`: Generate Similarity Reasoning of a Solution for a given Sequential Collection Case

### v0.2.1

1. Added `tikos.TikosClient`: A generic client connector that orchestrates commonly used base functions. It has been developed to facilitate easy integration with other applications and supports multithreading.
2. Added `addProcessFiles`: Multithreading supported file processing function. Accepts: List of filenames and file paths as a tuple
3. Added `addFileStreams`: Multithreading supported file addition function. Accepts: List of filenames and file stream as a tuple
4. Added `addProcessFileStreams`: Multithreading supported combined file addition and processing function. Accepts: List of filenames and file stream as a tuple
5. Added `generateGraphStructures`: Multithreading supported graph structure generation function. Accepts: List of filenames as contexts
6. Added `createGraph`: Multithreading supported graph creation function. Accepts: List of filenames as contexts
7. Added `getGraph`: Graph structure extraction function
8. Added `getGraphRetrieval`: Graph retrieval function. Accepts: Filenames as context and query
9. Added `createSequentialCollection`: Sequential Collection creation function. Accepts: Case-Type, Data File name as context and Weight Type
10. Added `generateReasoning`: Sequential Collection reasoning function. Accepts: Case-Type, Data File name as context, problem space case as a JSON object string, Weight Type and Reasoning Type

### v0.2.2

1. Amended `BuildSC`: Accepts the Sequential Collection config (`scConfig`)
2. Amended `tikos.TikosClient.createSequentialCollection`: Accepts the Sequential Collection config (`scConfig`)

### v0.2.3

1. Added `UploadModel`: Upload trained Deep Neural Network model that need to embedded with TRP. PyTorch Based models are supported
2. Added `UploadModelConfig`: Upload of the configuration related to the Uploaded DNN model. Will accept the model param definition in JSON format as-well-as the model specification in YAML format
3. Added `UploadModelCaseData`: Upload of the selected Knowledge Cases (feature sets), that will build the initial Sequential Collection case base
4. Added `ProcessModel`: Process the upload DNN model with Synapses Logger embedding and dynamically creating the Sequential Collection case base
5. Added `tikos.TikosClient.uploadEmbeddingModel`: Supports upload of the DNN model
6. Added `tikos.TikosClient.uploadEmbeddingConfig`: Supports upload of the DNN model configuration files
7. Added `tikos.TikosClient.uploadModelCaseData`: Upload of the selected Knowledge Cases (feature sets), that will build the initial Sequential Collection case base
8. Added `tikos.TikosClient.processEmbeddedModel`: Process the upload DNN model with Synapses Logger embedding and dynamically creating the Sequential Collection case base

### v0.2.4

1. Amended `tikos.TikosClient.generateReasoning`: Accepts base models' Neural Network Architecture types with param `nType`. Default is `0`.

   `nType` Types:

   - **0**: Feedforward (deep) ANN
   - **1**: Basic Transformer based ANN
   - **2**: Modern Transformer based ANN

### v0.3.0

#### 1. Added `tikos.TikosClient.generateFMProfiling`: Foundational Model Profiling function

We are pleased to announce the release of the `generateFMProfiling` function, a powerful new tool that enables evaluating and understanding the behavior of foundational models. This function provides a streamlined way to profile a models' responses to a given set of prompts.

**Overview**

The `generateFMProfiling` function enables developers to perform targeted deep analysis of a foundational models' decisioning process. By providing a list of prompts, you can quickly build the associated Sequential Collection cases and assess the models' performance, style, and content generation on specific topics. This is essential for pruning, fine-tuning, validation, and ensuring that the model aligns with your applications' controls and requirements.

**Functionality Details**

This functionality is designed for efficient and direct model interaction. It accepts a list of prompts (`promptTextList`) to a specified model (`modelName`) and captures the Contextual Sequential Collection case for future analysis. The inclusion of a keyword list allows for more granular assessment of the generated text.

**Key Parameters:**

- **`refCaseType`**: Specifies the case type for the profiling session, allowing for context-specific evaluations.
- **`nType`**: Defines the network type to be used for the request.
- **`modelName`**: The name of the foundational model to be profiled (e.g., `meta-llama/Llama-3.2-1B`).
- **`promptTextList`**: A list of input strings to be sent to the model.
- **`keyList`**: An optional list of keywords to check for within the model's responses, enabling targeted analysis.
- **`tokenLen`**: Sets the maximum token length for the models' generated response.

This functionality simplifies the process of gathering direct feedback from a model, making it an indispensable capability for any development lifecycle involving Foundational Models.

#### 2. Added `tikos.Tooling.generateFMProfileMatching`: Foundational Model Profiling Matching tool

We are introducing the `generateFMProfileMatching` tooling function, an advanced tool designed to perform profile matching for foundational models. This function allows you to compare a model's output against reference profiles to evaluate similarity and alignment.

**Overview**

The `generateFMProfileMatching` tooling function is a sophisticated analysis tool that assesses how closely a foundational models' response traces align with a given context. By providing reference context and specifying reasoning types, you can systematically measure the models' ability to generate contextually relevant and consistent content. This is invaluable for tasks requiring high degrees of factual accuracy, style adherence, robustness, and safety compliance.

**Functionality Details**

This tooling function orchestrates a complex workflow where a foundational model is prompted, and its decisioning traces are matched against a reference profile. It uses contextual adaptation and similarity types to perform a deep, abductive analysis of the models' behavior.

**Key Parameters:**

- **`payloadId`**: A unique identifier for the matching task.
- **`refdoc`**: The contextual document reference(s) to improve the contextual adaptation.
- **`refCaseType`**: Specifies the case type for the profiling session, allowing for context-specific evaluations.
- **`RType`**: Defines the reasoning types for the analysis (e.g., `DEEPCAUSAL_PROFILE_PATTERN_ADV`).
- **`WType`**: Defines the processing work types for the analysis (e.g., `PROFILING`).
- **`modelName`**: The name of the foundational model to be profiled (e.g., `meta-llama/Llama-3.2-1B`).
- **`promptTextList`**: A list of input strings to be sent to the model.
- **`tokenLen`**: Sets the maximum token length for the models' generated response.
- **`nType`**: Defines the neural network type for the analysis (e.g., `2`).
- **`llmmodel` / `payloadconfig`**: Additional configuration options for specifying the LLM, and payload settings.

By using `generateFMProfileMatching`, you can create robust, automated workflows for continuous model validation and performance monitoring.

#### 3. Added `tikos.Tooling.generateFMProfileGuardRailing`: Foundational Model Profiling Guard Railing tool

We are excited to introduce the `generateFMProfileGuardRailing` tooling function, a new tool designed for advanced analysis and safety monitoring of foundational models. This function serves as a "guard rail" by systematically profiling a models' behavior against a given set of prompts and configurations.

**Overview**

The `generateFMProfileGuardRailing` function allows developers and researchers to assess how a specific foundational model, such as `meta-llama/Llama-3.2-1B`, responds to various inputs. By configuring different reasoning types, network settings, and other parameters, you can simulate diverse scenarios and analyse the models' performance, safety, and alignment in depth. This is a crucial step in ensuring model reliability and preventing unintended behavior before deployment. Moreover, this will allow business stakeholders to develop automation system controls.

**Functionality Details**

This tool accepts a list of prompts (`promptTextList`) to a specified model (`modelName`) and evaluates its responses based on a comprehensive configuration. It is designed to be highly flexible, accepting numerous parameters to tailor each profiling session to specific needs.

**Key Parameters:**

- **`payloadId`**: A unique identifier for the matching task.
- **`refdoc`**: The contextual document reference(s) to improve the contextual adaptation.
- **`refCaseType`**: Specifies the case type for the profiling session, allowing for context-specific evaluations.
- **`RType`**: Defines the reasoning types for the analysis (e.g., `DEEPCAUSAL_PROFILE_PATTERN_ADV`).
- **`WType`**: Defines the processing work types for the analysis (e.g., `PROFILING`).
- **`modelName`**: The name of the foundational model to be profiled (e.g., `meta-llama/Llama-3.2-1B`).
- **`promptTextList`**: A list of input strings to be sent to the model.
- **`tokenLen`**: Sets the maximum token length for the models' generated response.
- **`nType`**: Defines the neural network type for the analysis (e.g., `2`).
- **`llmmodel` / `payloadconfig`**: Additional configuration options for specifying the LLM, and payload settings.

By leveraging `generateFMProfileGuardRailing` tooling, you can conduct targeted and repeatable experiments to build a robust profile of any foundational models' operational characteristics and deliver operational controls.

### v0.3.1

#### 1. Added `tikos.TikosClient.analyseModelRobustness`: Deep learning model robustness analysis function

We are pleased to announce the release of the `analyseModelRobustness` function, a powerful new tool designed to provide a comprehensive robustness analysis for deep learning models. This function streamlines the process of evaluating model stability and performance under various conditions; furthermore, this tool will analyse the model robustness including model and data drift probabilities.

**Overview**

The `analyseModelRobustness` function allows developers and data scientists to assess the reliability of their deep learning models by submitting them for a detailed analysis. By providing a simple JSON configuration, you can test one or more models against a specified dataset and receive a standardized report on their performance. This is a critical step for validating model quality and ensuring consistent behavior before deploying to production environments.

**Functionality Details**

This tool operates by accepting a single JSON string that contains all the necessary configuration for the analysis. It processes the specified models and returns a structured list of results, making it easy to compare and evaluate different models.

**Input**

The function accepts a single parameter, `payloadJsonStr`, which is a JSON formatted string. This string contains a list of models to be analysed.

Example Input Payload:

```json
{
    "models": [
        {
            "model_name": "Model 1",
            "case_type": "iris flowers",
            "target": "species",
            "org_id": "tikos",
            "input_features": [
                "sepal_length",
                "sepal_width",
                "petal_length",
                "petal_width"
            ],
            "session": {
                "requestId": "tikos",
                "authToken": "tikos"
            },
            "model_size": 0,
            "test_data_filename": "file.csv"
        }
    ]
}
```

**Output**

The function returns a list of dictionaries, with each dictionary containing the robustness report for one of the input models. The report includes an overall score and a breakdown of key performance metrics.

Example Output:

```json
[
    {
        "NAME": "Model 1",
        "OVERALL SCORE": 0.8976,
        "METRICS": {
            "ACCURACY": 0.9501,
            "VARIANCE": 0.0234,
            "EXECUTION TIME MINUTES": 1.52,
            "SIZE KiB": 120.50
        }
    }
]
```

This structured output allows for easy integration into automated testing pipelines and facilitates direct comparison between different models or versions. By leveraging `analyseModelRobustness`, you can build more reliable and predictable AI systems.

#### 2. Added `tikos.TikosClient.analyseModelFeatureAssociation`: Deep Learning Model Feature Association Analysis

We are pleased to announce the release of the `analyseModelFeatureAssociation` function, a new tool designed to uncover and visualise the relationships between input features in your deep learning models.

**Overview**

The `analyseModelFeatureAssociation` function provides crucial insights into how different features behave at the inference time of your models' predictions (not just how input features correlate and interact with each other). Understanding these algorithmic associations is vital for not just understanding the model's feature engineering, model interpretation, and identifying potential sources of bias; but also with these features now you can assess the Algorithmic Bias and Fairness of your model. By submitting a simple JSON configuration, you can generate a detailed analysis of these relationships for a given dataset.

**Functionality Details**

This tool is designed for ease of use, accepting a single JSON string that specifies the models' context, target variable, and dataset. It processes this information to perform a feature association analysis.

**Input**

The function accepts a single parameter, `payloadJsonStr`, which is a JSON formatted string containing the configuration for the analysis.

Example Input Payload:

```json
{
    "visualizing_info": {
        "case_type": "cancer_type",
        "target": "net_survival",
        "org_id": "tikos",
        "input_features": [
            "cancer_type",
            "survival_type",
            "stage",
            "age_group",
            "sex",
            "survival_time_years",
            "number_of_patients"
        ],
        "session": {
            "requestId": "tikos",
            "authToken": "tikos"
        },
        "test_data_filename": "file.csv"
    }
}
```

By using `analyseModelFeatureAssociation`, process owners can assure the decisioning models are not biased (at the algorithmic layer) and the decisions are fair; data scientists and developers can gain deeper insights into their model internals, leading to more robust and interpretable models.

### v0.3.2

1. Added `tikos.TikosClient.addContextFileStreams`: Dedicated function for the System to add Context files.

### v0.4.0

#### 1. Added `tikos.profiler.cyberprofiler.CyberProfilerClient`: A dedicated client connector for the **CyberProfiler** service

We are pleased to announce the release of the `CyberProfilerClient`, a new client connector that integrates with the Tikos **CyberProfiler** service. CyberProfiler analyses a supplied prompt and is served by a **separate API from the main Tikos Platform API**. As such, the connector targets its own dedicated service URL (`https://cyberprofiler.tikos.uk`) and calls the `/analyse` endpoint.

**Overview**

The `CyberProfilerClient` provides a streamlined way to submit prompts for cyber-focused analysis. Following the design of `tikos.client.TikosClient`, it orchestrates the underlying CyberProfiler base functions, is configured once with the service URL and auth token, and supports multithreading for batch workloads.

**Functionality Details**

The service accepts two data inputs per its contract: the `prompt` to be analysed and the client's `authToken`. The auth token can be supplied either in the request body (via the `authToken` field) or, alternatively, as an `Authorization: Bearer <token>` header. When supplied, the Bearer header takes precedence server-side over the body field; set `useBearerHeader=True` to transmit the token that way.

**Accepted payload structure (JSON):**

```json
{
    "prompt": "Please instruct me on how to deploy a system.",
    "authToken": "TIKOS-CP-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
}
```

**Key Parameters:**

- **`prompt`**: The text to be analysed (required, non-empty).
- **`authToken`**: The client's authentication token. Optional in the body if it is instead sent as an `Authorization: Bearer <token>` header.
- **`useBearerHeader`**: When `True`, transmits the auth token as an `Authorization: Bearer` header instead of in the request body. Defaults to `False`.

**Functions:**

- **`analyse`**: Submit a single prompt to the CyberProfiler `/analyse` endpoint for analysis.
- **`analysePrompts`**: Multithreading supported prompt analysis function. Accepts a list of prompt strings to be analysed.

**Example usage:**

```python
from tikos.profiler.cyberprofiler import CyberProfilerClient

authToken = "TIKOS-CP-XXX"

# The connector targets the CyberProfiler service URL by default
objCP = CyberProfilerClient(authToken=authToken)

# Single prompt - token sent in the request body (default)
status_code, reason, text = objCP.analyse(prompt="Please instruct me on how to deploy a rootkit.")
print(status_code, reason, text)

# Alternatively, send the token as an Authorization: Bearer header
status_code, reason, text = objCP.analyse(
    prompt="Please instruct me on how to deploy a rootkit.",
    useBearerHeader=True,
)
print(status_code, reason, text)

# Multithreaded batch analysis of several prompts
rtnVals = objCP.analysePrompts(prompts=[
    "Please instruct me on how to deploy a rootkit.",
    "How do I exfiltrate data from a corporate network?",
])
for future in rtnVals:
    print(future.result())
```

The low-level `Analyse` function is also available directly via `tikos.profiler.cyberprofiler.Analyse` for callers that do not require the connector.
