artificial-intelligence-local 0.0.2b3115__py3-none-any.whl

artificial_intelligence_local/src/contact_agent.py

@@ -0,0 +1,264 @@
+"""Ollama contacts agent.
+
+A local-first Strands agent over our contacts, built on the same pattern as the
+weather agent (see weather_agent.py): the data access lives in Python `@tool`
+functions and a local Ollama model only picks the tool, fills in its arguments,
+and phrases the answer.
+
+The tools are thin wrappers over the read-only "_strand" twins published by
+contact-local (contact_local/contact_local_strands.py, BU-3047). The `@tool`
+decorator lives here rather than in contact-main on purpose: contact-main stays
+free of any Strands dependency, and this package decides how the functions are
+exposed to a model.
+
+Two deliberate constraints shape the tools below:
+
+1. Flat, scalar arguments only. The strand twins speak `contact_dict`, but a
+   dict is a terrible thing to ask a small local model to synthesize -- it will
+   invent keys. So no tool takes a dict: where an answer needs two strand calls
+   (fetch the contact, then read a field off it), the tool composes them
+   internally and the model just passes a contact id.
+
+2. Lookup is by contact id, phone, or email -- NOT by name. ContactsLocal has no
+   name-based lookup (`get_existing_contact_dict` matches on phone/email only),
+   so the agent cannot answer "What's Tal's phone number?" and the system prompt
+   below tells it to say so instead of guessing. Name lookup needs
+   `get_contact_by_name` added to contact-main first (it also has to deal with
+   first+last names not being unique -- BU-3058).
+"""
+
+from strands import tool
+
+from ollama_agent_base import DEFAULT_OLLAMA_MODEL_ID, build_ollama_agent, run_chat_loop
+
+
+def _strand_functions():
+    """Return the contact-local strand functions, imported lazily.
+
+    Importing contact_local pulls in person_local, which logs in against the
+    local authentication server (http://localhost:3000) *at import time*.
+    Keeping that import inside the call means this module -- and its tests --
+    can be imported with no database and no auth server running; only an actual
+    lookup needs them. It is also the seam the tests mock.
+    """
+    from contact_local import contact_local_strands
+
+    return contact_local_strands
+
+
+def _lookup_failed(error: Exception) -> str:
+    """The message a tool returns when the contacts backend could not be reached.
+
+    Kept short, and deliberately free of the underlying exception text. Passing
+    the raw error back (e.g. the auth server's 500, which is a wall of JSON) led
+    a small local model to compress it into "There is no contact with id 1" --
+    turning a backend outage into a confident, wrong "that person doesn't
+    exist". The wording below tells the model what the failure is NOT.
+    """
+    return (
+        f"LOOKUP FAILED ({type(error).__name__}): the contacts database could not be reached. "
+        "This is a system error. It does NOT mean the contact does not exist -- "
+        "tell the user the contacts database is unavailable right now."
+    )
+
+
+def _format_contact(contact_dict: dict) -> str:
+    """Describe who a contact is, for the model to read."""
+    name = " ".join(
+        part for part in (contact_dict.get("first_name"), contact_dict.get("last_name")) if part
+    )
+    description = name or contact_dict.get("display_as") or "Unnamed contact"
+
+    for field in ("job_title", "organization"):
+        value = contact_dict.get(field)
+        if value:
+            description += f", {value}"
+    return description
+
+
+@tool
+def get_contact_by_id(contact_id: int) -> str:
+    """Get who a contact is (name, job title, organization) from their contact id.
+
+    Args:
+        contact_id: The numeric id of the contact, e.g. 42.
+
+    Returns:
+        A short description of the contact, or a message saying no contact has
+        that id.
+    """
+    try:
+        contact_dict = _strand_functions().get_contact_by_contact_id_strand(contact_id)
+    except Exception as error:  # noqa: BLE001 - report the failure to the model, never raise at it
+        return _lookup_failed(error)
+
+    if not contact_dict:
+        return f"There is no contact with id {contact_id}."
+    return f"Contact {contact_id}: {_format_contact(contact_dict)}."
+
+
+@tool
+def get_contact_phone_numbers(contact_id: int) -> str:
+    """Get the phone numbers of the contact with this contact id.
+
+    Args:
+        contact_id: The numeric id of the contact, e.g. 42.
+
+    Returns:
+        The contact's phone numbers, or a message saying they have none on
+        record / that no contact has that id.
+    """
+    try:
+        strands = _strand_functions()
+        contact_dict = strands.get_contact_by_contact_id_strand(contact_id)
+        if not contact_dict:
+            return f"There is no contact with id {contact_id}."
+        phone_numbers = strands.get_contact_phone_numbers_from_contact_dict_strand(contact_dict)
+    except Exception as error:  # noqa: BLE001 - report the failure to the model, never raise at it
+        return _lookup_failed(error)
+
+    if not phone_numbers:
+        return f"{_format_contact(contact_dict)} has no phone number on record."
+    return f"{_format_contact(contact_dict)}: {', '.join(phone_numbers)}"
+
+
+@tool
+def get_contact_email_addresses(contact_id: int) -> str:
+    """Get the email addresses of the contact with this contact id.
+
+    Args:
+        contact_id: The numeric id of the contact, e.g. 42.
+
+    Returns:
+        The contact's email addresses, or a message saying they have none on
+        record / that no contact has that id.
+    """
+    try:
+        strands = _strand_functions()
+        contact_dict = strands.get_contact_by_contact_id_strand(contact_id)
+        if not contact_dict:
+            return f"There is no contact with id {contact_id}."
+        email_addresses = strands.get_contact_email_addresses_from_contact_dict_strand(contact_dict)
+    except Exception as error:  # noqa: BLE001 - report the failure to the model, never raise at it
+        return _lookup_failed(error)
+
+    if not email_addresses:
+        return f"{_format_contact(contact_dict)} has no email address on record."
+    return f"{_format_contact(contact_dict)}: {', '.join(email_addresses)}"
+
+
+@tool
+def find_contact_by_phone_or_email(phone_number: str = "", email_address: str = "") -> str:
+    """Check whether we already have a contact with this phone number or email address.
+
+    Use this to answer questions like "do we already know someone with this
+    email?". Give a phone number, an email address, or both.
+
+    Args:
+        phone_number: A phone number to search for, e.g. "+972501234567".
+        email_address: An email address to search for, e.g. "tal@circ.zone".
+
+    Returns:
+        A description of the matching contact including its contact id (which
+        can then be used with the other tools), or a message saying nobody
+        matches.
+    """
+    if not phone_number and not email_address:
+        return "Give me a phone number or an email address to search for."
+
+    # The strand twin matches on the phone/email columns of a contact_dict, so we
+    # compose that dict here -- the model only ever passes flat strings.
+    search_contact_dict = {}
+    if phone_number:
+        search_contact_dict["phone1"] = phone_number
+    if email_address:
+        search_contact_dict["email1"] = email_address
+
+    try:
+        contact_dict = _strand_functions().get_existing_contact_dict_strand(search_contact_dict)
+    except Exception as error:  # noqa: BLE001 - report the failure to the model, never raise at it
+        return _lookup_failed(error)
+
+    if not contact_dict:
+        searched = " or ".join(value for value in (phone_number, email_address) if value)
+        return f"We have no contact with {searched}."
+
+    contact_id = contact_dict.get("contact_id")
+    return f"Yes -- contact {contact_id}: {_format_contact(contact_dict)}."
+
+
+# The prompt does not list the tools: Strands already sends the model each tool's name,
+# signature and docstring, so a list here would be a second copy that goes stale the
+# moment a tool is added. Describe a tool in its docstring, not here.
+#
+# The name rule below is the exception, and it is deliberate. A tool schema can only say
+# what EXISTS -- an absence is not expressible in any schema, so the model cannot infer
+# it. Measured on qwen2.5:7b with "What's Tal's phone number?": with the explicit rule,
+# 6/6 clean refusals; replacing it with a general "ask for an identifier you can look up",
+# 0/6 -- the model reaches for the tool named find_contact_by_phone_or_email, gets
+# nothing, then guesses contact_id=1 and reports a stranger's phone number as Tal's.
+#
+# TODO (when name lookup lands -- BU-3058): DELETE this rule, do not just edit it. It does
+# not merely go stale, it SUPPRESSES the new tool: measured with a working name tool
+# registered AND this rule still in the prompt, the model called no tool at all and told
+# the user it cannot look people up by name. Tests stay green while the feature silently
+# does nothing. The general prompt is fine once the gap itself is a registered tool -- a
+# find_contact_by_name whose body reports "name lookup unavailable" scored 6/6 with no
+# name rule in the prompt at all. That is the shape to move to once the tools are complete.
+CONTACT_SYSTEM_PROMPT = """You are an assistant that answers questions about our contacts database.
+
+Rules -- follow them strictly:
+- Answer ONLY from what a tool returned. Never invent a name, phone number, email
+  address or contact id, and never guess an id to "try".
+- You CANNOT look up a contact by name -- there is no tool for it. If you are asked
+  something like "What is Tal's phone number?", do not guess: say you can only look
+  someone up by contact id, phone number, or email address, and ask for one of those.
+- If a tool says there is no such contact, say exactly that. Do not retry with a
+  different id.
+- If a tool answer starts with "LOOKUP FAILED", the contacts database is broken or
+  unreachable. Say that the contacts database is unavailable right now. NEVER report
+  this as the contact not existing -- a failed lookup tells you NOTHING about whether
+  the contact exists.
+- Do not narrate your steps or say what you are "about to" do. Call the tool, then
+  give only the final answer, in one or two short sentences.
+"""
+
+
+def build_agent(model_id=DEFAULT_OLLAMA_MODEL_ID):
+    """Build the contacts Agent backed by a local Ollama model.
+
+    Kept as a factory so the interactive picker can build the agent with the
+    model the user chose at startup, while imports/tests still get a ready-made
+    agent from the configured default (see ``contact_agent`` below).
+    """
+    return build_ollama_agent(
+        model_id=model_id,
+        system_prompt=CONTACT_SYSTEM_PROMPT,
+        tools=[
+            get_contact_by_id,
+            get_contact_phone_numbers,
+            get_contact_email_addresses,
+            find_contact_by_phone_or_email,
+        ],
+    )
+
+
+# A ready-made agent on the configured default, so importing the module (and the
+# tests) get a working agent without any interactive prompt. Building the agent
+# touches neither the database nor Ollama -- see _strand_functions.
+contact_agent = build_agent()
+
+
+# Interactive loop so we can test it from the terminal. Needs the database and the
+# local authentication server (http://localhost:3000) running, since every tool
+# call goes through contact-local.
+if __name__ == "__main__":
+    run_chat_loop(
+        build_agent=build_agent,
+        title="Ollama Contact Agent",
+        examples=[
+            "Who is contact 1?",
+            "What's the phone number of contact 1?",
+            "Do we already have someone with the email tal@circ.zone?",
+        ],
+    )

artificial_intelligence_local/src/ollama_agent_base.py

@@ -0,0 +1,204 @@
+"""Shared Ollama + Strands plumbing for the local agents in this package.
+
+The weather agent and the contact agent have the same shape: a local Ollama
+model plus a few Python `@tool` functions. Everything that is not specific to
+one agent -- building the Strands Agent on an OllamaModel, listing the models
+you have pulled, picking one at startup, and the terminal chat loop -- lives
+here, so an agent module only declares its tools and its system prompt.
+"""
+
+import os
+import sys
+
+import ollama
+from dotenv import find_dotenv, load_dotenv
+from strands import Agent
+from strands.models.ollama import OllamaModel
+
+# Load OLLAMA_* settings from a local .env.local1 file if one exists
+# (see .env.local1.example). find_dotenv searches up from the current working
+# directory, so this works whichever sub-directory you launch an agent from.
+load_dotenv(find_dotenv(".env.local1", usecwd=True))
+
+# The model (the "brain"): a local Ollama model instead of a cloud provider.
+# You must have Ollama installed and the model pulled first:
+# `ollama pull <model_id>`. Running an agent interactively lets you pick a
+# different installed model at startup (see choose_model).
+DEFAULT_OLLAMA_MODEL_ID = os.getenv("OLLAMA_MODEL_ID", "qwen2.5:7b")
+DEFAULT_OLLAMA_HOST = os.getenv("OLLAMA_HOST", "http://localhost:11434")
+
+
+def build_ollama_agent(model_id, system_prompt, tools):
+    """Build a Strands Agent backed by a local Ollama model.
+
+    Args:
+        model_id: An Ollama model you have pulled, e.g. "qwen2.5:7b".
+        system_prompt: The agent's instructions.
+        tools: The `@tool`-decorated functions the agent is allowed to call.
+    """
+    model = OllamaModel(host=DEFAULT_OLLAMA_HOST, model_id=model_id)
+    return Agent(model=model, system_prompt=system_prompt, tools=tools)
+
+
+def available_ollama_models():
+    """Return the locally-pulled Ollama model ids, e.g. ``["qwen2.5:7b", ...]``.
+
+    Uses the Ollama Python client. Returns an empty list if Ollama is not
+    running or has no models pulled, so callers can fall back to the default.
+    """
+    try:
+        response = ollama.list()
+    except Exception:  # noqa: BLE001 - Ollama may be down; caller falls back to the default
+        return []
+    # ollama-python >= 0.4 returns an object with a ``.models`` list of items
+    # exposing ``.model``; older versions return a dict of {"name"/"model": ...}.
+    models = getattr(response, "models", None)
+    if models is None and isinstance(response, dict):
+        models = response.get("models", [])
+    names = []
+    for model in models or []:
+        name = getattr(model, "model", None)
+        if name is None and isinstance(model, dict):
+            name = model.get("model") or model.get("name")
+        if name:
+            names.append(name)
+    return names
+
+
+def is_ollama_running():
+    """Whether the Ollama server answers at DEFAULT_OLLAMA_HOST."""
+    try:
+        ollama.list()
+    except Exception:  # noqa: BLE001 - any failure to reach Ollama means "not running"
+        return False
+    return True
+
+
+def ollama_readiness_problem(model_id):
+    """Explain what is wrong with the Ollama setup, or return None if it is ready.
+
+    Without this the failure surfaces as a raw ConnectionError from deep inside
+    the Strands/Ollama stack, which tells the user nothing about what to fix.
+    Each of the three ways this goes wrong needs a different fix, so they get
+    different messages.
+    """
+    if not is_ollama_running():
+        return (
+            f"Cannot reach Ollama at {DEFAULT_OLLAMA_HOST}.\n"
+            "  - Start it: open the Ollama app, or run `ollama serve` in another terminal.\n"
+            "  - Not installed? https://ollama.com/download\n"
+            "  - Listening somewhere else? Set OLLAMA_HOST in your .env.local1."
+        )
+
+    models = available_ollama_models()
+    if not models:
+        return (
+            "Ollama is running but you have no models pulled.\n"
+            f"  Pull one, e.g.: ollama pull {model_id}"
+        )
+
+    if model_id not in models:
+        return (
+            f"Ollama is running but the model '{model_id}' is not pulled.\n"
+            f"  Pull it:        ollama pull {model_id}\n"
+            f"  Or pick one of: {', '.join(models)}\n"
+            "  (the default comes from OLLAMA_MODEL_ID in your .env.local1)"
+        )
+
+    return None
+
+
+def choose_model(default_model_id):
+    """Let the user pick from the locally-installed Ollama models at startup.
+
+    Falls back to ``default_model_id`` when input is non-interactive (tests /
+    CI / piped stdin), when Ollama lists no models, or when the user just
+    presses Enter.
+    """
+    models = available_ollama_models()
+    if not models or not sys.stdin.isatty():
+        return default_model_id
+
+    default_installed = default_model_id in models
+    fallback = default_model_id if default_installed else models[0]
+    if not default_installed:
+        # Don't silently redirect: tell the user their configured default
+        # isn't pulled, so the "(default)" marker below (which only marks the
+        # real configured default) isn't misleading.
+        print(
+            f"Configured default {default_model_id!r} is not installed; "
+            f"falling back to {fallback!r}."
+        )
+    print("Available Ollama models:")
+    for index, name in enumerate(models, start=1):
+        marker = "  (default)" if name == default_model_id else ""
+        print(f"  {index}. {name}{marker}")
+
+    try:
+        choice = input(f"Pick a model by number [default: {fallback}]: ").strip()
+    except (KeyboardInterrupt, EOFError):
+        return fallback
+    if not choice:
+        return fallback
+    if choice.isdigit() and 1 <= int(choice) <= len(models):
+        return models[int(choice) - 1]
+    print(f"'{choice}' is not a valid choice; using {fallback}.")
+    return fallback
+
+
+def run_chat_loop(build_agent, title, examples, default_model_id=DEFAULT_OLLAMA_MODEL_ID):
+    """Run an agent as an interactive terminal chat, so we can test it by hand.
+
+    Checks Ollama is usable before starting, so a missing server or an unpulled
+    model is reported as something the user can act on rather than as a stack
+    trace on their first question.
+
+    Args:
+        build_agent: Callable taking a model id and returning the Agent to chat
+            with. Called after the user has picked the model at startup.
+        title: Shown at the top, e.g. "Ollama Contact Agent".
+        examples: Example questions printed as a hint.
+        default_model_id: The pre-selected model in the startup picker.
+    """
+    if not is_ollama_running():
+        print(f"\n{ollama_readiness_problem(default_model_id)}\n")
+        return
+
+    # Picked first: the user may choose a model other than the (possibly
+    # unpulled) default, and it is the chosen one that has to be usable.
+    selected_model_id = choose_model(default_model_id)
+
+    problem = ollama_readiness_problem(selected_model_id)
+    if problem:
+        print(f"\n{problem}\n")
+        return
+
+    agent = build_agent(selected_model_id)
+
+    print(f"\n{title} (local {selected_model_id})\n")
+    print("Ask, for example:")
+    for example in examples:
+        print(f"  {example}")
+    print("Type 'exit' to quit.\n")
+
+    while True:
+        try:
+            user_input = input("> ").strip()
+            if not user_input:
+                continue
+            if user_input.lower() == "exit":
+                print("\nGoodbye!")
+                break
+            # The agent streams its answer to stdout itself, so we don't reprint it.
+            agent(user_input)
+            print()
+        except (KeyboardInterrupt, EOFError):
+            print("\nExiting...")
+            break
+        except Exception as error:  # noqa: BLE001 - surface any error to the user
+            # Ollama can also go away mid-chat (laptop slept, app quit). Say so,
+            # instead of blaming the question the user just asked.
+            if not is_ollama_running():
+                print(f"\n{ollama_readiness_problem(selected_model_id)}\n")
+                break
+            print(f"\nError: {error}\nPlease try a different request.")

artificial_intelligence_local/src/weather_agent.py

@@ -0,0 +1,112 @@
+"""Ollama weather agent.
+
+A local-first Strands weather agent that follows the tool-based pattern from the
+Strands samples repo (python/07-ux-demos/triage-agent weather server): the
+National Weather Service two-step (points -> forecast) lives inside a Python
+`get_forecast` tool, and a local Ollama model just decides the coordinates and
+phrases the result.
+
+Running the NWS calls in code -- instead of handing the model the generic
+`http_request` tool and asking it to build URLs and parse JSON itself -- makes
+small local models far more reliable: they only pick coordinates, call one tool,
+and summarize the answer.
+
+The Ollama plumbing (model picker, agent construction, chat loop) is shared with
+the other agents in this package -- see ollama_agent_base.
+"""
+
+import requests
+from strands import tool
+
+from ollama_agent_base import DEFAULT_OLLAMA_MODEL_ID, build_ollama_agent, run_chat_loop
+
+# Free US National Weather Service API. It requires a descriptive User-Agent;
+# requests without one can be rejected.
+NWS_API_BASE = "https://api.weather.gov"
+NWS_HEADERS = {
+    "User-Agent": "circlez-ai-local-weather-agent (contact: dev@circ.zone)",
+    "Accept": "application/geo+json",
+}
+
+
+@tool
+def get_forecast(latitude: float, longitude: float) -> str:
+    """Get the current weather forecast for a US location.
+
+    Args:
+        latitude: Latitude in decimal degrees (e.g. 47.6062 for Seattle).
+        longitude: Longitude in decimal degrees (e.g. -122.3321 for Seattle).
+
+    Returns:
+        A short human-readable forecast for the upcoming period, or a message
+        explaining that no forecast is available (e.g. the coordinates are
+        outside the US, which the NWS does not cover).
+    """
+    try:
+        points = requests.get(
+            f"{NWS_API_BASE}/points/{latitude},{longitude}",
+            headers=NWS_HEADERS,
+            timeout=10,
+        )
+        if points.status_code != 200:
+            return (
+                f"No weather data for {latitude},{longitude} -- the National "
+                "Weather Service only covers locations in the United States."
+            )
+        forecast_url = points.json()["properties"]["forecast"]
+
+        forecast = requests.get(forecast_url, headers=NWS_HEADERS, timeout=10)
+        forecast.raise_for_status()
+        period = forecast.json()["properties"]["periods"][0]
+    except (requests.RequestException, KeyError, IndexError) as error:
+        return f"Could not retrieve the forecast: {error}"
+
+    return (
+        f"{period['name']}: {period['temperature']}°{period['temperatureUnit']}, "
+        f"{period['shortForecast']} "
+        f"(wind {period['windSpeed']} {period['windDirection']})."
+    )
+
+
+WEATHER_SYSTEM_PROMPT = """You are a weather assistant for locations in the United States.
+
+You have one tool: get_forecast(latitude, longitude). To answer a weather question:
+1. Work out the latitude and longitude of the location from your own knowledge.
+2. Call get_forecast with those coordinates.
+3. Reply in ONE or TWO short sentences that state the temperature and the conditions.
+
+Rules -- follow them strictly:
+- Do NOT narrate your steps or say what you are "about to" do. Call the tool, then
+  give only the final answer.
+- If get_forecast says there is no data or that it could not retrieve the forecast,
+  tell the user you could not get weather for that location. Never invent a forecast.
+- If the location is not a real US place, say you cannot find it instead of guessing.
+"""
+
+
+def build_agent(model_id=DEFAULT_OLLAMA_MODEL_ID):
+    """Build the weather Agent backed by a local Ollama model.
+
+    Kept as a factory so the interactive picker can build the agent with the
+    model the user chose at startup, while imports/tests still get a ready-made
+    agent from the configured default (see ``weather_agent`` below).
+    """
+    return build_ollama_agent(
+        model_id=model_id,
+        system_prompt=WEATHER_SYSTEM_PROMPT,
+        tools=[get_forecast],
+    )
+
+
+# A ready-made agent on the configured default, so importing the module (and the
+# tests) get a working agent without any interactive prompt.
+weather_agent = build_agent()
+
+
+# Interactive loop so we can test it from the terminal.
+if __name__ == "__main__":
+    run_chat_loop(
+        build_agent=build_agent,
+        title="Ollama Weather Agent",
+        examples=["What's the weather like in Seattle?"],
+    )

artificial_intelligence_local/tests/artificial_intelligence_local_test.py

@@ -0,0 +1,10 @@
+"""Placeholder test for the artificial-intelligence-local package.
+
+The template example tests were removed in the BU-3046 cleanup. Real tests
+(e.g. the weather agent and the contacts agent) are added in later PRs.
+This keeps the test suite green so the build/GHA has at least one test to collect.
+"""
+
+
+def test_placeholder():
+    assert True

artificial_intelligence_local/tests/contact_agent_test.py

@@ -0,0 +1,275 @@
+"""Tests for the Ollama contacts agent.
+
+Every tool reaches the database through the contact-local "_strand" twins, and
+importing those logs in against the local authentication server. So the tests
+mock at that boundary -- `contact_agent._strand_functions` -- which keeps them
+fast and deterministic and means they need no database, no auth server and no
+LLM. The live test at the bottom is skipped by default; it exercises the full
+Ollama -> tool -> answer path and needs the infrastructure actually running.
+"""
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+import contact_agent
+
+# A contact as the contact view returns it: phone1..3 / email1..3 columns.
+TAL_CONTACT_DICT = {
+    "contact_id": 1,
+    "first_name": "Tal",
+    "last_name": "Cohen",
+    "job_title": "Developer",
+    "organization": "Circlez",
+    "phone1": "+972501234567",
+    "phone2": "",
+    "phone3": None,
+    "email1": "tal@circ.zone",
+    "email2": None,
+    "email3": None,
+}
+
+
+def _fake_strands(**overrides):
+    """A stand-in for contact_local.contact_local_strands.
+
+    Defaults behave like the real twins over TAL_CONTACT_DICT; pass an override
+    to make one of them return something else or raise.
+    """
+    strand_functions = SimpleNamespace(
+        get_contact_by_contact_id_strand=MagicMock(return_value=TAL_CONTACT_DICT),
+        get_existing_contact_dict_strand=MagicMock(return_value=TAL_CONTACT_DICT),
+        get_contact_phone_numbers_from_contact_dict_strand=MagicMock(
+            return_value=["+972501234567"]
+        ),
+        get_contact_email_addresses_from_contact_dict_strand=MagicMock(
+            return_value=["tal@circ.zone"]
+        ),
+    )
+    for name, value in overrides.items():
+        setattr(strand_functions, name, value)
+    return strand_functions
+
+
+def _patch_strands(**overrides):
+    return patch.object(contact_agent, "_strand_functions", return_value=_fake_strands(**overrides))
+
+
+def _registered_tools():
+    """Every tool the agent is actually built with.
+
+    Read from the registry rather than listed by hand, so a tool added later is
+    covered by the checks below without anyone remembering to add it here.
+    """
+    return list(contact_agent.contact_agent.tool_registry.registry.values())
+
+
+def test_contact_agent_is_built():
+    """The module exposes a constructed agent, its tools, and a system prompt."""
+    assert contact_agent.contact_agent is not None
+    assert isinstance(contact_agent.CONTACT_SYSTEM_PROMPT, str)
+    assert contact_agent.CONTACT_SYSTEM_PROMPT.strip() != ""
+
+    # A subset check, not equality. A tool going *missing* from build_agent() is a real
+    # bug that nothing else catches -- every tool function is also tested directly, so
+    # they stay green while the agent quietly loses the ability to call one. A tool being
+    # *added* is a deliberate act, and failing on that would be friction with no payoff.
+    tool_names = {tool.tool_name for tool in _registered_tools()}
+    assert {
+        "get_contact_by_id",
+        "get_contact_phone_numbers",
+        "get_contact_email_addresses",
+        "find_contact_by_phone_or_email",
+    } <= tool_names
+
+
+def test_importing_the_module_does_not_touch_the_database():
+    """contact_local is imported lazily, inside the tools.
+
+    Importing it logs in against the auth server, so if it happened at module
+    import the agent could not even be imported without the infrastructure --
+    and neither could these tests.
+    """
+    assert "contact_local" not in contact_agent.__dict__
+
+
+def test_tools_take_only_flat_scalar_arguments():
+    """No tool may take a dict -- checked across every tool the agent is built with.
+
+    The strand twins speak `contact_dict`, but a small local model cannot be
+    trusted to synthesize one -- it invents keys. Tools compose the dict-shaped
+    calls internally instead, so every exposed argument stays a scalar.
+
+    This reads the registry rather than a hand-written list on purpose. A new tool
+    wrapping a new ContactsLocal method is exactly where the dict would creep back
+    in, and a hardcoded list would go on passing while silently covering none of it.
+    """
+    scalar_types = {"string", "integer", "number", "boolean"}
+    tools = _registered_tools()
+    assert tools, "no tools registered -- this test would otherwise pass vacuously"
+
+    for tool in tools:
+        properties = tool.tool_spec["inputSchema"]["json"]["properties"]
+        for argument_name, schema in properties.items():
+            assert schema.get("type") in scalar_types, (
+                f"{tool.tool_name}({argument_name}) is {schema.get('type')}, not a scalar"
+            )
+
+
+def test_get_contact_by_id_describes_the_contact():
+    with _patch_strands():
+        answer = contact_agent.get_contact_by_id(1)
+
+    assert "Tal Cohen" in answer
+    assert "Circlez" in answer
+
+
+def test_get_contact_by_id_unknown_contact_is_reported():
+    """Negative case: an id nobody has must be reported, not invented."""
+    with _patch_strands(get_contact_by_contact_id_strand=MagicMock(return_value={})):
+        answer = contact_agent.get_contact_by_id(999)
+
+    assert "no contact with id 999" in answer
+
+
+def test_get_contact_phone_numbers_composes_the_two_strand_calls():
+    """The tool fetches the contact, then reads the phones off it."""
+    strand_functions = _fake_strands()
+    with patch.object(contact_agent, "_strand_functions", return_value=strand_functions):
+        answer = contact_agent.get_contact_phone_numbers(1)
+
+    assert "+972501234567" in answer
+    strand_functions.get_contact_by_contact_id_strand.assert_called_once_with(1)
+    strand_functions.get_contact_phone_numbers_from_contact_dict_strand.assert_called_once_with(
+        TAL_CONTACT_DICT
+    )
+
+
+def test_get_contact_phone_numbers_when_there_are_none():
+    with _patch_strands(
+        get_contact_phone_numbers_from_contact_dict_strand=MagicMock(return_value=[])
+    ):
+        answer = contact_agent.get_contact_phone_numbers(1)
+
+    assert "no phone number" in answer
+
+
+def test_get_contact_phone_numbers_unknown_contact_never_reads_fields():
+    """If no contact has that id, don't go on to read phones off an empty dict."""
+    strand_functions = _fake_strands(get_contact_by_contact_id_strand=MagicMock(return_value={}))
+    with patch.object(contact_agent, "_strand_functions", return_value=strand_functions):
+        answer = contact_agent.get_contact_phone_numbers(999)
+
+    assert "no contact with id 999" in answer
+    strand_functions.get_contact_phone_numbers_from_contact_dict_strand.assert_not_called()
+
+
+def test_get_contact_email_addresses_returns_them():
+    with _patch_strands():
+        answer = contact_agent.get_contact_email_addresses(1)
+
+    assert "tal@circ.zone" in answer
+
+
+def test_find_contact_by_email_reports_the_contact_id():
+    """The id is what lets the model chain into the other tools, so it must be there."""
+    strand_functions = _fake_strands()
+    with patch.object(contact_agent, "_strand_functions", return_value=strand_functions):
+        answer = contact_agent.find_contact_by_phone_or_email(email_address="tal@circ.zone")
+
+    assert "contact 1" in answer
+    assert "Tal Cohen" in answer
+    # The model passed a flat string; the tool built the contact_dict itself.
+    strand_functions.get_existing_contact_dict_strand.assert_called_once_with(
+        {"email1": "tal@circ.zone"}
+    )
+
+
+def test_find_contact_by_phone_builds_the_phone_column():
+    strand_functions = _fake_strands()
+    with patch.object(contact_agent, "_strand_functions", return_value=strand_functions):
+        contact_agent.find_contact_by_phone_or_email(phone_number="+972501234567")
+
+    strand_functions.get_existing_contact_dict_strand.assert_called_once_with(
+        {"phone1": "+972501234567"}
+    )
+
+
+def test_find_contact_no_match_is_reported():
+    with _patch_strands(get_existing_contact_dict_strand=MagicMock(return_value={})):
+        answer = contact_agent.find_contact_by_phone_or_email(email_address="nobody@circ.zone")
+
+    assert "no contact" in answer.lower()
+
+
+def test_find_contact_with_no_arguments_asks_for_one():
+    """Guard against the model calling the search tool with nothing to search on."""
+    with _patch_strands():
+        answer = contact_agent.find_contact_by_phone_or_email()
+
+    assert "phone number or an email address" in answer
+
+
+def test_database_failure_is_returned_as_a_message_not_raised():
+    """A DB/auth failure must come back as text the model can relay.
+
+    If it raised, the exception would surface as an agent crash mid-chat instead
+    of the agent telling the user it could not look the contact up.
+    """
+    with _patch_strands(
+        get_contact_by_contact_id_strand=MagicMock(side_effect=ConnectionError("auth server down"))
+    ):
+        answer = contact_agent.get_contact_by_id(1)
+
+    assert "LOOKUP FAILED" in answer
+    assert "could not be reached" in answer
+
+
+def test_database_failure_is_never_phrased_as_a_missing_contact():
+    """Regression: a backend outage must not read as "that contact doesn't exist".
+
+    We used to hand the model the raw exception. When the auth server 500s, that
+    is a wall of JSON, and qwen2.5:7b compressed it into "There is no contact
+    with the id 1" -- reporting a DB outage as a confident, wrong answer about a
+    person. The failure text must not look like a not-found, and must not carry
+    the raw error for the model to (mis)interpret.
+    """
+    auth_500 = Exception('{"message":"Server error ... Cannot read properties of undefined"}')
+
+    failures = []
+    for tool, arguments in (
+        (contact_agent.get_contact_by_id, (1,)),
+        (contact_agent.get_contact_phone_numbers, (1,)),
+        (contact_agent.get_contact_email_addresses, (1,)),
+    ):
+        with _patch_strands(get_contact_by_contact_id_strand=MagicMock(side_effect=auth_500)):
+            failures.append(tool(*arguments))
+    with _patch_strands(get_existing_contact_dict_strand=MagicMock(side_effect=auth_500)):
+        failures.append(contact_agent.find_contact_by_phone_or_email(email_address="a@b.com"))
+
+    for answer in failures:
+        assert "LOOKUP FAILED" in answer
+        # Must not read as "no such contact"...
+        assert "no contact" not in answer.lower()
+        assert "does NOT mean the contact does not exist" in answer
+        # ...and must not leak the raw error the model would try to summarize.
+        assert "Cannot read properties" not in answer
+
+
+@pytest.mark.skip(
+    reason="live test: needs Ollama running, the database, and the auth server on :3000"
+)
+def test_contact_agent_answers_live():
+    """End-to-end: ask for a contact and expect the real phone number back.
+
+    The LLM is non-deterministic, so assert the answer carries the fact from the
+    database rather than checking exact wording. Set CONTACT_ID / EXPECTED_PHONE
+    to a contact that exists in your local database before un-skipping.
+    """
+    contact_id = 1
+    expected_phone = "+972501234567"
+
+    answer = str(contact_agent.contact_agent(f"What's the phone number of contact {contact_id}?"))
+
+    assert expected_phone in answer

artificial_intelligence_local/tests/ollama_agent_base_test.py

@@ -0,0 +1,124 @@
+"""Tests for the Ollama plumbing shared by the agents in this package.
+
+These cover the model picker and the model listing -- the parts every agent
+reuses. They mock the Ollama client, so no Ollama server is needed.
+"""
+
+from unittest.mock import MagicMock, patch
+
+import ollama_agent_base
+
+
+def test_available_ollama_models_parses_client_response():
+    """Model ids are extracted from the ollama client's `.models[].model`."""
+    item = MagicMock()
+    item.model = "qwen2.5:7b"
+    response = MagicMock(models=[item])
+
+    with patch("ollama_agent_base.ollama.list", return_value=response):
+        assert ollama_agent_base.available_ollama_models() == ["qwen2.5:7b"]
+
+
+def test_available_ollama_models_empty_when_ollama_down():
+    """If the ollama client raises (server down), we return [] to fall back."""
+    with patch("ollama_agent_base.ollama.list", side_effect=ConnectionError):
+        assert ollama_agent_base.available_ollama_models() == []
+
+
+def test_choose_model_non_interactive_uses_default_without_prompting():
+    """In tests / CI (stdin not a tty) the configured default is used, no input()."""
+    with patch("ollama_agent_base.available_ollama_models", return_value=["a", "b"]), \
+            patch("ollama_agent_base.sys.stdin.isatty", return_value=False), \
+            patch("ollama_agent_base.input", side_effect=AssertionError("must not prompt")):
+        assert ollama_agent_base.choose_model("b") == "b"
+
+
+def test_choose_model_picks_by_number():
+    """A valid number selects the matching model from the listed order."""
+    with patch("ollama_agent_base.available_ollama_models", return_value=["a", "b", "c"]), \
+            patch("ollama_agent_base.sys.stdin.isatty", return_value=True), \
+            patch("ollama_agent_base.input", return_value="3"):
+        assert ollama_agent_base.choose_model("a") == "c"
+
+
+def test_choose_model_invalid_choice_falls_back_to_default():
+    """Empty / out-of-range / garbage input falls back to the default model."""
+    with patch("ollama_agent_base.available_ollama_models", return_value=["a", "b"]), \
+            patch("ollama_agent_base.sys.stdin.isatty", return_value=True), \
+            patch("ollama_agent_base.input", return_value="99"):
+        assert ollama_agent_base.choose_model("a") == "a"
+
+
+def test_choose_model_default_not_installed_notes_and_uses_first(capsys):
+    """If the configured default isn't installed, note it and fall back to the
+    first listed model (pressing Enter selects that fallback)."""
+    with patch("ollama_agent_base.available_ollama_models", return_value=["a", "b"]), \
+            patch("ollama_agent_base.sys.stdin.isatty", return_value=True), \
+            patch("ollama_agent_base.input", return_value=""):
+        assert ollama_agent_base.choose_model("not-installed") == "a"
+
+    out = capsys.readouterr().out
+    assert "not-installed" in out and "not installed" in out
+
+
+def test_ollama_down_is_reported_with_how_to_start_it():
+    """The commonest failure: Ollama isn't running. Say so, and how to fix it."""
+    with patch("ollama_agent_base.ollama.list", side_effect=ConnectionError):
+        problem = ollama_agent_base.ollama_readiness_problem("qwen2.5:7b")
+
+    assert "Cannot reach Ollama" in problem
+    assert "ollama serve" in problem
+    assert "OLLAMA_HOST" in problem
+
+
+def test_no_models_pulled_is_reported_with_the_pull_command():
+    with patch("ollama_agent_base.is_ollama_running", return_value=True), \
+            patch("ollama_agent_base.available_ollama_models", return_value=[]):
+        problem = ollama_agent_base.ollama_readiness_problem("qwen2.5:7b")
+
+    assert "no models pulled" in problem
+    assert "ollama pull qwen2.5:7b" in problem
+
+
+def test_unpulled_model_is_reported_and_lists_what_you_do_have():
+    """Configured a model you never pulled: name it, and show the alternatives."""
+    with patch("ollama_agent_base.is_ollama_running", return_value=True), \
+            patch("ollama_agent_base.available_ollama_models", return_value=["llama3.2:3b"]):
+        problem = ollama_agent_base.ollama_readiness_problem("qwen2.5:7b")
+
+    assert "'qwen2.5:7b' is not pulled" in problem
+    assert "ollama pull qwen2.5:7b" in problem
+    assert "llama3.2:3b" in problem
+
+
+def test_no_problem_when_ollama_is_ready():
+    with patch("ollama_agent_base.is_ollama_running", return_value=True), \
+            patch("ollama_agent_base.available_ollama_models", return_value=["qwen2.5:7b"]):
+        assert ollama_agent_base.ollama_readiness_problem("qwen2.5:7b") is None
+
+
+def test_chat_loop_refuses_to_start_when_ollama_is_down(capsys):
+    """It must not build an agent or prompt for input if Ollama is unreachable."""
+    build_agent = MagicMock(side_effect=AssertionError("must not build an agent"))
+
+    with patch("ollama_agent_base.is_ollama_running", return_value=False), \
+            patch("ollama_agent_base.input", side_effect=AssertionError("must not prompt")):
+        ollama_agent_base.run_chat_loop(build_agent, title="Test Agent", examples=[])
+
+    assert "Cannot reach Ollama" in capsys.readouterr().out
+    build_agent.assert_not_called()
+
+
+def test_build_ollama_agent_wires_prompt_and_tools():
+    """The agent is built on the given system prompt and tool set."""
+    tool_function = MagicMock(tool_name="a_tool")
+
+    with patch("ollama_agent_base.OllamaModel") as ollama_model, \
+            patch("ollama_agent_base.Agent") as agent:
+        ollama_agent_base.build_ollama_agent(
+            model_id="qwen2.5:7b", system_prompt="be helpful", tools=[tool_function]
+        )
+
+    assert ollama_model.call_args.kwargs["model_id"] == "qwen2.5:7b"
+    assert agent.call_args.kwargs["system_prompt"] == "be helpful"
+    assert agent.call_args.kwargs["tools"] == [tool_function]

artificial_intelligence_local/tests/weather_agent_test.py

@@ -0,0 +1,83 @@
+"""Tests for the Ollama weather agent.
+
+The NWS calls live in the `get_forecast` tool, so the important behavior can be
+tested fast and deterministically by mocking `requests` — no network or LLM
+needed. The live test at the bottom is skipped by default; it exercises the full
+Ollama -> tool -> answer path and needs Ollama running plus internet.
+
+The model picker and the agent construction now live in ollama_agent_base and
+are tested in ollama_agent_base_test.py.
+"""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+import weather_agent
+
+
+def test_weather_agent_is_built():
+    """The module exposes a constructed agent, its tool, and a system prompt."""
+    assert weather_agent.weather_agent is not None
+    assert weather_agent.get_forecast is not None
+    assert isinstance(weather_agent.WEATHER_SYSTEM_PROMPT, str)
+    assert weather_agent.WEATHER_SYSTEM_PROMPT.strip() != ""
+
+
+def _mock_response(status_code, payload):
+    response = MagicMock(status_code=status_code)
+    response.json.return_value = payload
+    return response
+
+
+def test_get_forecast_formats_period():
+    """A valid location returns a one-line forecast with temperature + conditions."""
+    points = _mock_response(200, {
+        "properties": {"forecast": "https://api.weather.gov/gridpoints/SEW/124,67/forecast"},
+    })
+    forecast = _mock_response(200, {
+        "properties": {"periods": [{
+            "name": "Tonight",
+            "temperature": 53,
+            "temperatureUnit": "F",
+            "shortForecast": "Mostly Cloudy",
+            "windSpeed": "8 mph",
+            "windDirection": "SSW",
+        }]},
+    })
+
+    # get_forecast makes two GETs: points, then the forecast URL.
+    with patch("weather_agent.requests.get", side_effect=[points, forecast]):
+        answer = weather_agent.get_forecast(47.6062, -122.3321)
+
+    assert "53°F" in answer
+    assert "Mostly Cloudy" in answer
+
+
+def test_get_forecast_outside_us_is_refused():
+    """Negative case: a non-US / unknown location is refused, not invented.
+
+    The NWS only covers the US and returns a non-200 for anything else, so the
+    tool must say it has no data — and must NOT fabricate a temperature.
+    """
+    with patch("weather_agent.requests.get", return_value=_mock_response(404, {})):
+        answer = weather_agent.get_forecast(0, 0)
+
+    assert "United States" in answer
+    assert "°F" not in answer
+
+
+@pytest.mark.skip(reason="live test: needs Ollama running + internet to api.weather.gov")
+def test_weather_agent_answers_live():
+    """End-to-end: ask for a US city and expect a weather-shaped answer.
+
+    The LLM is non-deterministic, so we assert the answer is non-empty AND
+    mentions a weather concept rather than checking exact wording.
+    """
+    weather_terms = ("°f", "temperature", "forecast", "cloudy", "rain", "sunny", "wind")
+    answer = str(weather_agent.weather_agent("What's the weather like in Seattle?")).strip().lower()
+
+    assert answer != ""
+    assert any(term in answer for term in weather_terms), (
+        f"answer did not look weather-related: {answer!r}"
+    )

artificial_intelligence_local-0.0.2b3115.dist-info/METADATA

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: artificial-intelligence-local
+Version: 0.0.2b3115
+Summary: PyPI artificial-intelligence-local Python Package owned by Circlez.ai
+Home-page: https://github.com/circles-zone/artificial-intelligence-local-python-package
+Author: Circles
+Author-email: info@circlez.ai
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Description-Content-Type: text/markdown
+Requires-Dist: python-sdk-remote
+Requires-Dist: logger-local>=0.0.189
+Requires-Dist: strands-agents
+Requires-Dist: ollama
+Requires-Dist: python-dotenv
+Requires-Dist: requests
+Requires-Dist: contact-local>=0.0.72b3047
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: summary
+
+PyPI artificial-intelligence-local Python Package owned by Circlez.ai
+JIRA Work Item: https://circles-zone.atlassian.net/browse/BU-3046
+GHA: https://github.com/circles-zone/artificial-intelligence-local-python-package/actions

artificial_intelligence_local-0.0.2b3115.dist-info/RECORD

@@ -0,0 +1,14 @@
+artificial_intelligence_local/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+artificial_intelligence_local/src/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+artificial_intelligence_local/src/contact_agent.py,sha256=Ahb7Gm4qZHLEGy8h8oQ3YQrmZGD-ISgJzUsi_CieFH4,11641
+artificial_intelligence_local/src/ollama_agent_base.py,sha256=6CvMhQODg_evwIukOrM5gHK9IdzWAAy4o776F__MEZk,8134
+artificial_intelligence_local/src/weather_agent.py,sha256=Obv3pPSwhvmhSEI-uuoa18rxwPmYZ8kI5Zjnk7Q6kIA,4383
+artificial_intelligence_local/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+artificial_intelligence_local/tests/artificial_intelligence_local_test.py,sha256=howtqD2rHlK9Zg08JnyPmZgXz-d4o83Aikti8kQIlL4,344
+artificial_intelligence_local/tests/contact_agent_test.py,sha256=DbeeANWnAYvy1iD77Z6miUU6XgVnyERHLDhlMFMIJzg,11132
+artificial_intelligence_local/tests/ollama_agent_base_test.py,sha256=46JRjFmgCFNEEcPbmW4qS1cP_kad8Pr5ov5eP4ujI_Y,5744
+artificial_intelligence_local/tests/weather_agent_test.py,sha256=EJ5agBiHNLOBWQsyjENqeAufhrytQI9t0IyU6vkBMVM,3088
+artificial_intelligence_local-0.0.2b3115.dist-info/METADATA,sha256=D1nu3hFywtt2GubeBO-0wttwgF5sDx5UUFroKJusZAE,1042
+artificial_intelligence_local-0.0.2b3115.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+artificial_intelligence_local-0.0.2b3115.dist-info/top_level.txt,sha256=QAJP8cTE3SKcbE58zw4EH_qDgZqVNktdTyEemkzGXoI,30
+artificial_intelligence_local-0.0.2b3115.dist-info/RECORD,,

artificial_intelligence_local-0.0.2b3115.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

artificial_intelligence_local-0.0.2b3115.dist-info/top_level.txt

@@ -0,0 +1 @@
+artificial_intelligence_local