arcananex-synapse/README.md

Agentic AI framework

# Arcananex Synapse

Arcananex Synapse is a TypeScript library for building agentic AI systems and orchestrators. It provides abstractions for agent management, LLM (Large Language Model) integration, command execution, and AWS Bedrock connectivity, enabling rapid development of advanced AI-driven applications.

## Features

- **Agent Routing:** Route user input to the correct agent using LLM-based task routing.
- **Agent Abstraction:** Define, register, and manage agents with custom logic (agent.ts).
- **Command Pattern:** Encapsulate operations as commands for flexible scheduling and execution (command.ts).
- **Always-Run Agents:** Register agents that execute on every input, in parallel.
- **LLM Integration:** Connect to AWS Bedrock and other LLM providers via adapters (adapters).
- **Builders:** Utilities for constructing memory and message objects for LLMs (builders).
- **TypeScript-first:** Strong typing and modern developer experience.
- **Test Coverage:** Comprehensive tests for core modules (`src/*.test.ts`).

## Getting Started

### Prerequisites

- Node.js (v18+ recommended)
- TypeScript (4.x or later)
- AWS credentials (for Bedrock integration, if used)

### Installation

```sh
npm install <path-to-arcananex-synapse>
# or if published
npm install arcananex-synapse
```

### Configuration

Set environment variables in a `.env` file to configure the AI model and inference parameters:

```sh
AI_MODEL=amazon.nova-lite-v1:0
INFERENCE_CONFIG={"maxTokens":5000,"topP":0.9,"topK":20,"temperature":0.7}
```

- `AI_MODEL`: The model identifier (e.g., for Bedrock or other LLMs)
- `INFERENCE_CONFIG`: JSON string with inference parameters

## Usage

### 1. Routing User Input to Agents

The framework uses an LLM prompt to route user input to the correct agent. The routing prompt is only used for this step.

```typescript
import { agent, command } from 'arcananex-synapse';

const config = {
  defaultMemory: [/* business logic memory for default agent */]
};
const main = new agent.Agent(llmInvoker, config); // llmInvoker: your LLM client instance

// Define agent command functions
const emailCommand = new command.Command('email');
emailCommand.setTask(async (task) => {
  // Your email logic here
  return { message: { content: `Email sent: ${task.command}` } };
});

main.registerAgent('email', emailCommand);

// Register always running agents
const analyticCommand = new command.Command('analytic');
analyticCommand.setTask(async (task) => {
  // Analytics logic here
  return { message: { content: 'Analytics processed.' } };
});
main.registerAlwaysRunAgent('analytic', analyticCommand);

// Process input (routing will occur automatically)
const result = await main.processInput([
  { role: 'user', content: 'Send onboarding email to new users' }
]);
console.log(result);
```

### 2. Custom Agent Logic

You can implement custom agent logic by extending the `Command` or using your own handler:

```typescript
const customCommand = new command.Command('custom');
customCommand.setTask(async (task) => {
  // Custom logic here
  return { message: { content: `Handled by custom agent: ${task.command}` } };
});
main.registerAgent('custom', customCommand);
```

### 3. Chaining Agent Tasks

Chain multiple tasks using `ChainCommand`:

```typescript
const chain = new command.ChainCommand<agent.AgentTask, unknown>()
  .addTask(async (task) => {
    // Task 1
    return { step: 1 };
  })
  .addTask(async (task) => {
    // Task 2
    return { step: 2 };
  });
main.registerAgent('chain', chain);
```

### 4. Always-Run Agents

Always-run agents execute in parallel with the routed agent:

```typescript
const loggerCommand = new command.Command('logger');
loggerCommand.setTask(async (task) => {
  // Log every input
  console.log('Logging:', task.originalInput);
  return { message: { content: 'Logged.' } };
});
main.registerAlwaysRunAgent('logger', loggerCommand);
```

### 5. Use with AWS Bedrock

Adapters and utilities for AWS Bedrock are provided. Set up your AWS credentials and use the provided Bedrock client and adapters:

```typescript
import { bedrock } from 'arcananex-synapse/clients/bedrock';
const llmInvoker = new bedrock.BedrockLLMInvoker(/* config */);
const main = new agent.Agent(llmInvoker, config);
```

## Advanced Topics

- **Command Pattern:** Encapsulate operations as commands for scheduling and concurrency control.
- **Adapters:** Integrate with other LLM providers by implementing adapter interfaces.
- **Builders:** Use provided builders for constructing memory and message objects for LLMs.
- **Testing:** Run tests with `npm test`. Test files are in `src/*.test.ts`.
- **Extending:** Add new agents, commands, or adapters by following the patterns in src.

## Project Structure

```
esbuild.config.ts
jest.config.ts
LICENSE
package.json
README.md
tsconfig.json
src/
  agent.ts
  command.ts
  index.ts
  llm-invoker.ts
  adapters/
    bedrock-llm-client-adapter.ts
    llm-response-adapter.ts
  builders/
    agent-builder.ts
    memory-builder.ts
    message-builder.ts
  clients/
    bedrock.ts
    chatgpt.ts
  utils/
    aws-credential.ts
    bedrock-response.ts
  *.test.ts
```

## Development & Contribution

1. Clone the monorepo and install dependencies:
   ```sh
   git clone <your-repo-url>
   cd arcananex-synapse
   npm install
   ```
2. Build the framework:
   ```sh
   npm run build
   ```
3. Run tests:
   ```sh
   npm test
   ```

Pull requests and issues are welcome! Please open an issue to discuss your ideas or report bugs.

## License

MIT