refactor: standardize environment variable naming for base URL across SDKs

- Replaced `BASE_URL_ENV` with `TINYHUMANS_BASE_URL` in Python, C++, Java, and Rust SDKs to maintain consistency.
- Updated related code to ensure proper retrieval of the base URL from environment variables.
- Enhanced logging in the Python SDK for better debugging and tracking of memory client operations.

Author: senamakel

packages/plugin-agno/neocortex_agno/tools.py

@@ -12,7 +12,7 @@
 
 
 DEFAULT_BASE_URL = "https://staging-api.alphahuman.xyz"
-BASE_URL_ENV = "ALPHAHUMAN_BASE_URL"
+TINYHUMANS_BASE_URL = "ALPHAHUMAN_BASE_URL"
 
 
 class AlphahumanError(Exception):
@@ -36,7 +36,7 @@ class AlphahumanMemoryClient:
     def __init__(self, token: str, base_url: Optional[str] = None) -> None:
         if not token or not token.strip():
             raise ValueError("token is required")
-        resolved = base_url or os.getenv(BASE_URL_ENV) or DEFAULT_BASE_URL
+        resolved = base_url or os.getenv(TINYHUMANS_BASE_URL) or DEFAULT_BASE_URL
         self._base_url = resolved.rstrip("/")
         self._token = token
         self._http = httpx.Client(

packages/plugin-livekit/neocortex_livekit/tools.py

@@ -11,7 +11,7 @@
 
 
 DEFAULT_BASE_URL = "https://staging-api.alphahuman.xyz"
-BASE_URL_ENV = "ALPHAHUMAN_BASE_URL"
+TINYHUMANS_BASE_URL = "ALPHAHUMAN_BASE_URL"
 
 
 class AlphahumanError(Exception):
@@ -29,7 +29,7 @@ class AlphahumanMemoryClient:
     def __init__(self, token: str, base_url: Optional[str] = None) -> None:
         if not token or not token.strip():
             raise ValueError("token is required")
-        resolved = base_url or os.getenv(BASE_URL_ENV) or DEFAULT_BASE_URL
+        resolved = base_url or os.getenv(TINYHUMANS_BASE_URL) or DEFAULT_BASE_URL
         self._base_url = resolved.rstrip("/")
         self._token = token
         self._http = httpx.Client(

packages/sdk-cpp/src/memory_client.cpp

@@ -8,7 +8,7 @@
 namespace alphahuman {
 
 static const char* DEFAULT_BASE_URL = "https://staging-api.alphahuman.xyz";
-static const char* BASE_URL_ENV = "ALPHAHUMAN_BASE_URL";
+static const char* TINYHUMANS_BASE_URL = "ALPHAHUMAN_BASE_URL";
 
 static void global_curl_init() {
     static std::once_flag flag;
@@ -37,7 +37,7 @@ AlphahumanMemoryClient::AlphahumanMemoryClient(const std::string& token, const s
     // Resolve base URL
     std::string resolved = base_url;
     if (resolved.empty()) {
-        const char* env = std::getenv(BASE_URL_ENV);
+        const char* env = std::getenv(TINYHUMANS_BASE_URL);
         if (env && env[0] != '\0') {
             resolved = env;
         }

packages/sdk-java/src/main/java/xyz/alphahuman/sdk/AlphahumanMemoryClient.java

@@ -17,7 +17,7 @@
 public class AlphahumanMemoryClient implements AutoCloseable {
 
     private static final String DEFAULT_BASE_URL = "https://staging-api.alphahuman.xyz";
-    private static final String BASE_URL_ENV = "ALPHAHUMAN_BASE_URL";
+    private static final String TINYHUMANS_BASE_URL = "ALPHAHUMAN_BASE_URL";
 
     private final String baseUrl;
     private final String token;
@@ -35,7 +35,7 @@ public AlphahumanMemoryClient(String token, String baseUrl) {
 
         String resolved = baseUrl;
         if (resolved == null || resolved.isEmpty()) {
-            resolved = System.getenv(BASE_URL_ENV);
+            resolved = System.getenv(TINYHUMANS_BASE_URL);
         }
         if (resolved == null || resolved.isEmpty()) {
             resolved = DEFAULT_BASE_URL;

packages/sdk-python/README.md

@@ -40,17 +40,25 @@ import tinyhumansai as api
 client = api.TinyHumanMemoryClient("YOUR_APIKEY_HERE")
 
 # Store a single memory
-client.ingest_memory({
-    "key": "user-preference-theme",
-    "content": "User prefers dark mode",
-    "namespace": "preferences",
-    "metadata": {"source": "onboarding"},
-})
-
-# Ask a LLM something from the memory
+client.ingest_memory(
+    item={
+        "key": "user-preference-theme",
+        "content": "User prefers dark mode",
+        "namespace": "preferences",
+        "metadata": {"source": "onboarding"},
+    }
+)
+
+# Fetch relevant memory context, then ask a LLM something from it
+ctx = client.recall_memory(
+    namespace="preferences",
+    prompt="What is the user's preference for theme?",
+)
+
 response = client.recall_with_llm(
     prompt="What is the user's preference for theme?",
-    api_key="OPENAI_API_KEY"
+    api_key="OPENAI_API_KEY",
+    context=ctx.context,
 )
 print(response.text) # The user prefers dark mode
 ```

packages/sdk-python/example.py

@@ -18,7 +18,7 @@
 
 # Ingest (upsert) a single memory
 result = client.ingest_memory(
-    {
+    item={
         "key": "user-preference-theme",
         "content": "User prefers dark mode",
         "namespace": "preferences",
@@ -42,11 +42,11 @@
 # (Optional) Query LLM with context (use your own API key from the provider)
 # Built-in providers: "openai", "anthropic", "google"
 response = client.recall_with_llm(
-    "What is the user's preference for theme?",
-    "openai",
-    "gpt-4o-mini",
-    os.environ["OPENAI_API_KEY"],
-    ctx.context,
+    prompt="What is the user's preference for theme?",
+    provider="openai",
+    model="gpt-4o-mini",
+    api_key=os.environ["OPENAI_API_KEY"],
+    context=ctx.context,
 )
 print(response.text)
 

packages/sdk-python/tinyhumansai/__init__.py

@@ -1,5 +1,10 @@
 """TinyHumans Python SDK."""
 
+from __future__ import annotations
+
+import logging
+import os
+
 from .client import TinyHumanMemoryClient
 from .llm import SUPPORTED_LLM_PROVIDERS
 from .types import (
@@ -12,6 +17,13 @@
     ReadMemoryItem,
 )
 
+logger = logging.getLogger("tinyhumansai")
+
+_level = os.environ.get("TINYHUMANSAI_LOG_LEVEL")
+if _level:
+    # Optional, env-driven log level for easier debugging in apps and notebooks.
+    logger.setLevel(_level.upper())
+
 __all__ = [
     "TinyHumanMemoryClient",
     "TinyHumanError",
@@ -22,4 +34,5 @@
     "GetContextResponse",
     "ReadMemoryItem",
     "SUPPORTED_LLM_PROVIDERS",
+    "logger",
 ]

packages/sdk-python/tinyhumansai/client.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 import os
 import time
 from typing import Any, Optional, Sequence, Union
@@ -11,7 +12,6 @@
 from .llm import recall_with_llm as _query_llm_func
 from .types import (
     TinyHumanError,
-    BASE_URL_ENV,
     DEFAULT_BASE_URL,
     DeleteMemoryResponse,
     GetContextResponse,
@@ -22,6 +22,9 @@
 )
 
 
+logger = logging.getLogger("tinyhumansai")
+
+
 def _validate_timestamp(value: Optional[float], name: str) -> None:
     """Validate a Unix timestamp (seconds).
 
@@ -90,10 +93,17 @@ def __init__(
             raise ValueError("token is required")
         if not model_id or not model_id.strip():
             raise ValueError("model_id is required")
-        resolved_base_url = base_url or os.environ.get(BASE_URL_ENV) or DEFAULT_BASE_URL
+        resolved_base_url = (
+            base_url or os.environ.get("TINYHUMANS_BASE_URL") or DEFAULT_BASE_URL
+        )
         self._base_url = resolved_base_url.rstrip("/")
         self._token = token
         self._model_id = model_id
+        logger.debug(
+            "Initializing TinyHumanMemoryClient base_url=%s model_id=%s",
+            self._base_url,
+            self._model_id,
+        )
         self._http = httpx.Client(
             base_url=self._base_url,
             headers={
@@ -105,6 +115,7 @@ def __init__(
 
     def close(self) -> None:
         """Close the underlying HTTP client and release connections."""
+        logger.debug("Closing TinyHumanMemoryClient HTTP session")
         self._http.close()
 
     def __enter__(self) -> "TinyHumanMemoryClient":
@@ -164,6 +175,7 @@ def ingest_memories(
             raise ValueError("items must be a non-empty list")
 
         normalized: list[dict[str, Any]] = []
+        logger.debug("Normalizing %d memory item(s) for ingest", len(items))
         for item in items:
             if isinstance(item, MemoryItem):
                 _validate_timestamps(item.created_at, item.updated_at)
@@ -199,6 +211,11 @@ def ingest_memories(
                 raise TypeError("items must be MemoryItem or dict")
 
         body = {"items": normalized}
+        logger.debug(
+            "Sending ingest_memories request namespace(s)=%s count=%d",
+            {i["namespace"] for i in normalized},
+            len(normalized),
+        )
         data = self._send("POST", "/memory", body)
         return IngestMemoryResponse(
             ingested=data["ingested"],
@@ -247,6 +264,14 @@ def recall_memory(
             for k in keys:
                 params.append(("keys[]", k))
 
+        logger.debug(
+            "Recalling memory namespace=%s prompt=%s num_chunks=%d key=%s keys_count=%s",
+            namespace,
+            (prompt[:100] + "…") if len(prompt) > 100 else prompt,
+            num_chunks,
+            key,
+            len(keys) if keys else 0,
+        )
         data = self._get("/memory", params)
         items = [
             ReadMemoryItem(
@@ -305,6 +330,13 @@ def delete_memory(
         if delete_all:
             body["deleteAll"] = True
 
+        logger.debug(
+            "Deleting memory namespace=%s key=%s keys_count=%s delete_all=%s",
+            namespace,
+            key,
+            len(keys) if keys else 0,
+            delete_all,
+        )
         data = self._send("DELETE", "/memory", body)
         return DeleteMemoryResponse(deleted=data["deleted"])
 
@@ -369,6 +401,17 @@ def recall_with_llm(
                 num_chunks=num_chunks,
             )
             context = ctx.context
+        logger.debug(
+            "Calling recall_with_llm provider=%s model=%s namespace=%s "
+            "has_context=%s max_tokens=%s temperature=%s url=%s",
+            provider,
+            model,
+            namespace,
+            bool(context),
+            max_tokens,
+            temperature,
+            url,
+        )
         return _query_llm_func(
             prompt=prompt,
             provider=provider,
@@ -385,14 +428,19 @@ def recall_with_llm(
     # ------------------------------------------------------------------
 
     def _get(self, path: str, params: list[tuple[str, str]]) -> dict[str, Any]:
+        logger.debug("HTTP GET %s params=%s", path, params)
         response = self._http.get(path, params=params)
         return self._parse_response(response)
 
     def _send(self, method: str, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        logger.debug("HTTP %s %s json_keys=%s", method, path, list(body.keys()))
         response = self._http.request(method, path, json=body)
         return self._parse_response(response)
 
     def _parse_response(self, response: httpx.Response) -> dict[str, Any]:
+        logger.debug(
+            "Parsing response status=%s url=%s", response.status_code, response.url
+        )
         try:
             payload = response.json()
         except Exception: