# hello-ollama

**Repository Path**: jackie19/hello-ollama

## Basic Information

- **Project Name**: hello-ollama
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-03
- **Last Updated**: 2026-04-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LangChain.js Ollama Agent Project

A comprehensive AI agent project using LangChain.js that enables local connection to Ollama. This project provides a robust framework for building AI agents with tool integration capabilities.

## Table of Contents

- [Project Overview](#project-overview)
- [Features](#features)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Tool Integration](#tool-integration)
- [Testing](#testing)
- [Directory Structure](#directory-structure)
- [Troubleshooting](#troubleshooting)

## Project Overview

This project demonstrates how to create a powerful AI agent using LangChain.js that connects to Ollama locally. The agent can receive user queries, determine when tool usage is required, execute appropriate tools, and generate responses based on tool outputs.

## Features

- **Local Ollama Integration**: Secure connection to Ollama API running locally
- **Tool Integration System**: Support for multiple tool functions with proper input/output schemas
- **Example Tools**: Calculator and weather tools with clear documentation
- **Configuration Management**: Environment variable support with validation
- **Error Handling**: Comprehensive logging and error handling mechanisms
- **Testing Setup**: Sample prompts to verify agent functionality
- **Type Safety**: Full TypeScript support throughout the codebase

## Installation

### Prerequisites

- Node.js 16.0 or higher
- Ollama installed and running locally
- Git

### Steps

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd hello-ollama
   ```

2. **Install dependencies**
   ```bash
   npm install --legacy-peer-deps
   ```

3. **Start Ollama**
   Make sure Ollama is running locally on port 11434 (default)
   ```bash
   ollama serve
   ```

4. **Pull a model** (if not already done)
   ```bash
   ollama pull llama3
   ```

## Configuration

### Environment Variables

Create a `.env` file in the project root with the following options:

```env
# Ollama Configuration
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3
OLLAMA_TEMPERATURE=0.7
OLLAMA_MAX_TOKENS=1000

# Agent Configuration
AGENT_NAME=Ollama Agent
AGENT_DESCRIPTION=A powerful AI agent powered by Ollama

# Tools Configuration
ENABLED_TOOLS=calculator,weather

# Logging Configuration
LOG_LEVEL=info
```

### Default Configuration

If no `.env` file is provided, the project uses the following defaults:

- **Ollama**: `http://localhost:11434`, model `llama3`
- **Agent**: Name `Ollama Agent`, description `A powerful AI agent powered by Ollama`
- **Tools**: Enabled tools `calculator,weather`
- **Logging**: Level `info`

## Usage

### Running the Agent

```bash
# Run the main application
npm start

# Run with ts-node
npx ts-node src/index.ts
```

### Example Queries

The agent can handle various types of queries:

1. **Tool-using queries**:
   - "What is 42 multiplied by 7?" (uses calculator tool)
   - "What's the weather in Chicago?" (uses weather tool)

2. **Direct queries**:
   - "Tell me about LangChain.js"
   - "Write a poem about AI"

## Tool Integration

### Adding New Tools

To add a new tool to the agent:

1. **Create a new tool file** in `src/tools/`
2. **Extend the BaseTool class**
3. **Register the tool** in `src/tools/index.ts`
4. **Enable the tool** in configuration

### Example Tool Structure

```typescript
import { BaseTool } from './baseTool';
import { z } from 'zod';

class MyTool extends BaseTool {
  constructor() {
    super({
      name: 'myTool',
      description: 'Description of what the tool does',
      schema: z.object({
        // Input schema definition
      }),
    });
  }

  async _run(input: string): Promise<string> {
    const validatedInput = this.validateInput(input);
    // Tool implementation
    return 'Tool result';
  }
}

export const myTool = new MyTool();
```

## Testing

### Run Tests

```bash
# Run comprehensive tests
npx ts-node test/testAgent.ts
```

### Test Coverage

The test script verifies:
1. **Ollama connection**
2. **Tool functionality** (calculator and weather tools)
3. **Agent performance** with sample prompts

## Directory Structure

```
hello-ollama/
├── src/
│   ├── agents/           # Agent implementation
│   ├── tools/            # Tool definitions
│   ├── config/           # Configuration management
│   ├── integrations/     # Ollama integration
│   ├── utils/            # Utility functions
│   └── index.ts          # Main entry point
├── test/
│   └── testAgent.ts      # Test script
├── logs/                 # Log files
├── .env                  # Environment variables
├── package.json          # Project configuration
├── tsconfig.json         # TypeScript configuration
└── README.md             # Documentation
```

## Troubleshooting

### Common Issues

1. **Ollama connection failed**
   - Ensure Ollama is running: `ollama serve`
   - Check base URL in configuration
   - Verify network connectivity

2. **Tool execution errors**
   - Check tool input format
   - Verify tool is enabled in configuration
   - Review tool implementation for bugs

3. **Agent not using tools**
   - Check prompt format in agent configuration
   - Verify tool descriptions are clear
   - Ensure tools are properly registered

### Logs

Check log files in the `logs/` directory for detailed error information:
- `logs/error.log` - Error messages
- `logs/combined.log` - All log messages

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License.