# indus-agents

[![PyPI version](https://badge.fury.io/py/indusagi.svg)](https://pypi.org/project/indusagi/)
[![Python versions](https://img.shields.io/pypi/pyversions/indusagi.svg)](https://pypi.org/project/indusagi/)
[![License](https://img.shields.io/pypi/l/indusagi.svg)](https://github.com/varunisrani/indus-agents/blob/main/LICENSE)

A modern, extensible framework for building LLM-powered agents with tools, memory, and multi-agent orchestration. Built with Python and a clean, modular architecture.

## Features

- Clean architecture with clear separation of concerns
- Type safety via Pydantic models
- Tool calling loop with built-in dev tools
- Multi-provider support: OpenAI, Anthropic, Groq, Ollama
- Multi-agent orchestration (Agency + Orchestrator)
- Conversation memory and tool usage logging
- Rich CLI and optional TUI

## Quick Start

### Installation

#### Using uv (recommended)

```bash
pip install uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install indusagi
```

#### Using pip

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install indusagi
```

#### Development install

```bash
git clone https://github.com/varunisrani/indus-agents.git
cd indus-agents
uv pip install -e ".[dev]"
```

### Basic usage

```python
from indusagi import Agent, AgentConfig

agent = Agent(
    name="Helper",
    role="Helpful assistant",
    config=AgentConfig(model="gpt-5-mini", temperature=0.7),
)

response = agent.process("What is 2 + 2?")
print(response)
```

### Using tools

```python
from typing import ClassVar
from indusagi import Agent, AgentConfig
from indusagi.tools import BaseTool, registry


class AddTool(BaseTool):
    name: ClassVar[str] = "add"
    description: ClassVar[str] = "Add two numbers"
    a: int
    b: int

    def execute(self) -> str:
        return str(self.a + self.b)


registry.register(AddTool)

agent = Agent(
    name="Calculator",
    role="Math helper",
    config=AgentConfig(model="gpt-5-mini"),
)

response = agent.process_with_tools(
    "Add 12 and 30",
    tools=registry.schemas,
    tool_executor=registry,
)
print(response)
```

### Configuration

Copy `.env.example` to `.env` and fill in your keys. Example:

```env
OPENAI_API_KEY=your-openai-api-key-here
ANTHROPIC_API_KEY=your-anthropic-api-key-here
GROQ_API_KEY=your-groq-api-key-here
OLLAMA_API_KEY=your-ollama-api-key-here

LLM_PROVIDER=groq
GROQ_MODEL=moonshotai/kimi-k2-instruct-0905
OLLAMA_MODEL=glm-4.7

DEFAULT_MODEL=gpt-5-mini
DEFAULT_TEMPERATURE=1
MAX_TOKENS=6000
```

## CLI Commands

```bash
indusagi run "Tell me a joke"
indusagi interactive
indusagi list-tools
indusagi test-connection
indusagi list-agents
indusagi create-agent --output ./agents
indusagi tui
indusagi agency-demo
indusagi version
```

## Project Structure

```text
indus-agents/
  src/indusagi/
    agent.py
    agency.py
    orchestrator.py
    memory.py
    tools.py
    tools/
    providers/
    presets/
    templates/
    tui/
    utils/
    cli.py
  example_agents/
    example_agency*.py
    example_agency_improved_*_prompts/
  example-html-website-create-by-agents/
    <static html demos>
  useful-resource/
    Agency-Code/
    Mini-Agent/
    claude-agent-sdk/
  .env.example
  agents.md
  pyproject.toml
  README.md
  CHANGELOG.md
  CONTRIBUTING.md
  LICENSE
```

## Examples and Demos

- `example_agents/` contains the demo scripts and prompt folders used by the agency examples.
- `example-html-website-create-by-agents/` contains static HTML/CSS/JS demo sites generated by agents.

## Archived or Reference Projects

- `useful-resource/` contains archived or reference subprojects (not part of the core package).

## Development

```bash
uv pip install -e ".[dev]"
pre-commit install
ruff check src
ruff format src
python -m build
```

## Contributing

Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Support

- Issues: https://github.com/varunisrani/indus-agents/issues
- Discussions: https://github.com/varunisrani/indus-agents/discussions
- Email: team@indusagi.ai

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE).

## Acknowledgments

- Built with Typer for the CLI
- Styled with Rich for terminal output
- Validated with Pydantic models

## Citation

```bibtex
@software{indusagi,
  title = {indus-agents},
  author = {IndusAGI Team},
  year = {2025},
  url = {https://github.com/varunisrani/indus-agents}
}
```
