arcananex-synapse/README.md

Agentic AI framework

# Arcananex Synapse

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

## Features
- **Agent Abstraction:** Define, register, and manage multiple agents with custom logic (`src/agent.ts`).
- **LLM Integration:** Connect to AWS Bedrock and other LLM providers via adapters (`src/adapters/`).
- **Command Pattern:** Encapsulate operations as commands for flexible scheduling and execution (`src/command.ts`).
- **Extensible Architecture:** Build your own agents, adapters, and workflows.
- **TypeScript-first:** Strong typing and modern developer experience.
- **Builders:** Utilities for constructing memory and message objects for LLMs (`src/builders/`).
- **AWS Bedrock Support:** Out-of-the-box Bedrock client and credential helpers (`src/clients/`, `src/utils/`).
- **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
Add the framework to your project (from your monorepo or npm if published):
```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

### Basic Usage

#### 1. Create and Configure an Agent Controller
```typescript
import { agent, command } from 'arcananex-synapse';

const config = {
  defaultMemory: [/* AI system memory */]
};
const main = new agent.Agent(config);

// Define agent command functions
const emailCommand = new command.Command('email');
const defaultCommand = new command.Command('default');

// Register agents
main.registerAgent('default', defaultCommand);
main.registerAgent('email', emailCommand);

// Register always running agents
main.registerAlwaysRunAgent('analytic', new agent.AnalyticAgent());

// Process input
await main.processInput('Send onboarding email to new users');
```

##### Task Routing
The framework uses a default agent to route tasks to the appropriate agent. Agents process tasks based on their registration and logic.

#### 2. Implement Custom Agents
Extend the `Agent` interface to add your own logic:
```typescript
import { agent } from 'arcananex-synapse';

class MyCustomAgent implements agent.Agent {
  async executeTask(task: agent.AgentTask): Promise<void> {
    // Custom logic here
  }
}
```

#### 3. Chaining Agent Tasks
Use `ChainCommand` to chain multiple tasks:
```typescript
import { command, agent } from 'arcananex-synapse';

export const agentCmd = new command.ChainCommand<agent.AgentTask, unknown>()
  .addTask(async (task: agent.AgentTask | undefined) => {
    console.log('Do task 1');
  })
  .addTask(async (taskWithParams: unknown) => {
    console.log('Do task 2');
  });
```

#### 4. Use with AWS Bedrock
The framework provides adapters and utilities for invoking LLMs via AWS Bedrock. Ensure your AWS credentials are set up in your environment. See `src/adapters/bedrock-llm-client-adapter.ts` and `src/clients/bedrock.ts` for details.

## 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` to ensure correctness. 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