from freeagent import Agent

agent = Agent(model="llama3.1:8b")
print(agent.run("What is Python?"))

from freeagent import Agent, tool
from freeagent.tools import system_info, calculator

@tool
def weather(city: str) -> dict:
    """Get weather for a city.
    city: The city name
    """
    return {"temp": 72, "condition": "sunny"}

agent = Agent(
    model="qwen3:8b",
    tools=[weather, system_info, calculator],
)

print(agent.run("Weather in Portland and disk space?"))

$ freeagent ask qwen3:8b "What's the capital of France?"
Paris is the capital of France.

$ freeagent chat qwen3:8b
freeagent > What is Python?
Python is a high-level programming language...
freeagent > When was it released?
Python was first released in 1991...
freeagent > /trace
Trace for run 2 (qwen3:8b, native):
  +     0ms  run_start            "When was it released?"
  ...
freeagent > /exit

$ freeagent models
Name                           Size       Modified
gemma4:e2b                     7.2GB      2026-04-06
qwen3:8b                       5.2GB      2025-12-09
llama3.1:latest                4.9GB      2025-12-12

from freeagent import Agent, TokenEvent, ToolCallEvent, ToolResultEvent

agent = Agent(model="qwen3:8b", tools=[weather])

for event in agent.run_stream("Weather in Tokyo?"):
    if isinstance(event, TokenEvent):
        print(event.text, end="", flush=True)
    elif isinstance(event, ToolCallEvent):
        print(f"\n[Calling {event.name}...]")
    elif isinstance(event, ToolResultEvent):
        print(f"[{event.name} -> {'ok' if event.success else 'fail'}]")

async for event in agent.arun_stream("Weather in Tokyo?"):
    if isinstance(event, TokenEvent):
        print(event.text, end="", flush=True)

from freeagent import Agent

agent = Agent(model="qwen3:8b", tools=[weather])
agent.run("What's the weather in Tokyo?")
agent.run("Convert that to Celsius")  # remembers Tokyo was 85°F

from freeagent import Agent, SlidingWindow, TokenWindow

# Default: SlidingWindow(max_turns=20)
agent = Agent(model="qwen3:8b")

# Token-based budget (small context models)
agent = Agent(model="qwen3:4b", conversation=TokenWindow(max_tokens=3000))

# Stateless mode (each run() independent)
agent = Agent(model="qwen3:8b", conversation=None)

# Saves to .freeagent/sessions/my-chat.json
agent = Agent(model="qwen3:8b", session="my-chat")
agent.run("Hello!")

# Later, in a new process — restores conversation
agent = Agent(model="qwen3:8b", session="my-chat")

from freeagent import Agent

# Auto-tuned: 2B model → strips skills + memory tool
agent = Agent(model="gemma4:e2b")
print(agent.model_info.parameter_size)   # 5.1B
print(agent.model_info.is_small)         # True (MoE pattern)
print(len(agent.skills))                 # 0
print(agent.config.context_window)       # 131072 (real)

# Auto-tuned: 8B model → keeps full defaults
agent = Agent(model="qwen3:8b")
print(agent.model_info.parameter_size)   # 8.2B
print(len(agent.skills))                 # 2
print(agent.config.context_window)       # 40960 (real)

# Force bundled skills on a small model
agent = Agent(model="gemma4:e2b", bundled_skills=True, memory_tool=True)

# Disable auto-tune entirely
agent = Agent(model="qwen3:8b", auto_tune=False)

from freeagent import Agent, tool

@tool
def adder(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

agent = Agent(model="qwen3:4b", tools=[adder])
agent.run("What is 47 + 23?")

print(agent.trace())

# One-line summary
print(agent.last_run.summary())
# Run 1: qwen3:4b (native) 12191ms, 2 iters, 1 tool calls

# Markdown report
print(agent.last_run.to_markdown())

# Raw trace events
for te in agent.last_run.trace_events:
    print(te.timestamp, te.event_type, te.data)

@agent.on("before_tool")
def log_tool(ctx):
    print(f"→ Calling {ctx.tool_name}({ctx.args})")

@agent.on("after_tool")
def cache_result(ctx):
    if ctx.result and ctx.result.success:
        agent.memory.set(
            f"cache.{ctx.tool_name}",
            ctx.result.data
        )

@agent.on("on_error")
def alert(ctx):
    send_to_slack(f"Agent error: {ctx.error}")

@agent.on("before_tool")
def use_cache(ctx):
    # Skip the actual tool call if we have cached data
    cached = agent.memory.get(f"cache.{ctx.tool_name}")
    if cached:
        ctx.skip = True  # tool won't execute

@agent.on("after_run")
def sanitize(ctx):
    # Override the final response
    ctx.override_response = ctx.response.replace("password", "***")

from freeagent import log_hook, cost_hook

# Logging — prints every lifecycle event
logger = log_hook(verbose=True)
agent.on("before_run", logger)
agent.on("before_tool", logger)
agent.on("after_tool", logger)
agent.on("after_run", logger)

# Cost tracking — counts tool calls per tool
track, stats = cost_hook()
agent.on("before_tool", track)
agent.run("check disk space")
print(stats())
# → {"calls": 1, "tools": {"system_info": 1}, "errors": 0}

agent = Agent(
    model="llama3.1:8b",
    tools=[weather],
    memory_path="~/.freeagent/memory.json",  # persists to disk
)

# Pre-load preferences
agent.memory.set("user.name", "Alice", source="user")
agent.memory.set("user.units", "metric", source="user")

# The model sees this in its system prompt:
# ## Your Memory (facts you remember):
# - user.name: Alice
# - user.units: metric

agent.run("What's the weather?")
# Model knows to use metric because it's in memory

from freeagent import Memory

mem = Memory(path="~/.freeagent/memory.json")

mem.set("user.name", "Alice")          # create/update
mem.get("user.name")                     # → "Alice"
mem.get("missing", "default")            # → "default"
mem.has("user.name")                     # → True
mem.delete("user.name")                  # → True

mem.search("user.")                      # → all keys starting with "user."
mem.all()                                # → full dict
mem.keys()                               # → list of keys
len(mem)                                # → entry count
"user.name" in mem                      # → True

# Each entry tracks metadata:
# created_at, updated_at, access_count, source

# Auto-cache tool results in memory
@agent.on("after_tool")
def auto_cache(ctx):
    if ctx.result and ctx.result.success:
        agent.memory.set(
            f"cache.{ctx.tool_name}.{hash(str(ctx.args))}",
            ctx.result.data,
            source="tool"
        )

# Use cache to skip redundant calls
@agent.on("before_tool")
def check_cache(ctx):
    key = f"cache.{ctx.tool_name}.{hash(str(ctx.args))}"
    if agent.memory.has(key):
        ctx.skip = True  # don't re-run

@tool
def lookup_user(username: str) -> dict:
    """Look up a user by username.
    username: The username to look up
    """
    return {"name": "Alice", "role": "engineer"}

# Auto-generated:
lookup_user.name         # → "lookup_user"
lookup_user.schema()     # → JSON schema from type hints
lookup_user.to_ollama_spec()    # → Ollama tool format
lookup_user.to_react_description()  # → human-readable for ReAct

---
name: nba-analyst
description: Basketball statistics expert
version: 1.0
tools: [search, calculator]
---

You are an NBA analyst. Always cite your sources.
When comparing players, use per-game averages.

agent = Agent(
    model="qwen3:8b",
    tools=[search, calculator],
    skills=["./my-skills"],   # directory of skill folders
)

from freeagent import Agent, VLLMProvider

provider = VLLMProvider(model="qwen3-8b")
agent = Agent(model="qwen3-8b", provider=provider, tools=[my_tool])

agent.run("What's the weather?")
print(agent.metrics)               # quick summary
print(agent.metrics.tool_stats())  # per-tool breakdown
agent.metrics.to_json("m.json")   # export