Quickstart

Get up and running with jaato in 5 minutes. This guide covers installation, basic setup, and sending your first message with tool execution.

Requirements

  • Python 3.10 or higher
  • Credentials for at least one AI provider (see table)

Choose a Provider

Provider Use Case Setup
Anthropic Complex reasoning, code generation Setup guide
Google GenAI Long context, multimodal Setup guide
GitHub Models Multi-model access via single API Setup guide
Ollama Local models, privacy, no API costs Setup guide
Claude CLI Claude Pro/Max subscribers Setup guide
Zhipu AI GLM models, chain-of-thought reasoning Setup guide

See the Providers Reference for detailed configuration options for each provider.

Check Python version
python3 --version
# Python 3.10+

Installation

Create a virtual environment and install from TestPyPI.

Terminal
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

pip install \
  --extra-index-url https://test.pypi.org/simple/ \
  jaato-sdk jaato-server jaato-tui

Environment Setup

Create a .env file with your credentials. The provider auto-detects the endpoint based on your configuration.

.env (Anthropic)
JAATO_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-api03-...your-key
MODEL_NAME=claude-sonnet-4-20250514
.env (Google GenAI)
JAATO_PROVIDER=google_genai
GOOGLE_GENAI_API_KEY=AIza...your-key
MODEL_NAME=gemini-2.5-flash
.env (Ollama - local)
JAATO_PROVIDER=ollama
OLLAMA_MODEL=qwen3:32b

Basic Usage

Create a client, connect, and send a message. When called without arguments, connect() reads JAATO_PROVIDER and MODEL_NAME from your environment (or .env file).

Steps

  1. Import JaatoClient
  2. Create client and call connect()
  3. Use generate() for text completion
Environment Variable Resolution
connect() resolves configuration from environment variables:
  • JAATO_PROVIDER — selects the provider
  • MODEL_NAME — selects the model
  • Provider-specific vars (e.g., ANTHROPIC_API_KEY, OLLAMA_MODEL) — authentication and overrides
basic_example.py
from jaato import JaatoClient

client = JaatoClient()
client.connect()  # Reads JAATO_PROVIDER and MODEL_NAME from env

response = client.generate("What is 2 + 2?")
print(response)  # "4"

Adding Tools

jaato becomes powerful when you give the model access to tools. The PluginRegistry discovers and manages tool plugins.

Steps

  1. Create a PluginRegistry with the model name
  2. Call discover() to find available plugins
  3. Use expose_tool() to enable specific plugins
  4. Call configure_tools() on the client
  5. Use send_message() with an output callback

Output Callback

The callback receives three arguments for each output event:

  • source str
    "model" for model output, plugin name for tool output
  • text str
    The output text
  • mode str
    "write" for new block, "append" to continue
with_tools.py
from jaato import JaatoClient, PluginRegistry

client = JaatoClient()
client.connect()  # Reads JAATO_PROVIDER and MODEL_NAME from env

# Discover and expose plugins
registry = PluginRegistry(model_name=client.model_name)
registry.discover()

# Expose the CLI plugin for shell commands
registry.expose_tool("cli")

# Configure tools on the client
client.configure_tools(registry)

# Define output callback
def on_output(source, text, mode):
    prefix = f"[{source}] " if mode == "write" else ""
    print(f"{prefix}{text}", end="")

# Send message - model can now use CLI tools
response = client.send_message(
    "List Python files in the current directory",
    on_output=on_output
)

print(f"\n\nFinal: {response}")
Output
[model] I'll list the Python files for you.
[cli] cli_mcp_harness.py
test_vertex.py
...
[model] I found several Python files in the directory.

Final: I found several Python files...

Multi-turn Conversations

The client maintains conversation history internally. Each call to send_message() adds to the history, enabling multi-turn conversations with context.

History Management

  • get_history() - retrieve conversation history
  • reset_session() - clear history and start fresh
  • reset_session(history) - reset with modified history
multi_turn.py
# First message
response = client.send_message(
    "What files are in this directory?",
    on_output=on_output
)

# Follow-up (client remembers context)
response = client.send_message(
    "Which one is the largest?",
    on_output=on_output
)

# Check history
history = client.get_history()
print(f"Conversation has {len(history)} messages")

# Start fresh
client.reset_session()

Next Steps

Now that you have the basics working, explore these topics to get the most out of jaato:

Available built-in plugins
# List available plugins
registry = PluginRegistry()
registry.discover()

for name in registry.list_available():
    print(name)

# Common plugins:
# - cli: Execute shell commands
# - mcp: Model Context Protocol tools
# - file_edit: File editing
# - todo: Task management
# - web_search: Web search
# - permission: Permission control