artificial-intelligence-local 0.0.2b3115__tar.gz

artificial_intelligence_local-0.0.2b3115/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,150 @@
+# General
+
+Unlike the README.md in the root directory, this is a README.md of this specific repo/package<br>
+
+TODO Please update this README.md of this specific repo/package and not the README.md in the root directory based on the python-package-template repo<br>
+
+## TODOs
+
+### Implement using AWS Strands Agents SDK wrapper classes<br>
+
+All the classes below should get an optional parameter of OurAgentSdkEnum, which at this point has only one value: AWS_STRANDS_AGENTS_SDK<br>
+
+TODO Create OurLlmModel class, which at this point inherits "stands.models.litellm" LiteLLMModel. Has model_id data member<br>
+TODO Create OurLlmModelWithSystemPrompt class which inherits OurLlmModel and has system_prompt data member<br>
+TODO Create OurLlmPrompt class, which prompt str data member<br>
+TODO Create OurLlmComplete method<br>
+TODO Create OurLlmResponse class with which the same data memresponse str data member<br>
+TODO Create OurLlmConversation class which includes Context<br>
+
+TODO Create OurLlmAgent class with inheritance at this point stands Agent<br>
+TODO Create OurLlmSession class, which at this point inherits strands.session.s3_session_manager S3SessionManager (it can recieve optional OurStorage parameter i.e. S3) uses our storage-local-python-package repo<br>
+TODO Create OurLlmMemory (knowledgebase) Class which uses SmartVectordb class from our smart-datastore-python-package repo<br>
+TODO Create OurLlmGuardrails class that imports strands.models BedrockModel and uses BedrockModel( guardrail_id and guardrail_version and guardrail_trace )<br>
+TODO Create OurLlmMcpClient, which at this point inherits strands.tools.mcp MCPClient<br>
+
+TODO Natural 2 KQL
+TODO Natural 2 SQL
+
+TODO Convert https://github.com/gilinachum/agents/blob/main/strands-beginner.ipynb to use OurLlmModel, OurLlmPrompt (prompt-local-python-package), OurLlmResponse, OurLlmConversation, OurLlmAgent, OurLlmSession, OurLlmMemory, OurLlmGuardrails in this repo<br>
+TODO Implement https://github.com/microsoft/langchain-for-beginners in prompt-local-python-package using inheritance to allow also other implementations.<br>
+
+TODO Develop OurLlmRouter based on OpenRouter, AWS Bedrock
+
+TODO Wrapper around OpenRouter to gain API for Any AI Model
+
+### Implement using OpenAI's Agent SDK
+
+You can start by working with an OpenAI-compatible model running locally with LMStudio running locally<br>
+
+### Implement using Google's Agent Development Kit (ADK)
+
+### Implement using LangChain Agents
+
+) using machine learning model, Smart Vector Store (smart_vectorstore.py)<br>
+
+# Running the local weather agent
+
+An example agent lives at `artificial_intelligence_local/src/weather_agent.py`. It runs a local
+LLM via [Ollama](https://ollama.com) and answers US weather questions from the National Weather
+Service API.
+
+Following the tool-based pattern in the [Strands samples](https://github.com/strands-agents/samples)
+repo, the National Weather Service two-step call (`points` → `forecast`) lives inside a Python
+`get_forecast(latitude, longitude)` tool. The model's only job is to pick the location's
+coordinates, call the tool, and phrase the one-line answer — which is far more reliable on small
+local models than asking the model to build API URLs and parse JSON itself.
+
+## Prerequisites
+
+1. Install Ollama: https://ollama.com/download — then start it (the Ollama app, or `ollama serve`).
+2. Pull a model that supports tool-calling, e.g.: `ollama pull qwen2.5:7b`
+3. Copy `.env.local1.example` to `.env.local1` and set `OLLAMA_HOST` / `OLLAMA_MODEL_ID` for your machine.
+
+## Run
+
+Run these from the package directory. Note the repo nests a same-named folder, so from the
+cloned repository root you first need to `cd` one level in:
+
+```bash
+# From the repository root:
+cd artificial-intelligence-local-python-package   # the inner package dir (skip if already there)
+
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+python artificial_intelligence_local/src/weather_agent.py
+```
+
+On startup the agent lists the Ollama models you have installed and lets you pick one by number
+(press Enter to accept the default). Then ask, e.g., `What's the weather like in Seattle?` (type
+`exit` to quit).
+
+The pre-selected default comes from `.env.local1` (`OLLAMA_MODEL_ID`). `qwen2.5:7b` is the default
+and handles the coordinate-lookup + tool-call reliably; smaller models like `llama3.2:3b` also work
+but are more likely to guess coordinates poorly. In non-interactive runs (tests / CI) the default is
+used without prompting.
+
+# Running the local contact agent 
+
+`artificial_intelligence_local/src/contact_agent.py` is the same pattern applied to our contacts
+database. Its tools wrap the read-only `_strand` twins published by
+[contact-local](https://pypi.org/project/contact-local/) (`contact_local/contact_local_strands.py`),
+so a local Ollama model can answer questions about contacts.
+
+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 its functions are exposed to a model. The tools
+take only flat scalar arguments — the strand twins speak `contact_dict`, but a small local model
+cannot be trusted to synthesize a dict (it invents keys), so where an answer needs two strand calls
+the tool composes them internally.
+
+## What it can and cannot answer
+
+Lookup is by **contact id, phone number, or email address**:
+
+- `Who is contact 1?`
+- `What's the phone number of contact 1?`
+- `Do we already have someone with the email tal@circ.zone?`
+
+It **cannot look up a contact by name** — `ContactsLocal` has no name-based lookup
+(`get_existing_contact_dict` matches on phone/email only). Asked "What's Tal's phone number?", the
+agent says it can only look someone up by id / phone / email rather than guessing an id. Adding name
+lookup needs `get_contact_by_name` in contact-main first, which also has to handle first+last names
+not being unique (BU-3058).
+
+## Prerequisites
+
+The Ollama prerequisites above, plus — because every tool call goes through contact-local to the
+database — the local backend:
+
+1. A local MySQL with the contact schema.
+2. The local authentication server on `http://localhost:3000`: from
+   `authentication-local-restapi-typescript-serverless-com`, run `npx serverless offline --stage local`.
+   (Note `serverless.ts` calls a bare `dotenv.config()`, which only reads a file named exactly `.env`,
+   so the `RDS_*` / `JWT_*` variables have to be exported in your shell or copied into `.env`.)
+
+Importing `contact_local` performs an auth login *at import time*, which is why `contact_agent.py`
+imports it lazily inside the tools — the module and its tests import fine without any of this
+running, and only an actual lookup needs it.
+
+## Run
+
+```bash
+# From the inner package directory, as above:
+python artificial_intelligence_local/src/contact_agent.py
+```
+
+Then ask, e.g., `What's the phone number of contact 1?` (type `exit` to quit).
+
+# Versions
+
+[pub] 0.0.1 Initial version (change the directories, files, setup.py, .github/workflows/*.yml)<br>
+
+# Installing instructions
+
+It's advised to use venv<br>
+If you have Windows, it's also advised to use Windows Subsystem for Linux<br>
+
+## Install dependencies
+
+Run ./download-beta-sdk.sh from the bash terminal<br>
+Run pip install -r requirements.txt from the bash terminal<br>

artificial_intelligence_local-0.0.2b3115/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-0.0.2b3115/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.")