agentnet 0.0.1

package/LICENSE.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Helium S.r.l
+
+   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.

package/README.md

@@ -0,0 +1,488 @@
+# SmartAgent Framework
+
+SmartAgent is a flexible, extensible framework for building and orchestrating LLM-powered agents that can communicate, collaborate, and leverage tools to solve complex tasks. It is specifically designed to develop autonomous networks of agents that can work together to accomplish sophisticated objectives with minimal human intervention.
+
+## Table of Contents
+
+- [Declarative Agent Definitions](#declarative-agent-definitions)
+  - [Static Definitions (YAML)](#static-definitions-yaml)
+  - [Dynamic Implementation (JavaScript)](#dynamic-implementation-javascript)
+  - [Multi-Agent Systems with YAML](#multi-agent-systems-with-yaml)
+- [Key Features](#key-features)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+  - [Agents](#agents)
+  - [Agent Configuration](#agent-configuration)
+  - [Tool Binding](#tool-binding)
+  - [Transport Mechanisms](#transport-mechanisms)
+  - [Agent Auto-Discovery](#agent-auto-discovery)
+  - [Agent Handoffs](#agent-handoffs)
+- [Advanced Usage](#advanced-usage)
+  - [Events and Hooks](#events-and-hooks)
+  - [Multi-Agent Systems](#multi-agent-systems)
+  - [Session State Management](#session-state-management)
+- [Installation](#installation)
+- [License](#license)
+
+## Declarative Agent Definitions
+
+A key feature of SmartAgent is the ability to define agents declaratively using YAML files, separating the static definition of agents from their dynamic runtime behavior:
+
+### Static Definitions (YAML)
+
+Agents can be defined in YAML files that specify:
+- Metadata (name, description)
+- LLM configuration (provider, model, system instructions)
+- Transport mechanisms (NATS, etc.)
+- Tool schemas (name, description, parameters)
+- Discovery schemas for inter-agent communication
+
+Example YAML definition:
+
+```yaml
+---
+apiVersion: smartagent.io/v1alpha1
+kind: AgentDefinition
+metadata:
+  name: bookingAgent
+  namespace: smartchat
+spec:
+  io:
+    - type: NatsIO
+      bindings:
+        discoveryTopic: smartness.discovery
+        doHandoffsTo:
+          - "smartness.accomodation.*"
+
+  llm:
+    provider: Gemini
+    model: gemini-2.0-flash
+    systemInstruction: |
+      You are a highly advanced booking agent. 
+      Prioritize clarity and helpfulness.
+      Use tools effectively to gather information.
+    config:
+      temperature: 0.5
+      toolConfig:
+        functionCallingConfig:
+          mode: 'auto'
+
+  tools:
+    - name: bookRoomTool
+      description: Book a room to a specific hotel and room.
+      parameters:
+        type: object
+        properties:
+          hotelName:
+            type: string
+            description: The name of the hotel.
+          roomName:
+            type: string
+            description: The name of the room.
+          checkinDate:
+            type: string
+            description: The check-in date.
+          checkoutDate:
+            type: string
+            description: The check-out date.
+        required:
+          - hotelName
+          - roomName
+
+  discoverySchemas:
+    - name: booking_agent_query
+      description: Perform a booking to a specific hotel and room.
+      parameters:
+        type: object
+        properties:
+          hotelName:
+            type: string
+            description: The name of the hotel.
+          roomName:
+            type: string
+            description: The name of the room.
+```
+
+You can define multiple agents in a single YAML file using YAML document separators (`---`). Each agent can have its own specialized role in a multi-agent system.
+
+### Dynamic Implementation (JavaScript)
+
+The YAML definitions are loaded at runtime, and tool implementations are dynamically bound using JavaScript:
+
+```javascript
+// Load all agents from a YAML file
+const agents = await AgentLoaderFile('./agents.yaml', {
+  bindings: { [Bindings.NatsIO]: natsInstance }
+});
+
+// Access a specific agent
+const bookingAgent = agents.bookingAgent;
+const pricingAgent = agents.pricingAgent;
+
+// Bind tool implementations
+bookingAgent.tools.bookRoomTool.bind(async (state, input) => {
+  // Actual implementation to book a room
+  return { 
+    confirmation: `Room ${input.roomName} booked at ${input.hotelName} 
+                  from ${input.checkinDate} to ${input.checkoutDate}` 
+  };
+});
+
+// Customize prompt/response handling
+bookingAgent.prompt((state, input) => {
+  // Pre-process input before sending to LLM
+  console.log(`Received booking request: ${input}`);
+  return input;
+});
+
+bookingAgent.response((state, conversation, result) => {
+  // Post-process response from LLM
+  return `Booking confirmation: ${result}`;
+});
+
+// Compile all agents to make them ready for use
+await bookingAgent.compile();
+await pricingAgent.compile();
+```
+
+This separation of concerns allows for:
+- Version-controlled agent definitions
+- Reusable tool schemas
+- Dynamic runtime implementation
+- Easy testing and deployment
+- Clear separation between definition and implementation
+
+### Multi-Agent Systems with YAML
+
+The framework excels at creating autonomous multi-agent systems where specialized agents collaborate with minimal supervision. Each agent in the network can operate independently while maintaining awareness of other agents' capabilities. This creates a resilient, self-organizing system that can tackle complex tasks through agent collaboration. An example setup might include:
+
+```javascript
+// Load a set of specialized agents from YAML
+const agents = await AgentLoaderFile('./agents-smartness.yaml', {
+  bindings: { [Bindings.NatsIO]: natsIO }
+});
+
+// Configure each agent with specific tool implementations
+agents.accomodationAgent.tools.getRoomsListTool.bind(async (state, input) => {
+  // Implementation for listing available rooms
+  return { rooms: ["Double room with sea view", "Single room with pool view"] };
+});
+
+agents.pricingAgent.tools.getPricingTool.bind(async (state, input) => {
+  // Implementation for getting room prices
+  return { price: "200€ per night" };
+});
+
+agents.bookingAgent.tools.bookRoomTool.bind(async (state, input) => {
+  // Implementation for booking rooms
+  return { confirmation: "Booking confirmed" };
+});
+
+// Compile all agents
+await Promise.all(Object.values(agents).map(agent => agent.compile()));
+
+// Wait for agent discovery to complete
+await new Promise(resolve => setTimeout(resolve, 2000));
+
+// Query the main orchestrator agent
+const client = AgentClient();
+const response = await client.queryIo(
+  natsIO,
+  'smartnessAgent', 
+  "What rooms do you have available for next weekend and how much do they cost?"
+);
+```
+
+With this setup, the smartness agent will automatically discover and delegate to specialized agents for accommodation, pricing, and booking, creating an autonomous network that collectively solves the user's query.
+
+## Key Features
+
+- **Autonomous Agent Networks**: Create self-organizing networks of agents that can discover, communicate, and collaborate with minimal human intervention
+- **Modular Agent Architecture**: Create specialized agents with distinct capabilities and compose them to solve complex problems
+- **Transport Agnostic**: Work with agents directly or through transport mechanisms like NATS
+- **Auto-Discovery**: Agents can discover each other's capabilities dynamically at runtime
+- **Tool Binding**: Easily bind JavaScript functions to agent tools
+- **Agent Handoffs**: Seamlessly delegate tasks between agents
+- **LLM Provider Agnostic**: Support for multiple LLM providers (Gemini and extensible to others)
+- **Persistent Sessions**: Maintain conversation context and state across interactions
+
+## Quick Start
+
+```javascript
+import { Agent, Gemini, NatsIO } from "smartagent";
+
+// Create a simple agent
+const myAgent = Agent()
+  .setMetadata({
+    name: "myAgent",
+    description: "A helpful assistant"
+  })
+  .withLLM(Gemini, {
+    model: "gemini-pro",
+    systemInstruction: "You are a helpful assistant"
+  })
+  .addToolSchema({
+    name: "weatherTool",
+    description: "Get weather information",
+    parameters: {
+      location: "string"
+    }
+  });
+
+// Bind tool implementation
+const compiledAgent = await myAgent.compile();
+compiledAgent.tools.weatherTool.bind(async (state, input) => {
+  return { weather: "Sunny", temperature: 25 };
+});
+
+// Query the agent
+const response = await compiledAgent.query("What's the weather like in Paris?");
+console.log(response);
+```
+
+## Core Concepts
+
+### Agents
+
+Agents are the core building blocks of the framework. Each agent:
+
+- Has its own identity (name, description)
+- Can be configured with an LLM provider
+- Can define and implement tools
+- Can discover and communicate with other agents
+
+### Agent Configuration
+
+Agents can be configured programmatically or via YAML definitions:
+
+```javascript
+// Programmatic configuration
+const myAgent = Agent()
+  .setMetadata({ name: "myAgent" })
+  .withLLM(Gemini, { model: "gemini-pro" })
+  .addToolSchema(myToolSchema);
+
+// YAML-based configuration
+const agents = await AgentLoaderFile('./agents.yaml', {
+  bindings: { [Bindings.NatsIO]: natsInstance }
+});
+```
+
+### Tool Binding
+
+Tools allow agents to perform actions in the real world. Each tool:
+
+- Has a schema that defines its interface (name, description, parameters)
+- Has an implementation bound to it at runtime
+
+```javascript
+// Define tool schema
+agent.addToolSchema({
+  name: "fetchData",
+  description: "Fetch data from an API",
+  parameters: {
+    url: "string",
+    method: "string"
+  }
+});
+
+// Bind implementation
+agent.tools.fetchData.bind(async (state, input) => {
+  // Actual implementation
+  const response = await fetch(input.url, { method: input.method });
+  return await response.json();
+});
+```
+
+### Transport Mechanisms
+
+The framework supports different transport mechanisms for agent communication:
+
+#### Direct Communication
+
+Agents can be queried directly in the same process:
+
+```javascript
+const compiledAgent = await myAgent.compile();
+const response = await compiledAgent.query("Hello, agent!");
+```
+
+#### NATS-based Communication
+
+Agents can communicate through NATS for distributed deployments:
+
+```javascript
+// Initialize NATS transport
+const natsIO = NatsIO({ servers: ['nats://localhost:4222'] });
+
+// Configure agent with NATS transport
+const myAgent = Agent()
+  .setMetadata({ name: "distributedAgent" })
+  .addIO(natsIO, { bindings: { discoveryTopic: "agent.discovery" } })
+  .withLLM(Gemini, { model: "gemini-pro" });
+
+// Query an agent through NATS
+const client = AgentClient();
+const response = await client.queryIo(natsIO, 'distributedAgent', "Hello!");
+```
+
+### Agent Auto-Discovery
+
+Agents can discover each other's capabilities at runtime through a discovery protocol:
+
+1. Agents publish their capabilities (available tools and schemas) to a discovery topic
+2. Other agents subscribe to the discovery topic and build a catalog of available agents
+3. Agents can then delegate tasks to the most appropriate agent
+
+```javascript
+// Auto-discovery happens automatically when agents share the same transport
+// Just wait for discovery to complete
+await new Promise(resolve => setTimeout(resolve, 2000));
+
+// Now agents can communicate with each other
+```
+
+### Agent Handoffs
+
+Agents can delegate tasks to other agents with the right capabilities:
+
+1. An agent receives a task it can't handle directly
+2. It identifies another agent with the required capability
+3. It hands off the task to that agent
+4. The specialized agent processes the task and returns the result
+
+This happens transparently from the user's perspective, creating a seamless experience.
+
+## Advanced Usage
+
+### Events and Hooks
+
+Customize agent behavior with event hooks:
+
+```javascript
+agent.prompt((state, input) => {
+  // Customize input before it reaches the LLM
+  return `[Processed] ${input}`;
+});
+
+agent.response((state, conversation, result) => {
+  // Process the result before returning to the user
+  return `Agent says: ${result}`;
+});
+```
+
+### Multi-Agent Systems
+
+Create autonomous networks of specialized agents that collaborate without human intervention:
+
+```javascript
+// Create specialized agents
+const weatherAgent = Agent()
+  .setMetadata({ name: "weatherAgent" })
+  .addToolSchema(weatherToolSchema);
+
+const travelAgent = Agent()
+  .setMetadata({ name: "travelAgent" })
+  .addToolSchema(travelToolSchema);
+
+// The main agent that orchestrates others
+const smartAgent = Agent()
+  .setMetadata({ name: "smartAgent" })
+  .addDiscoverySchema(weatherDiscoverySchema)
+  .addDiscoverySchema(travelDiscoverySchema);
+
+// Compile and connect all agents
+await weatherAgent.compile();
+await travelAgent.compile();
+await smartAgent.compile();
+
+// Query through the main agent
+const response = await smartAgent.query(
+  "Plan a trip to Paris and tell me about the weather"
+);
+```
+
+In this autonomous network:
+- Each agent is responsible for a specific domain of expertise
+- The orchestrator agent (smartAgent) discovers and routes requests to appropriate specialists
+- The network can scale by adding more specialized agents without changing existing ones
+- Agents can be deployed across different environments while maintaining communication
+
+### Session State Management
+
+The SmartAgent framework provides robust session management for maintaining state across conversations and agent interactions:
+
+```javascript
+// Creating a message with session information
+const message = new Message({
+  content: "What rooms do you have available?",
+  session: {
+    id: "67a71e42-a7d8-1db2-ad17-64e1c8546b21",  // Reserved system ID
+    propertySetId: "123",                         // Custom session data
+    userPreferences: { roomType: "suite" }        // Custom session data
+  }
+});
+
+// Query the agent with session context
+const result = await agentInstance.query(message);
+```
+
+#### Session ID
+
+The `id` keyword in the session object is reserved for the system. It's used to uniquely identify the session for:
+- Loading session state from persistent storage
+- Saving session state back to storage
+- Tracking conversation history
+
+#### State Propagation
+
+Session variables have different scopes:
+
+1. **Regular variables** (without underscore prefix) are propagated between agents during handoffs, ensuring continuity of context across the agent system.
+
+2. **Private variables** (with underscore prefix `_`) are agent-specific and not shared during handoffs. For example:
+   ```javascript
+   message.session._agentPrivateData = "This stays with the current agent";
+   message.session.sharedData = "This is passed between agents";
+   ```
+
+When a session is saved to storage, private variables (starting with `_`) are saved on the agent store, but removed from response to the calling agent to keep the session data clean and focused on shareable information.
+
+#### Stores Configuration
+
+SmartAgent supports different storage backends for persisting session state:
+
+```javascript
+// Configure the agent with a Postgres store
+const agents = await AgentLoaderJSON(agentDefinition, {
+  bindings: {
+    [Bindings.Postgres]: PostgresStore({
+      url: "postgres://postgres:postgres@localhost:5432/postgres"
+    })
+  }
+});
+
+// Or with an in-memory store for testing
+const agents = await AgentLoaderJSON(agentDefinition, {
+  bindings: {
+    [Bindings.Memory]: MemoryStore()
+  }
+});
+```
+
+#### Session Life Cycle
+
+1. When an agent receives a query with a session ID, it attempts to load the existing session state
+2. The state is merged with any new session data provided in the query
+3. The agent processes the query with access to this state
+4. Before responding, the updated state is saved back to storage
+5. Private variables (with `_` prefix) are removed from the response
+
+This mechanism allows agents to maintain context across multiple interactions while keeping appropriate boundaries between agent-specific and shared data.
+
+## Installation
+
+```bash
+npm install smartagent
+```
+