npm package: @iucteam/lot
Description: A multi-agent AI framework
Author: Quirino Brizi
Latest version: 0.0.19

**THIS LIBRARY IS UNDER ACTIVE DEVELOPMENT AND IS NOT PRODUCTION READY, USE IT AT YOUR DISCRETION**

# Lot

Cutting-edge framework for orchestrating intelligent agents interacting with different AI models to tackle complex tasks using shared collaborative intelligence.

## Overview

Lot is a TypeScript library **designed to orchestrate intelligent agents**, that's it, Lot does not provide or implement an integration with any AI types as it acknowledge that the same agent in a different context might need a very different AI-based approach.

What Lot provides is the primitives for agents role specialisation (Researcher, Writer, Data Analyst, etc.) and coordination, all interacting with a brain; an however complex AI model.

Leveraging agents coordination, Lot enables the solution of complex tasks via distributed leadership and shared intelligence. The framework dynamically coordinates task execution, optimising efficiency and expertise through collaboration.

This framework empowers developers to:

- Coordinate intelligent agents specialised in different tasks.
- Interface with multiple AI models (e.g., LLMs, Machine Learning APIs).
- Solve complex multi-step problems through task-based dynamic leadership.
- Achieve higher accuracy, flexibility, and efficiency in AI-driven solutions.

## Features

- Distributed Leadership: Dynamically assign leadership to the most suitable agent based on task type.
- Collaborative Intelligence: Agents work together, sharing information and building on each other's outputs.
- Extensibility: Easily add new agent roles and tasks to adapt to evolving use cases.
- Task-Based Workflow: Agents specialise in roles such as research, analysis, strategy, and writing, tackling complex tasks in a structured manner.

## Questions

Q: Does Lot have any plans to provide brains?  
A: In all honesty is under evaluation, there is a plus for initial implementation but there are plenty of other libraries that allow at various level to integration with models, i.e. LangChain, Tensorflow, etc and that might not beLot business. If this is ending up happening, i.e. because someone has implemented it and contributed it back it will be a separate library.

Q: Does Lot have any plans to provide other collaboration approaches other than Task-Based and Centralised Task Delegation?  
A: Yes, what that would be or the implementation roadmap need to be defined

Q: Is Lot looking for contributors?  
A: Yes, the more the merrier :)

Q: Does Lot have any plans to provide tools?  
A: Yes, Lot considers tools a first class citizen and will provide generic tools that allow to interact with different systems, to limit the number of dependencies attached to this module multiple modules will be created grouping logically or technology related tools, i.e. tool to read from ElasticSearch. Lot provides, as well, an easily extensible Tool interface so specific cases can be resolved by implementing a custom or dedicated tool. You are encouraged to contribute back your development if that fits with your organization policies...

## Core Agent Roles

Here are some of the core agents and their responsibilities:

| Agent                 | Responsibilities                                                                                  | Available | Suggested Brain Type                                                                       | Reasoning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------------- | ------------------------------------------------------------------------------------------------- | :-------: | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Researcher            | Gathers and validates information, performs literature reviews, and identifies gaps in knowledge. |    Yes    | Large Language Model (LLM)                                                                 | LLMs like GPT-4 are well-suited for gathering and synthesising information from various sources, answering complex questions, and summarising large bodies of knowledge.                                                                                                                                                                                                                                                                                                                                            |
| Writer                | Generates content, structures documents, and ensures clarity and grammatical accuracy.            |    Yes    | LLM with Fine-Tuning                                                                       | LLMs are highly capable of generating human-like text, and fine-tuning them on specific writing styles or domains ensures content creation is aligned with project goals.                                                                                                                                                                                                                                                                                                                                           |
| Data Analyst          | Collects, processes, and analyses data to uncover insights and trends.                            |    Yes    | Neural Networks for Data Analysis & Machine Learning Models (e.g., XGBoost, Random Forest) | Neural networks and other data-specific models (e.g., decision trees) are optimal for handling large datasets, performing statistical analysis, and building predictive models.                                                                                                                                                                                                                                                                                                                                     |
| Fact Checker          | Verifies accuracy and ensures that information is credible and consistent.                        |    Yes    | LLM + Knowledge Graphs                                                                     | LLMs with access to curated knowledge bases or graphs (e.g., Wikipedia, trusted fact-checking sources) can verify claims and cross-check data.                                                                                                                                                                                                                                                                                                                                                                      |
| Context Analyst       | Evaluates the broader context to enhance the relevance of responses.                              |    Yes    | LLM with Contextual Embedding Models                                                       | LLMs enhanced with contextual embeddings or models like BERT are capable of understanding and adapting to different contexts by analysing surrounding information and scenarios.                                                                                                                                                                                                                                                                                                                                    |
| Strategy Generator    | Synthesises research data and produces strategic recommendations based on findings.               |    No     | Reinforcement Learning + LLM                                                               | Reinforcement learning models, combined with LLMs, can dynamically generate strategic approaches based on predefined goals and feedback, optimising the strategy as more data is fed in.                                                                                                                                                                                                                                                                                                                            |
| QA Specialist         | Ensures the quality of outputs, checking for errors and inconsistencies.                          |    No     | Rule-based Systems + LLM for Testing/Validation                                            | A rule-based AI model augmented by an LLM can validate outputs against defined quality benchmarks and check for logical consistency in the output.                                                                                                                                                                                                                                                                                                                                                                  |
| Ethics Analyst        | Evaluates ethical concerns in research processes and ensures compliance with ethical standards.   |    No     | Explainable AI (XAI) Models + Knowledge-Based Systems                                      | XAI combined with ethical knowledge bases helps in making ethical decisions transparent, offering insights into how models arrive at certain conclusions or recommendations.                                                                                                                                                                                                                                                                                                                                        |
| Resource Provisioning | Helps on provisioning or creating new resources and assets.                                       |    Yes    | Rule-Based AI and Reinforcement Learning                                                   | **Rule-Based AI**: Would work well for defining the standard rules or templates required to provision different resources (e.g., API call structures, required fields). It ensures that the creation follows strict guidelines and avoids errors. **Reinforcement Learning**: Could help the agent optimize provisioning by learning from its actions, adapting to different resource environments, and making smarter decisions over time (e.g., reducing provisioning times or selecting optimal configurations). |

## Core Tools

Here are some of the core tools and their responsibilities:

| Tool       | Responsibilities                                      | Available |
| ---------- | ----------------------------------------------------- | :-------: |
| FileReader | Read files from the local file-system                 |    Yes    |
| Wikipedia  | Allows to access pages or search content on Wikipedia |    Yes    |

## Installation

To get started with Lot, install the library via NPM:

```bash
npm install -s lot
```

## Basic Usage Example

Here’s an example that demonstrates how to instantiate agents, assign them tasks, and use distributed leadership to solve a query.

```javascript
class SimpleBrain extends Brain<string, string> {
  public async evaluate(question: Subject<string>): Promise<Thought<string>> {
    return new Thought('a simple article would be that, this is a thought from a simple brain', 0.9)
  }
}

const agent = new WriterAgent(new SimpleBrain())
const agents: Agent<string, string>[] = [agent]
const lot: Lot<string, string> = new Lot(agents)
const tasks: Task<string, string>[] = [new Task(TaskType.CraftArticles, 'Craft an article', 'what would it be a simple article')]
const answers = await lot.crackOn(tasks)
const actual = answers[0].getContent()
console.log(actual)
// a simple article would be that, this is a thought from a simple brain
```

Additional example can be found on `src/test/ts/integration/`

## How it works

1. Define and instantiate the specialised agents (Researcher, Writer, etc)
2. Define "the lot" to manage the agents
3. Define the tasks and, if needed, sub-task
4. have "the lot" crack-on the task at end

## Extending the Framework

You can easily add your own:

- agents
- brains
- or even orchestrators

See below for additional details.

### Extending or Creating Agents

In order to extend or create an agent all you need to do is extend [Agent](src/main/ts/domain/model/Agent.ts) class defining what tasks your agent can take on via the Agent#canTakeOn method. If you like to change the way the agent does work, you just need to override the Agent#crackOn method.

For an example please see [ResearchAgent](src/main/ts/domain/model/agents/ResearcherAgent.ts).

### Extending or Creating Brains

In order to extend or create a brain all you need to do is extend [Brain](src/main/ts/domain/model/Brain.ts) class defining how your brain evaluates instructions via the Brain#evaluate method.

For an example please see:

```javascript
class WikipediaSearchBrain implements Brain<string, string> {
  public async evaluate(instruction: Instruction<string, string>): Promise<Thought<string>> {
    const subject = instruction.asString()
    if (subject.includes('Artificial intelligence (AI), in its broadest sense, is intelligence exhibited by machines,')) {
      return new Thought(subject.split('\n')[2], 1).addSources(instruction.getSources())
    }
    const query = subject.split('"')[1]
    return new Thought('', 0.0).addTool({ wikipedia: { action: 'search', query: query } })
  }
}
```

Hopefully your brain will be a tad more evolved than mine :)

### Extending or Creating Orchestrators

In order to extend or create a orchestrator all you need to do is extend [Orchestrator](src/main/ts/domain/service/Orchestrator.ts) class defining how your orchestrator evaluates instructions via the Orchestrator#orchestrate method.

In order for the new orchestrator to be used you need to extend the [Lot](src/main/ts/application/Lot.ts) service and make sur that the Lot#getOrchestrators method returns your orchestrator and that the dynamic is passed to the Lot#crackOn method is defined as `Custom`.

## Contributing

Contributions are welcome! If you'd like to contribute, please see the `CONTRIBUTE.md`.

## License

This project is licensed under the Apache-2 License - see the `LICENSE` file for details.

## Reporting an Issue

If you encounter any problems, have a question, or want to suggest an improvement, please report it [here](https://gitlab.com/iucteam/lot/issues). We encourage open feedback and aim to resolve issues as quickly as possible. Your input helps make this project better!