smart-artificial-intelligence-local 0.0.1__tar.gz

smart_artificial_intelligence_local-0.0.1/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: smart-artificial-intelligence-local
+Version: 0.0.1
+Summary: PyPI smart-artificial-intelligence-local Python Package owned by Circlez.ai
+Home-page: https://github.com/circles-zone/smart-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
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: summary
+
+PyPI smart-artificial-intelligence-local Python Package owned by Circlez.ai
+GHA: https://github.com/circles-zone/smart-artificial-intelligence-local-python-package/actions

smart_artificial_intelligence_local-0.0.1/README.md

@@ -0,0 +1,26 @@
+# smart-artificial-intelligence-local-python-package
+
+Unlike the README.md in the root directory, this is the README.md of this specific repo/package.<br>
+
+## General
+
+Smart LLM orchestration layer: run the same prompt against multiple LLM engines and either
+return all the answers (MULTIPLE_ANSWERS mode) or let a designated judge engine pick the best
+one (JUDGE mode).
+
+LLM engines are injected as plain Python callables `(prompt: str) -> str`.
+This keeps this package decoupled from the actual LLM gateway
+(llm-local-python-package, e.g. LM Studio / Ollama / OpenRouter / AWS Bedrock),
+which will be integrated in a separate work item once it exists.
+
+## Usage
+
+```python
+from smart_artificial_intelligence_local.src.smart_artificial_intelligence_local import (
+    SmartArtificialIntelligenceLocal,
+)
+from smart_artificial_intelligence_local.src.llm_mode_enum import LlmMode
+
+smart_ai = SmartArtificialIntelligenceLocal()
+
+engines = {"engine_a": engine_a_callable, "engine_b": en

smart_artificial_intelligence_local-0.0.1/pyproject.toml

@@ -0,0 +1,29 @@
+# This file should be in the future instead of setup.py
+# https://python-poetry.org/docs/pyproject
+# https://stackoverflow.com/questions/78048223/adding-folder-with-data-with-pyproject-toml
+# https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#license
+
+# This file is mandatory for the `poetry version patch`
+
+# It seems we need to copy this file also to serverless-com repo, as required by dialog-workflow-python-package
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+
+[tool.poetry]
+name = "smart-artificial-intelligence-local"
+# I believe we are still using the version from setup.py and not from here until Potery will work
+version = "0.0.1" # https://pypi.org/project/smart-artificial-intelligence-local
+description = "smart-artificial-intelligence-local Python Package"
+readme = "README.md"
+authors = [
+    "Circlez.ai <info@circlez.ai>",
+]
+
+[tool.poetry.dev-dependencies]
+pytest = "^8.0"
+pytest-cov = "^5.0"

smart_artificial_intelligence_local-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

smart_artificial_intelligence_local-0.0.1/setup.py

@@ -0,0 +1,39 @@
+import setuptools
+
+# Package Name is identical to the inner directory name (with dashes).
+# TODO Add the Jira Work Item (Jira Issue) number as beta suffix when
+#  available, i.e. version='0.0.1b2432' (no Jira access at the moment).
+PACKAGE_NAME = "smart-artificial-intelligence-local"
+
+package_dir = PACKAGE_NAME.replace("-", "_")
+
+PACKAGE_DESCRIPTION = f"PyPI {PACKAGE_NAME} Python Package owned by Circlez.ai"
+
+setuptools.setup(
+    name=PACKAGE_NAME,
+    # Increase this number every time you make a change you want to publish.
+    # After 0.0.9 switch to 0.0.10 and not 0.1.0.
+    version='0.0.1',
+    author="Circles",
+    author_email="info@circlez.ai",
+    description=PACKAGE_DESCRIPTION,
+    long_description=(
+        f"{PACKAGE_DESCRIPTION}\n"
+        f"GHA: https://github.com/circles-zone/{PACKAGE_NAME}"
+        "-python-package/actions"
+    ),
+    long_description_content_type='text/markdown',
+    url=f"https://github.com/circles-zone/{PACKAGE_NAME}-python-package",
+    packages=setuptools.find_packages(),
+    package_data={package_dir: ['*.py']},
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Operating System :: OS Independent",
+    ],
+    # Production/runtime dependencies only (test packages belong in
+    #  requirements-dev.txt).
+    install_requires=[
+        'python-sdk-remote',
+        'logger-local',
+    ]
+)

smart_artificial_intelligence_local-0.0.1/smart_artificial_intelligence_local/src/constants_src_smart_artificial_intelligence_local.py

@@ -0,0 +1,21 @@
+"""Constants of Smart Artificial Intelligence Local."""
+
+
+class ConstantsSrcSmartArtificialIntelligenceLocal:
+    """All the constants of Smart Artificial Intelligence Local."""
+
+    # TODO Replace the placeholder component ids with real ones from Slack
+    SMART_AI_CODE_COMPONENT_ID: int = 0
+    SMART_AI_COMPONENT_NAME = (
+        "Smart Artificial Intelligence Local Python package"
+    )
+    SMART_AI_DEVELOPER_EMAIL_ADDRESS: str = "lielchochabi@gmail.com"
+
+    SMART_AI_CODE_LOGGER_OBJECT: dict = {
+        'component_id': SMART_AI_CODE_COMPONENT_ID,
+        'component_name': SMART_AI_COMPONENT_NAME,
+        'component_category': 'Code',
+        'developer_email_address': SMART_AI_DEVELOPER_EMAIL_ADDRESS,
+    }
+
+    DEFAULT_MAX_RESPONSE_TIME_SECONDS: float = 60.0

smart_artificial_intelligence_local-0.0.1/smart_artificial_intelligence_local/src/llm_mode_enum.py

@@ -0,0 +1,11 @@
+import enum
+
+
+class LlmMode(enum.Enum):
+    """Smart LLM modes (from the challenge diagram).
+
+    Mode 1: LLM as a Judge - a designated judge engine picks the best answer.
+    Mode 2: return multiple answers (and get reaction).
+    """
+    JUDGE = 1
+    MULTIPLE_ANSWERS = 2

smart_artificial_intelligence_local-0.0.1/smart_artificial_intelligence_local/src/smart_artificial_intelligence_local.py

@@ -0,0 +1,205 @@
+"""Smart LLM orchestration (Smart LLM box in the challenge diagram).
+
+Can call multiple LLM engines with the same prompt and either:
+- Mode 1 (JUDGE): a designated judge engine picks the best answer.
+- Mode 2 (MULTIPLE_ANSWERS): return all the answers (and get reaction).
+
+Engines are injected as plain callables ``(prompt: str) -> str`` so this
+package stays decoupled from the actual LLM gateway
+(llm-local-python-package), which is a separate work item.
+"""
+import random
+import re
+import time
+from concurrent.futures import ThreadPoolExecutor
+from concurrent.futures import TimeoutError as FutureTimeoutError
+from typing import Callable, Dict, Optional
+
+from python_sdk_remote.our_object import OurObject
+
+from .constants_src_smart_artificial_intelligence_local import (
+    ConstantsSrcSmartArtificialIntelligenceLocal as Constants,
+)
+from .llm_mode_enum import LlmMode
+from .smart_llm_logger import create_smart_llm_logger
+from .smart_llm_result import SmartLlmResult
+
+ENTITY_NAME = "Smart Artificial Intelligence Local"
+
+EngineCallable = Callable[[str], str]
+
+logger = create_smart_llm_logger()
+
+JUDGE_PROMPT_TEMPLATE = (
+    "You are a judge. Below is a prompt and several candidate answers,"
+    " each produced by a different LLM engine.\n"
+    "Prompt:\n{prompt}\n\n"
+    "Candidate answers:\n{candidates}\n"
+    "Reply with the name of the engine that produced the best answer."
+    " Reply with the engine name only."
+)
+
+JUDGE_CANDIDATE_TEMPLATE = "Engine name: {engine_name}\nAnswer: {answer}\n"
+
+
+class SmartArtificialIntelligenceLocal(OurObject):
+    """Smart LLM: run one prompt against multiple injected LLM engines."""
+
+    def __init__(self, entity_name: str = ENTITY_NAME, **kwargs) -> None:
+        super().__init__(entity_name, **kwargs)
+        self.entity_name = entity_name
+
+    def get_name(self) -> str:
+        return self.entity_name
+
+    def ask(self, *, prompt: str, engines: Dict[str, EngineCallable],
+            llm_mode: LlmMode = LlmMode.MULTIPLE_ANSWERS,
+            judge_engine: Optional[EngineCallable] = None,
+            force_engine_name: Optional[str] = None,
+            max_response_time_seconds: Optional[float] = None
+            ) -> SmartLlmResult:
+        """Run the prompt against the engines according to llm_mode.
+
+        prompt: the prompt to send to every engine.
+        engines: engine name -> callable(prompt) -> answer.
+        llm_mode: JUDGE or MULTIPLE_ANSWERS.
+        judge_engine: callable used as the judge (mandatory in JUDGE mode).
+        force_engine_name: if set, only this engine is called
+            ("Force LLM Engine" in the challenge diagram).
+        max_response_time_seconds: wall-clock cap per ask() fan-out; engines
+            that exceed it are reported in result.errors.
+        """
+        logger.start("ask", object={
+            'llm_mode': str(llm_mode),
+            'engine_names': list(engines or {}),
+            'force_engine_name': force_engine_name,
+        })
+        self._validate_ask_arguments(
+            prompt=prompt, engines=engines, llm_mode=llm_mode,
+            judge_engine=judge_engine, force_engine_name=force_engine_name)
+        selected_engines = self._select_engines(
+            engines=engines, force_engine_name=force_engine_name)
+        answers, errors = self._collect_answers(
+            prompt=prompt, engines=selected_engines,
+            max_response_time_seconds=max_response_time_seconds)
+        if not answers:
+            logger.error("ask: all engines failed", object={'errors': errors})
+            raise ValueError(
+                f"All engines failed for prompt. errors={errors}")
+        result = SmartLlmResult(
+            prompt=prompt, llm_mode=llm_mode, answers=answers, errors=errors)
+        if llm_mode == LlmMode.JUDGE:
+            self._judge(result=result, judge_engine=judge_engine)
+        logger.end("ask", object={
+            'winner_engine_name': result.winner_engine_name,
+            'answered_engine_names': list(result.answers),
+            'error_engine_names': list(result.errors),
+        })
+        return result
+
+    @staticmethod
+    def _validate_ask_arguments(
+            *, prompt: str, engines: Dict[str, EngineCallable],
+            llm_mode: LlmMode, judge_engine: Optional[EngineCallable],
+            force_engine_name: Optional[str]) -> None:
+        if not prompt:
+            raise ValueError("prompt must be a non-empty string")
+        if not engines:
+            raise ValueError("engines must be a non-empty dict")
+        if llm_mode == LlmMode.JUDGE and judge_engine is None:
+            raise ValueError("judge_engine is mandatory in JUDGE llm_mode")
+        if force_engine_name is not None and force_engine_name not in engines:
+            raise ValueError(
+                f"force_engine_name '{force_engine_name}' is not one of the"
+                f" engines {list(engines)}")
+
+    @staticmethod
+    def _select_engines(
+            *, engines: Dict[str, EngineCallable],
+            force_engine_name: Optional[str]) -> Dict[str, EngineCallable]:
+        if force_engine_name is None:
+            return engines
+        return {force_engine_name: engines[force_engine_name]}
+
+    @staticmethod
+    def _collect_answers(
+            *, prompt: str, engines: Dict[str, EngineCallable],
+            max_response_time_seconds: Optional[float]) -> tuple:
+        """Fan the prompt out to all engines concurrently.
+
+        Returns (answers, errors) dicts keyed by engine name. An engine that
+        raises or exceeds max_response_time_seconds lands in errors, so one
+        bad engine never fails the whole run.
+        """
+        if max_response_time_seconds is None:
+            max_response_time_seconds = (
+                Constants.DEFAULT_MAX_RESPONSE_TIME_SECONDS)
+        answers: Dict[str, str] = {}
+        errors: Dict[str, str] = {}
+        # Manual shutdown below; a context manager would wait for
+        # timed-out engines.
+        executor = ThreadPoolExecutor(max_workers=len(engines))
+        futures = {
+            engine_name: executor.submit(engine, prompt)
+            for engine_name, engine in engines.items()
+        }
+        # Shared deadline for the whole fan-out
+        deadline = time.monotonic() + max_response_time_seconds
+        for engine_name, future in futures.items():
+            remaining_seconds = max(0.0, deadline - time.monotonic())
+            try:
+                answers[engine_name] = future.result(
+                    timeout=remaining_seconds)
+            except FutureTimeoutError:
+                errors[engine_name] = (
+                    f"engine '{engine_name}' timed out after"
+                    f" {max_response_time_seconds} seconds")
+            except Exception as exception:  # noqa: BLE001
+                errors[engine_name] = (
+                    f"engine '{engine_name}' failed: {exception}")
+        # Do not wait for timed-out engines
+        executor.shutdown(wait=False, cancel_futures=True)
+        return answers, errors
+
+    def _judge(self, *, result: SmartLlmResult,
+               judge_engine: EngineCallable) -> None:
+        """Ask the judge engine to pick the best answer (LLM as a Judge)."""
+        judge_prompt = self._build_judge_prompt(
+            prompt=result.prompt, answers=result.answers)
+        result.judge_raw_answer = judge_engine(judge_prompt)
+        result.winner_engine_name = self._parse_judge_verdict(
+            judge_raw_answer=result.judge_raw_answer,
+            engine_names=list(result.answers))
+        result.winner_answer = result.answers[result.winner_engine_name]
+
+    @staticmethod
+    def _build_judge_prompt(*, prompt: str, answers: Dict[str, str]) -> str:
+        # Randomize candidate order to reduce judge position bias
+        candidate_items = list(answers.items())
+        random.shuffle(candidate_items)
+        candidates = "\n".join(
+            JUDGE_CANDIDATE_TEMPLATE.format(
+                engine_name=engine_name, answer=answer)
+            for engine_name, answer in candidate_items
+        )
+        return JUDGE_PROMPT_TEMPLATE.format(
+            prompt=prompt, candidates=candidates)
+
+    @staticmethod
+    def _parse_judge_verdict(*, judge_raw_answer: str,
+                             engine_names: list) -> str:
+        """Extract the winning engine name from the judge's verdict text."""
+        verdict = (judge_raw_answer or "").strip()
+        if verdict in engine_names:
+            return verdict
+        mentioned_engine_names = [
+            engine_name for engine_name in engine_names
+            if re.search(
+                rf"(?<!\w){re.escape(engine_name)}(?!\w)", verdict)
+        ]
+        if len(mentioned_engine_names) == 1:
+            return mentioned_engine_names[0]
+        raise ValueError(
+            "Could not parse the judge verdict into exactly one engine"
+            f" name. verdict='{verdict}' engines={engine_names}"
+            f" mentioned={mentioned_engine_names}")

smart_artificial_intelligence_local-0.0.1/smart_artificial_intelligence_local/src/smart_llm_logger.py

@@ -0,0 +1,44 @@
+"""Logger for this package.
+
+Primary path is the circles-zone logger-local package (per company
+conventions). If it cannot be initialized (e.g. missing environment /
+credentials in a developer machine), we fall back to the standard library
+logging so the package stays importable and testable everywhere.
+"""
+import logging
+
+from .constants_src_smart_artificial_intelligence_local import (
+    ConstantsSrcSmartArtificialIntelligenceLocal as Constants,
+)
+
+
+class _FallbackLogger:
+    """Minimal start/end/info/error/exception adapter over stdlib logging."""
+
+    def __init__(self) -> None:
+        self._logger = logging.getLogger(Constants.SMART_AI_COMPONENT_NAME)
+
+    def start(self, message: str = "", **kwargs) -> None:
+        self._logger.debug("START %s %s", message, kwargs or "")
+
+    def end(self, message: str = "", **kwargs) -> None:
+        self._logger.debug("END %s %s", message, kwargs or "")
+
+    def info(self, message: str = "", **kwargs) -> None:
+        self._logger.info("%s %s", message, kwargs or "")
+
+    def error(self, message: str = "", **kwargs) -> None:
+        self._logger.error("%s %s", message, kwargs or "")
+
+    def exception(self, message: str = "", **kwargs) -> None:
+        self._logger.exception("%s %s", message, kwargs or "")
+
+
+def create_smart_llm_logger():
+    """Create the circles-zone logger-local Logger, or a stdlib fallback."""
+    try:
+        from logger_local.LoggerLocal import Logger
+        return Logger.create_logger(
+            object=Constants.SMART_AI_CODE_LOGGER_OBJECT)
+    except Exception:  # noqa: BLE001 - any init failure means fallback
+        return _FallbackLogger()

smart_artificial_intelligence_local-0.0.1/smart_artificial_intelligence_local/src/smart_llm_result.py

@@ -0,0 +1,22 @@
+from dataclasses import dataclass, field
+from typing import Optional
+
+from .llm_mode_enum import LlmMode
+
+
+@dataclass
+class SmartLlmResult:
+    """Result of a SmartArtificialIntelligenceLocal.ask() call.
+
+    answers: successful answers per engine name.
+    errors: error message per engine name (failed or timed-out engines).
+    winner_engine_name / winner_answer: set only in JUDGE mode.
+    judge_raw_answer: the raw verdict text returned by the judge engine.
+    """
+    prompt: str
+    llm_mode: LlmMode
+    answers: dict = field(default_factory=dict)
+    errors: dict = field(default_factory=dict)
+    winner_engine_name: Optional[str] = None
+    winner_answer: Optional[str] = None
+    judge_raw_answer: Optional[str] = None

smart_artificial_intelligence_local-0.0.1/smart_artificial_intelligence_local/tests/constants_tests_smart_artificial_intelligence_local.py

@@ -0,0 +1,15 @@
+class SmartArtificialIntelligenceLocalTestsConstants:
+    # TODO Replace the placeholder component id with a real one from Slack
+    SMART_AI_TEST_COMPONENT_ID: int = 0
+    SMART_AI_TEST_COMPONENT_NAME = (
+        "Smart Artificial Intelligence Local Tests"
+    )
+    SMART_AI_DEVELOPER_EMAIL_ADDRESS = "lielchochabi@gmail.com"
+
+    SMART_AI_TEST_LOGGER_OBJECT = {
+        'component_id': SMART_AI_TEST_COMPONENT_ID,
+        'component_name': SMART_AI_TEST_COMPONENT_NAME,
+        'component_category': 'UnitTest',
+        'testing_framework': 'pytest',
+        'developer_email_address': SMART_AI_DEVELOPER_EMAIL_ADDRESS,
+    }

smart_artificial_intelligence_local-0.0.1/smart_artificial_intelligence_local/tests/smart_artificial_intelligence_local_test.py

@@ -0,0 +1,292 @@
+"""Unit tests (with mock engines) for SmartArtificialIntelligenceLocal.
+
+TDD: these tests were written first (red) and then the implementation was
+added to make them pass (green).
+"""
+import sys
+import time
+from unittest.mock import Mock
+
+import pytest
+
+from ..src.llm_mode_enum import LlmMode
+from ..src.smart_artificial_intelligence_local import (
+    SmartArtificialIntelligenceLocal,
+)
+
+PROMPT = "Summarize: the quick brown fox jumps over the lazy dog."
+
+
+@pytest.fixture
+def smart_ai() -> SmartArtificialIntelligenceLocal:
+    return SmartArtificialIntelligenceLocal(is_test_data=True)
+
+
+def test_llm_mode_enum_has_judge_and_multiple_answers():
+    # Mode 1 = LLM as a Judge, Mode 2 = return multiple answers (diagram)
+    assert LlmMode.JUDGE.value == 1
+    assert LlmMode.MULTIPLE_ANSWERS.value == 2
+
+
+def test_get_name_returns_entity_name(smart_ai):
+    assert "Smart Artificial Intelligence" in smart_ai.get_name()
+
+
+def test_multiple_answers_mode_returns_all_answers(smart_ai):
+    engine_a = Mock(return_value="answer from a")
+    engine_b = Mock(return_value="answer from b")
+    result = smart_ai.ask(
+        prompt=PROMPT,
+        engines={"engine_a": engine_a, "engine_b": engine_b},
+        llm_mode=LlmMode.MULTIPLE_ANSWERS,
+    )
+    assert result.answers == {
+        "engine_a": "answer from a",
+        "engine_b": "answer from b",
+    }
+    assert result.errors == {}
+    assert result.winner_engine_name is None
+    engine_a.assert_called_once_with(PROMPT)
+    engine_b.assert_called_once_with(PROMPT)
+
+
+def test_multiple_answers_mode_collects_engine_errors(smart_ai):
+    engine_ok = Mock(return_value="fine")
+    engine_bad = Mock(side_effect=RuntimeError("engine down"))
+    result = smart_ai.ask(
+        prompt=PROMPT,
+        engines={"engine_ok": engine_ok, "engine_bad": engine_bad},
+        llm_mode=LlmMode.MULTIPLE_ANSWERS,
+    )
+    assert result.answers == {"engine_ok": "fine"}
+    assert "engine_bad" in result.errors
+    assert "engine down" in result.errors["engine_bad"]
+
+
+def test_all_engines_failing_raises(smart_ai):
+    engine_bad = Mock(side_effect=RuntimeError("down"))
+    with pytest.raises(ValueError):
+        smart_ai.ask(
+            prompt=PROMPT,
+            engines={"engine_bad": engine_bad},
+            llm_mode=LlmMode.MULTIPLE_ANSWERS,
+        )
+
+
+def test_empty_prompt_raises(smart_ai):
+    with pytest.raises(ValueError):
+        smart_ai.ask(
+            prompt="",
+            engines={"engine_a": Mock(return_value="x")},
+            llm_mode=LlmMode.MULTIPLE_ANSWERS,
+        )
+
+
+def test_empty_engines_raises(smart_ai):
+    with pytest.raises(ValueError):
+        smart_ai.ask(
+            prompt=PROMPT,
+            engines={},
+            llm_mode=LlmMode.MULTIPLE_ANSWERS,
+        )
+
+
+def test_judge_mode_returns_winner_picked_by_judge(smart_ai):
+    engine_a = Mock(return_value="short answer")
+    engine_b = Mock(return_value="a much better detailed answer")
+    judge_engine = Mock(return_value="engine_b")
+    result = smart_ai.ask(
+        prompt=PROMPT,
+        engines={"engine_a": engine_a, "engine_b": engine_b},
+        llm_mode=LlmMode.JUDGE,
+        judge_engine=judge_engine,
+    )
+    assert result.winner_engine_name == "engine_b"
+    assert result.winner_answer == "a much better detailed answer"
+    # All answers are still returned alongside the verdict
+    assert set(result.answers) == {"engine_a", "engine_b"}
+    judge_engine.assert_called_once()
+
+
+def test_judge_prompt_contains_original_prompt_and_answers(smart_ai):
+    judge_engine = Mock(return_value="engine_a")
+    smart_ai.ask(
+        prompt=PROMPT,
+        engines={
+            "engine_a": Mock(return_value="alpha answer"),
+            "engine_b": Mock(return_value="beta answer"),
+        },
+        llm_mode=LlmMode.JUDGE,
+        judge_engine=judge_engine,
+    )
+    judge_prompt = judge_engine.call_args[0][0]
+    assert PROMPT in judge_prompt
+    assert "alpha answer" in judge_prompt
+    assert "beta answer" in judge_prompt
+    assert "engine_a" in judge_prompt
+    assert "engine_b" in judge_prompt
+
+
+def test_judge_verdict_embedded_in_sentence_is_parsed(smart_ai):
+    judge_engine = Mock(
+        return_value="The best answer is the one from engine_b."
+    )
+    result = smart_ai.ask(
+        prompt=PROMPT,
+        engines={
+            "engine_a": Mock(return_value="alpha"),
+            "engine_b": Mock(return_value="beta"),
+        },
+        llm_mode=LlmMode.JUDGE,
+        judge_engine=judge_engine,
+    )
+    assert result.winner_engine_name == "engine_b"
+    assert result.winner_answer == "beta"
+
+
+def test_judge_mode_without_judge_engine_raises(smart_ai):
+    with pytest.raises(ValueError):
+        smart_ai.ask(
+            prompt=PROMPT,
+            engines={"engine_a": Mock(return_value="x")},
+            llm_mode=LlmMode.JUDGE,
+        )
+
+
+def test_unparseable_judge_verdict_raises(smart_ai):
+    judge_engine = Mock(return_value="I cannot decide at all")
+    with pytest.raises(ValueError):
+        smart_ai.ask(
+            prompt=PROMPT,
+            engines={
+                "engine_a": Mock(return_value="alpha"),
+                "engine_b": Mock(return_value="beta"),
+            },
+            llm_mode=LlmMode.JUDGE,
+            judge_engine=judge_engine,
+        )
+
+
+def test_force_engine_runs_only_that_engine(smart_ai):
+    engine_a = Mock(return_value="from a")
+    engine_b = Mock(return_value="from b")
+    result = smart_ai.ask(
+        prompt=PROMPT,
+        engines={"engine_a": engine_a, "engine_b": engine_b},
+        llm_mode=LlmMode.MULTIPLE_ANSWERS,
+        force_engine_name="engine_a",
+    )
+    assert result.answers == {"engine_a": "from a"}
+    engine_b.assert_not_called()
+
+
+def test_force_unknown_engine_raises(smart_ai):
+    with pytest.raises(ValueError):
+        smart_ai.ask(
+            prompt=PROMPT,
+            engines={"engine_a": Mock(return_value="x")},
+            llm_mode=LlmMode.MULTIPLE_ANSWERS,
+            force_engine_name="no_such_engine",
+        )
+
+
+def test_max_response_time_times_out_slow_engine(smart_ai):
+    def slow_engine(prompt: str) -> str:
+        time.sleep(2)
+        return "too late"
+
+    fast_engine = Mock(return_value="fast answer")
+    result = smart_ai.ask(
+        prompt=PROMPT,
+        engines={"slow": slow_engine, "fast": fast_engine},
+        llm_mode=LlmMode.MULTIPLE_ANSWERS,
+        max_response_time_seconds=0.3,
+    )
+    assert result.answers == {"fast": "fast answer"}
+    assert "slow" in result.errors
+    assert "timed out" in result.errors["slow"].lower()
+
+
+if __name__ == "__main__":
+    pytest.main(sys.argv[1:])
+
+
+def test_create_smart_llm_logger_uses_logger_local_when_available(
+        monkeypatch):
+    import types
+    from ..src import smart_llm_logger
+
+    fake_logger = Mock()
+    fake_logger_class = Mock()
+    fake_logger_class.create_logger = Mock(return_value=fake_logger)
+    fake_module = types.ModuleType("logger_local.LoggerLocal")
+    fake_module.Logger = fake_logger_class
+    fake_package = types.ModuleType("logger_local")
+    fake_package.LoggerLocal = fake_module
+    monkeypatch.setitem(sys.modules, "logger_local", fake_package)
+    monkeypatch.setitem(sys.modules, "logger_local.LoggerLocal", fake_module)
+
+    created_logger = smart_llm_logger.create_smart_llm_logger()
+    assert created_logger is fake_logger
+    fake_logger_class.create_logger.assert_called_once()
+
+
+def test_create_smart_llm_logger_falls_back_when_logger_local_fails(
+        monkeypatch):
+    from ..src import smart_llm_logger
+
+    monkeypatch.setitem(sys.modules, "logger_local", None)
+    created_logger = smart_llm_logger.create_smart_llm_logger()
+    assert isinstance(created_logger, smart_llm_logger._FallbackLogger)
+    # The fallback logger must expose the full logging interface
+    created_logger.start("m")
+    created_logger.end("m")
+    created_logger.info("m")
+    created_logger.error("m")
+    created_logger.exception("m")
+
+
+def test_ask_returns_promptly_when_engine_exceeds_timeout(smart_ai):
+    """max response time must cap wall-clock time of ask() itself.
+
+    A timed-out engine keeps running in its worker thread (Python cannot
+    kill it), but ask() must NOT wait for it to finish.
+    """
+    def very_slow_engine(prompt: str) -> str:
+        time.sleep(3)
+        return "too late"
+
+    fast_engine = Mock(return_value="fast answer")
+    started_at = time.monotonic()
+    result = smart_ai.ask(
+        prompt=PROMPT,
+        engines={"very_slow": very_slow_engine, "fast": fast_engine},
+        llm_mode=LlmMode.MULTIPLE_ANSWERS,
+        max_response_time_seconds=0.3,
+    )
+    elapsed_seconds = time.monotonic() - started_at
+    assert elapsed_seconds < 1.5
+    assert result.answers == {"fast": "fast answer"}
+    assert "very_slow" in result.errors
+
+
+def test_judge_candidates_order_is_shuffled(smart_ai, monkeypatch):
+    """Candidate order must be randomized to mitigate judge position bias."""
+    from ..src import smart_artificial_intelligence_local as module
+
+    monkeypatch.setattr(
+        module.random, "shuffle", lambda items: items.reverse())
+    judge_engine = Mock(return_value="engine_a")
+    smart_ai.ask(
+        prompt=PROMPT,
+        engines={
+            "engine_a": Mock(return_value="alpha"),
+            "engine_b": Mock(return_value="beta"),
+        },
+        llm_mode=LlmMode.JUDGE,
+        judge_engine=judge_engine,
+    )
+    judge_prompt = judge_engine.call_args[0][0]
+    # With shuffle patched to reverse, engine_b must come first
+    assert judge_prompt.index("Engine name: engine_b") < \
+        judge_prompt.index("Engine name: engine_a")

smart_artificial_intelligence_local-0.0.1/smart_artificial_intelligence_local/tests/smart_llm_system_test.py

@@ -0,0 +1,98 @@
+"""System tests (without mock) for SmartArtificialIntelligenceLocal.
+
+Runs the full Smart LLM flow end-to-end through the public API with real
+engine callables (deterministic fake LLM engines implemented as plain
+functions) - no mocking framework anywhere in this file.
+"""
+import sys
+
+import pytest
+
+from ..src.llm_mode_enum import LlmMode
+from ..src.smart_artificial_intelligence_local import (
+    SmartArtificialIntelligenceLocal,
+)
+
+DOCUMENT = (
+    "Circles Zone builds reusable packages. The Smart LLM component calls"
+    " multiple LLM engines with the same prompt. A judge engine can pick"
+    " the best answer."
+)
+PROMPT = f"Summarize the following document:\n{DOCUMENT}"
+
+
+def first_sentence_engine(prompt: str) -> str:
+    """Fake LLM: 'summarizes' by returning the first sentence it finds."""
+    document = prompt.split("\n", 1)[1]
+    return document.split(".")[0].strip() + "."
+
+
+def keyword_engine(prompt: str) -> str:
+    """Fake LLM: 'summarizes' by listing capitalized words."""
+    document = prompt.split("\n", 1)[1]
+    keywords = sorted({
+        word.strip(".,") for word in document.split()
+        if word[:1].isupper()
+    })
+    return "Keywords: " + ", ".join(keywords)
+
+
+def longest_answer_judge(judge_prompt: str) -> str:
+    """Fake judge LLM: picks the engine whose answer text is the longest.
+
+    Parses the judge prompt built by the package (Engine name: X / Answer: Y
+    blocks) exactly as a real LLM would read it.
+    """
+    best_engine_name = ""
+    best_length = -1
+    current_engine_name = None
+    for line in judge_prompt.splitlines():
+        if line.startswith("Engine name: "):
+            current_engine_name = line.removeprefix("Engine name: ").strip()
+        elif line.startswith("Answer: ") and current_engine_name:
+            answer_length = len(line.removeprefix("Answer: "))
+            if answer_length > best_length:
+                best_length = answer_length
+                best_engine_name = current_engine_name
+    return best_engine_name
+
+
+def test_system_multiple_answers_end_to_end():
+    smart_ai = SmartArtificialIntelligenceLocal()
+    result = smart_ai.ask(
+        prompt=PROMPT,
+        engines={
+            "first_sentence": first_sentence_engine,
+            "keyword": keyword_engine,
+        },
+        llm_mode=LlmMode.MULTIPLE_ANSWERS,
+    )
+    assert result.answers["first_sentence"] == (
+        "Circles Zone builds reusable packages.")
+    assert result.answers["keyword"].startswith("Keywords: ")
+    assert "Circles" in result.answers["keyword"]
+    assert result.errors == {}
+    assert result.winner_engine_name is None
+
+
+def test_system_judge_end_to_end_picks_expected_winner():
+    smart_ai = SmartArtificialIntelligenceLocal()
+    result = smart_ai.ask(
+        prompt=PROMPT,
+        engines={
+            "first_sentence": first_sentence_engine,
+            "keyword": keyword_engine,
+        },
+        llm_mode=LlmMode.JUDGE,
+        judge_engine=longest_answer_judge,
+        max_response_time_seconds=30,
+    )
+    # The keyword answer is longer, so the longest-answer judge must pick it
+    assert result.winner_engine_name == "keyword"
+    assert result.winner_answer == result.answers["keyword"]
+    assert result.judge_raw_answer == "keyword"
+    assert set(result.answers) == {"first_sentence", "keyword"}
+
+
+if __name__ == "__main__":
+    pytest.main(sys.argv[1:])

smart_artificial_intelligence_local-0.0.1/smart_artificial_intelligence_local.egg-info/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: smart-artificial-intelligence-local
+Version: 0.0.1
+Summary: PyPI smart-artificial-intelligence-local Python Package owned by Circlez.ai
+Home-page: https://github.com/circles-zone/smart-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
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: summary
+
+PyPI smart-artificial-intelligence-local Python Package owned by Circlez.ai
+GHA: https://github.com/circles-zone/smart-artificial-intelligence-local-python-package/actions

smart_artificial_intelligence_local-0.0.1/smart_artificial_intelligence_local.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+README.md
+pyproject.toml
+setup.py
+smart_artificial_intelligence_local/__init__.py
+smart_artificial_intelligence_local.egg-info/PKG-INFO
+smart_artificial_intelligence_local.egg-info/SOURCES.txt
+smart_artificial_intelligence_local.egg-info/dependency_links.txt
+smart_artificial_intelligence_local.egg-info/requires.txt
+smart_artificial_intelligence_local.egg-info/top_level.txt
+smart_artificial_intelligence_local/src/__init__.py
+smart_artificial_intelligence_local/src/constants_src_smart_artificial_intelligence_local.py
+smart_artificial_intelligence_local/src/llm_mode_enum.py
+smart_artificial_intelligence_local/src/smart_artificial_intelligence_local.py
+smart_artificial_intelligence_local/src/smart_llm_logger.py
+smart_artificial_intelligence_local/src/smart_llm_result.py
+smart_artificial_intelligence_local/tests/__init__.py
+smart_artificial_intelligence_local/tests/constants_tests_smart_artificial_intelligence_local.py
+smart_artificial_intelligence_local/tests/smart_artificial_intelligence_local_test.py
+smart_artificial_intelligence_local/tests/smart_llm_system_test.py

smart_artificial_intelligence_local-0.0.1/smart_artificial_intelligence_local.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

smart_artificial_intelligence_local-0.0.1/smart_artificial_intelligence_local.egg-info/requires.txt

@@ -0,0 +1,2 @@
+python-sdk-remote
+logger-local

smart_artificial_intelligence_local-0.0.1/smart_artificial_intelligence_local.egg-info/top_level.txt

@@ -0,0 +1 @@
+smart_artificial_intelligence_local