aa-agent-tools 0.1.0__py3-none-any.whl

aa_agent_tools/__init__.py

@@ -0,0 +1,125 @@
+"""aa_agent_tools - a friendly toolbox of cool functions for kid-built agents.
+
+Import it and call functions directly::
+
+    import aa_agent_tools as aa
+
+    aa.search_web("cute penguins", api_key="YOUR_BRAVE_KEY")
+    aa.fetch_page("https://example.com")
+    aa.get_joke()
+    aa.ask_ai("What is recursion?", api_key="YOUR_OPENAI_KEY")
+
+Every function that needs a secret (an API key, a password, ...) takes it as
+an argument. We never store your keys.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+# ---- re-export the friendly public functions -----------------------------
+from .apis import call_api
+from .data import (
+    convert_money,
+    country_info,
+    define_word,
+    number_fact,
+    shorten_url,
+    wikipedia_summary,
+)
+from .email_tools import send_email, send_email_gmail
+from .errors import AAError, AARequestError
+from .fun import (
+    flip_coin,
+    get_advice,
+    get_cat_fact,
+    get_cat_image,
+    get_dog_image,
+    get_joke,
+    get_pokemon,
+    get_quote,
+    pick_one,
+    random_number,
+    roll_dice,
+)
+from .images import get_photo, random_image
+from .space import near_earth_objects, space_image
+from .text_tools import (
+    base64_decode,
+    base64_encode,
+    convert_units,
+    count_words,
+    hash_text,
+    is_palindrome,
+    make_qr,
+    reverse_text,
+)
+from .weather import get_forecast, get_weather
+from .web import fetch_page, search_web
+
+__all__ = [
+    # web
+    "search_web",
+    "fetch_page",
+    # email
+    "send_email",
+    "send_email_gmail",
+    # generic api + ai
+    "call_api",
+    # weather
+    "get_weather",
+    "get_forecast",
+    # space
+    "space_image",
+    "near_earth_objects",
+    # fun
+    "get_joke",
+    "get_advice",
+    "get_cat_fact",
+    "get_cat_image",
+    "get_dog_image",
+    "get_quote",
+    "roll_dice",
+    "flip_coin",
+    "random_number",
+    "pick_one",
+    "get_pokemon",
+    # data / knowledge
+    "wikipedia_summary",
+    "define_word",
+    "number_fact",
+    "country_info",
+    "convert_money",
+    "shorten_url",
+    # images
+    "get_photo",
+    "random_image",
+    # text tools
+    "hash_text",
+    "base64_encode",
+    "base64_decode",
+    "make_qr",
+    "convert_units",
+    "count_words",
+    "reverse_text",
+    "is_palindrome",
+    # errors
+    "AAError",
+    "AARequestError",
+]
+
+
+def list_functions() -> list[str]:
+    """Return the names of every function in aa_agent_tools (handy for autocomplete)."""
+    return list(__all__)
+
+
+def about() -> str:
+    """Print a friendly welcome message."""
+    return (
+        "aa_agent_tools v"
+        + __version__
+        + " - a friendly toolbox of cool functions for kid-built agents.\n"
+        "Try: aa.search_web(...), aa.fetch_page(...), aa.get_joke(), aa.ask_ai(...)\n"
+        "Need a key? Pass it as an argument - we never store your secrets."
+    )

aa_agent_tools/_http.py

@@ -0,0 +1,88 @@
+"""Internal HTTP helpers for aa_agent_tools.
+
+Everything here uses only the Python standard library so it works inside a
+Pyodide (WebAssembly) environment where third-party wheels like ``requests``
+may not be available.
+"""
+
+from __future__ import annotations
+
+import gzip
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+
+DEFAULT_TIMEOUT = 30
+DEFAULT_USER_AGENT = "aa_agent_tools/0.1 (+https://github.com/Adullam-Technologies/aa_agent_tools)"
+
+
+def build_url(base: str, params: dict | None = None) -> str:
+    """Add query-string ``params`` to ``base`` if any are given."""
+    if not params:
+        return base
+    clean = {k: v for k, v in params.items() if v is not None}
+    if not clean:
+        return base
+    sep = "&" if "?" in base else "?"
+    return base + sep + urllib.parse.urlencode(clean, doseq=True)
+
+
+def request(
+    url: str,
+    method: str = "GET",
+    *,
+    params: dict | None = None,
+    headers: dict | None = None,
+    data: bytes | None = None,
+    json_body: dict | None = None,
+    timeout: int = DEFAULT_TIMEOUT,
+) -> dict:
+    """Make an HTTP request and return parsed JSON (or text).
+
+    Raises
+    ------
+    AARequestError
+        When the server returns an HTTP error status.
+    AAError
+        For other network / parsing problems.
+    """
+    from .errors import AAError, AARequestError
+
+    full_url = build_url(url, params)
+    merged = {"User-Agent": DEFAULT_USER_AGENT}
+    if headers:
+        merged.update({k: str(v) for k, v in headers.items()})
+
+    if json_body is not None:
+        data = json.dumps(json_body).encode("utf-8")
+        merged.setdefault("Content-Type", "application/json")
+        merged.setdefault("Accept", "application/json")
+
+    req = urllib.request.Request(full_url, data=data, method=method.upper(), headers=merged)
+
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw_bytes = resp.read()
+            # Auto-decompress if the server sent gzip content
+            if resp.headers.get("Content-Encoding") == "gzip":
+                raw_bytes = gzip.decompress(raw_bytes)
+            raw = raw_bytes.decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as exc:  # status code >= 400
+        body = ""
+        try:
+            raw_bytes = exc.read()
+            if exc.headers.get("Content-Encoding") == "gzip":
+                raw_bytes = gzip.decompress(raw_bytes)
+            body = raw_bytes.decode("utf-8", errors="replace")
+        except Exception:
+            pass
+        raise AARequestError(exc.code, exc.reason, body) from exc
+    except urllib.error.URLError as exc:
+        raise AAError(f"Could not reach {full_url}: {exc.reason}") from exc
+
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        # Some endpoints return plain text; hand it back as-is.
+        return { "content": raw }

aa_agent_tools/_util.py

@@ -0,0 +1,34 @@
+"""Small shared helpers: key checking, text truncation, pretty printing."""
+
+from __future__ import annotations
+
+from .errors import AAMissingKeyError
+
+
+def require_key(value, name: str):
+    """Return ``value`` or raise :class:`AAMissingKeyError` if it is falsy."""
+    if not value:
+        raise AAMissingKeyError(name)
+    return value
+
+
+def truncate(text: str, limit: int = 600) -> str:
+    """Trim ``text`` to ``limit`` characters and add an ellipsis if needed."""
+    if text is None:
+        return ""
+    text = str(text)
+    if len(text) <= limit:
+        return text
+    return text[: limit - 1].rstrip() + "…"
+
+
+def pretty(obj) -> str:
+    """Return a human-friendly, readable string for any result."""
+    import json
+
+    if isinstance(obj, (dict, list)):
+        try:
+            return json.dumps(obj, indent=2, ensure_ascii=False)
+        except TypeError:
+            pass
+    return str(obj)

aa_agent_tools/apis.py

@@ -0,0 +1,60 @@
+"""Connect to any API with an API key (and talk to AI models).
+
+These are the "give my agent super-powers" functions. Most web APIs just need
+a GET/POST request plus a key - :func:`call_api` does that for you.
+"""
+
+from __future__ import annotations
+
+from ._http import request
+from ._util import require_key
+
+
+def call_api(
+    url: str,
+    api_key: str | None = None,
+    *,
+    method: str = "GET",
+    params: dict | None = None,
+    json_body: dict | None = None,
+    extra_headers: dict | None = None,
+    key_header: str = "Authorization",
+    key_prefix: str = "Bearer ",
+):
+    """Call almost any REST API in one line.
+
+    Parameters
+    ----------
+    url : str
+        The full API endpoint, e.g. ``"https://api.example.com/v1/things"``.
+    api_key : str | None
+        Your key. It is sent in the header ``key_header`` with ``key_prefix``.
+    method : str
+        ``"GET"``, ``"POST"``, etc.
+    params : dict | None
+        Query-string arguments (for GET requests).
+    json_body : dict | None
+        JSON body (for POST/PUT requests).
+    key_header, key_prefix : str, str
+        How to send the key. Many APIs use ``"Bearer "``; some use
+        ``key_header="x-api-key"`` with ``key_prefix=""``.
+
+    Example
+    -------
+    >>> data = aa.call_api(
+    ...     "https://api.github.com/repos/octocat/Hello-World",
+    ...     key_header="Accept",
+    ...     key_prefix="application/vnd.github+json",
+    ... )
+    >>> print(data["stargazers_count"])
+    """
+    headers = dict(extra_headers or {})
+    if api_key:
+        headers[key_header] = f"{key_prefix}{api_key}"
+    return request(
+        url,
+        method=method,
+        params=params,
+        json_body=json_body,
+        headers=headers,
+    )

aa_agent_tools/data.py

@@ -0,0 +1,163 @@
+"""Look up facts, words, and numbers from free public knowledge APIs."""
+
+from __future__ import annotations
+
+from ._http import request
+from ._util import truncate
+
+
+def _is_prime(n: int) -> bool:
+    if n < 2:
+        return False
+    if n % 2 == 0:
+        return n == 2
+    i = 3
+    while i * i <= n:
+        if n % i == 0:
+            return False
+        i += 2
+    return True
+
+
+def wikipedia_summary(title: str, *, sentences: int = 3):
+    """Get a short, friendly summary of a Wikipedia topic.
+
+    Parameters
+    ----------
+    title : str
+        The topic, e.g. ``"Black hole"`` or ``"Turtle"``.
+    sentences : int
+        About how many sentences to include.
+
+    Returns
+    -------
+    dict
+        ``title``, ``summary``, ``url`` and ``image``.
+
+    Example
+    -------
+    >>> info = aa.wikipedia_summary("Aurora")
+    >>> print(info["summary"])
+    """
+    try:
+        data = request(
+            f"https://en.wikipedia.org/api/rest_v1/page/summary/{title.replace(' ', '_')}"
+        )
+    except Exception:
+        return {"title": title, "summary": "", "url": "", "image": ""}
+    return {
+        "title": data.get("title", title),
+        "summary": data.get("extract", ""),
+        "url": (data.get("content_urls") or {}).get("desktop", {}).get("page", ""),
+        "image": (data.get("thumbnail") or {}).get("source", ""),
+    }
+
+
+def define_word(word: str):
+    """Get the dictionary definition and example sentence for a word.
+
+    Example
+    -------
+    >>> d = aa.define_word("serendipity")
+    >>> print(d["definitions"][0])
+    """
+    try:
+        data = request(f"https://api.dictionaryapi.dev/api/v2/entries/en/{word.lower()}")
+    except Exception:
+        return {"word": word, "phonetic": "", "definitions": []}
+    if isinstance(data, dict):  # error response
+        return {"word": word, "phonetic": "", "definitions": []}
+    elif isinstance(data, list):
+        defs = []
+        phonetic = ""
+        for entry in list(data):
+            phonetic = phonetic or entry.get("phonetic", "")
+            for meaning in entry.get("meanings", []):
+                for d in meaning.get("definitions", []):
+                    defs.append(
+                        f"({meaning.get('partOfSpeech', '')}) {d.get('definition', '')}"
+                        + (f" e.g. {d['example']}" if d.get("example") else "")
+                    )
+        return {"word": word, "phonetic": phonetic, "definitions": defs[:5]}
+    return {"word": word, "phonetic": "", "definitions": []}
+
+
+def number_fact(number, *, kind: str = "math"):
+    """Get a fun, fact-packed description of a number (works offline!).
+
+    The fact is computed for you, so it never needs the internet. Try
+    ``kind="math"`` for number properties, or ``kind="year"`` / ``kind="date"``
+    for a playful note.
+
+    Example
+    -------
+    >>> aa.number_fact(7)
+    '7 has 1 digit(s). Its digits add up to 7. 7 is odd. 7 is a prime number ...'
+    """
+    try:
+        n = int(number)
+    except (TypeError, ValueError):
+        return f"{number} is... a number of some kind!"
+    facts = [f"{n} has {len(str(abs(n)))} digit(s)."]
+    digit_sum = sum(int(c) for c in str(abs(n)))
+    facts.append(f"Its digits add up to {digit_sum}.")
+    facts.append(f"{n} is {'even' if n % 2 == 0 else 'odd'}.")
+    if _is_prime(abs(n)):
+        facts.append(f"{n} is a prime number - only divisible by 1 and itself!")
+    root = int(abs(n) ** 0.5)
+    if root * root == abs(n) and n >= 0:
+        facts.append(f"{n} is a perfect square ({root} × {root}).")
+    if n != 0 and 1_000_000 % n == 0:
+        facts.append(f"{n} is a factor of 1,000,000.")
+    tail = {
+        "year": f" If {n} were a year, it would be in the {'BC' if n < 0 else 'AD'} era.",
+        "date": f" The {n}th day of the year is a special one!",
+        "trivia": "",
+        "math": "",
+    }.get(kind, "")
+    return " ".join(facts) + tail
+
+
+def country_info(name: str):
+    """Get a friendly snapshot of a country using Wikipedia.
+
+    Example
+    -------
+    >>> c = aa.country_info("Japan")
+    >>> print(c["name"]); print(c["summary"][:80])
+    """
+    info = wikipedia_summary(name)
+    return {
+        "name": info.get("title") or name,
+        "summary": info.get("summary", ""),
+        "url": info.get("url", ""),
+        "image": info.get("image", ""),
+    }
+
+
+def convert_money(amount: float, from_currency: str, to_currency: str):
+    """Convert money between currencies using live rates (no key needed).
+
+    Example
+    -------
+    >>> aa.convert_money(10, "USD", "EUR")
+    """
+    from ._util import require_key
+
+    data = request("https://open.er-api.com/v6/latest/" + from_currency.upper())
+    rates = data.get("rates", {})
+    rate = rates.get(to_currency.upper())
+    if rate is None:
+        return None
+    return round(amount * float(rate), 2)
+
+
+def shorten_url(url: str):
+    """Make a long URL short using the free is.gd service."""
+    try:
+        data = request("https://is.gd/create.php", params={"format": "json", "url": url})
+        if isinstance(data, dict):
+            return data.get("shorturl", url)
+    except Exception:
+        pass
+    return url

aa_agent_tools/email_tools.py

@@ -0,0 +1,100 @@
+"""Send emails from your agent.
+
+Uses only the standard library's ``smtplib`` so it works in Pyodide. You will
+need an email account that allows "app passwords" (Gmail, Outlook, etc.).
+"""
+
+from __future__ import annotations
+
+import smtplib
+import ssl
+from email.message import EmailMessage
+
+from ._util import require_key
+
+
+def send_email(
+    to: str,
+    subject: str,
+    body: str,
+    *,
+    smtp_host: str,
+    smtp_port: int = 587,
+    username: str,
+    password: str,
+    from_addr: str | None = None,
+    use_tls: bool = True,
+):
+    """Send a plain-text email through any SMTP server.
+
+    Parameters
+    ----------
+    to : str
+        Recipient email address.
+    subject, body : str
+        Email subject and message text.
+    smtp_host, smtp_port : str, int
+        Your email provider's SMTP server (e.g. ``"smtp.gmail.com"``, port 587).
+    username, password : str
+        Login + app password (NOT your normal account password).
+    from_addr : str | None
+        Sender address (defaults to ``username``).
+
+    Example
+    -------
+    >>> aa.send_email(
+    ...     to="friend@example.com",
+    ...     subject="Hello from my agent!",
+    ...     body="My robot wrote this email.",
+    ...     smtp_host="smtp.gmail.com",
+    ...     username="you@gmail.com",
+    ...     password="app-password-here",
+    ... )
+    """
+    require_key(username, "username")
+    require_key(password, "password")
+    sender = from_addr or username
+
+    msg = EmailMessage()
+    msg["Subject"] = subject
+    msg["From"] = sender
+    msg["To"] = to
+    msg.set_content(body)
+
+    with smtplib.SMTP(smtp_host, smtp_port, timeout=30) as server:
+        if use_tls:
+            context = ssl.create_default_context()
+            server.starttls(context=context)
+        server.login(username, password)
+        server.send_message(msg)
+    return f"Email sent to {to}"
+
+
+def send_email_gmail(to: str, subject: str, body: str, *, gmail: str, app_password: str):
+    """Send an email using a Gmail account.
+
+    ``gmail`` is your full address (e.g. ``"you@gmail.com"``) and
+    ``app_password`` is a 16-character Gmail app password, not your normal
+    password. Make one at https://myaccount.google.com/apppasswords.
+
+    Example
+    -------
+    >>> aa.send_email_gmail(
+    ...     to="friend@example.com",
+    ...     subject="hi!",
+    ...     body="sent from aa_agent_tools",
+    ...     gmail="you@gmail.com",
+    ...     app_password="abcd efgh ijkl mnop",
+    ... )
+    """
+    return send_email(
+        to,
+        subject,
+        body,
+        smtp_host="smtp.gmail.com",
+        smtp_port=587,
+        username=gmail,
+        password=app_password,
+        from_addr=gmail,
+        use_tls=True,
+    )

aa_agent_tools/errors.py

@@ -0,0 +1,36 @@
+"""Friendly error types for aa_agent_tools."""
+
+from __future__ import annotations
+
+
+class AAError(Exception):
+    """Base class for every error aa_agent_tools can raise."""
+
+
+class AARequestError(AAError):
+    """Raised when a web request comes back with an HTTP error status."""
+
+    def __init__(self, status: int, reason: str, body: str = ""):
+        self.status = status
+        self.reason = reason
+        self.body = body
+        hint = ""
+        if status == 401:
+            hint = " (did you forget your API key, or is it wrong?)"
+        elif status == 403:
+            hint = " (this key is not allowed to do that)"
+        elif status == 404:
+            hint = " (nothing was found at that address)"
+        elif status == 429:
+            hint = " (you've hit a rate limit - wait a moment and try again)"
+        super().__init__(f"HTTP {status} {reason}{hint}".strip())
+
+
+class AAMissingKeyError(AAError):
+    """Raised when a required API key was not supplied."""
+
+    def __init__(self, name: str):
+        self.key_name = name
+        super().__init__(
+            f"Missing API key: {name}. Pass it as an argument, e.g. {name}='YOUR_KEY'."
+        )