symbolicai 0.21.0__tar.gz → 1.0.0__tar.gz

{symbolicai-0.21.0 → symbolicai-1.0.0}/.gitignore

@@ -162,7 +162,3 @@ symsh
 .bash_history
 .conversation_state
 .symai
-zagent-review
-zagent-research
-.codex/context
-llama.cpp

symbolicai-1.0.0/MANIFEST.in

@@ -0,0 +1,3 @@
+global-exclude test_*.py
+include symai/**/*
+exclude **/*.pyc

{symbolicai-0.21.0 → symbolicai-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: symbolicai
-Version: 0.21.0
+Version: 1.0.0
 Summary: A Neurosymbolic Perspective on Large Language Models
 Author-email: Marius-Constantin Dinu <marius@extensity.ai>, Leoveanu-Condrei Claudiu <leo@extensity.ai>
 License: BSD 3-Clause License
@@ -84,6 +84,7 @@ Requires-Dist: httpx>=0.27.2
 Requires-Dist: nest-asyncio>=1.6.0
 Requires-Dist: rich>=13.9.4
 Requires-Dist: playwright>=1.55.0
+Requires-Dist: llvmlite>=0.45.1
 Provides-Extra: bitsandbytes
 Requires-Dist: bitsandbytes>=0.43.1; extra == "bitsandbytes"
 Provides-Extra: blip2
@@ -107,7 +108,8 @@ Provides-Extra: wolframalpha
 Requires-Dist: wolframalpha>=5.0.0; extra == "wolframalpha"
 Provides-Extra: whisper
 Requires-Dist: openai-whisper>=20240930; extra == "whisper"
-Requires-Dist: numba>=0.60.0; extra == "whisper"
+Requires-Dist: numba>=0.62.1; extra == "whisper"
+Requires-Dist: llvmlite>=0.45.1; extra == "whisper"
 Provides-Extra: serpapi
 Requires-Dist: google_search_results>=2.4.2; extra == "serpapi"
 Provides-Extra: services

{symbolicai-0.21.0 → symbolicai-1.0.0}/docs/source/FEATURES/contracts.md

@@ -157,10 +157,10 @@ This method defines the pre-conditions for your contract. It's called with the v
 
 The `act` method provides an optional intermediate processing step that occurs *after* input pre-validation (and potential pre-remedy) and *before* the main output validation/generation phase (`_validate_output`).
 
-*   **Signature**: `def act(self, input: YourInputModelOrActInputModel, **kwargs) -> YourIntermediateModel:`
-    *   The `input` parameter **must be named `input`** and be type-hinted with an `LLMDataModel` subclass.
-    *   It must have a return type annotation, also an `LLMDataModel` subclass. This can be a different type than the input, allowing `act` to transform the data.
-    *   `**kwargs` from the original call (excluding `'input'`) are passed to `act`.
+*   **Signature**: `def act(self, act_input: YourInputModelOrActInputModel, **kwargs) -> YourIntermediateModel:`
+    *   The decorator treats the **first positional or positional-or-keyword parameter after `self`** as the contract input. You can keep naming it `input` for clarity, but any valid identifier works.
+    *   That parameter must be type-hinted with an `LLMDataModel` subclass (or a Python type that can be wrapped dynamically). The method must also declare a return type annotation so the contract knows which `LLMDataModel` to build next.
+    *   `**kwargs` from the original call—excluding the canonical input argument—are passed through to `act`.
 *   **Behavior**:
     *   Perform transformations on the `input`, computations, or state updates on `self`.
     *   The object returned by `act` becomes the `current_input` for the `_validate_output` stage (where the LLM is typically called to generate the final output type).
@@ -205,10 +205,11 @@ This method defines the post-conditions. It's called by `_validate_output` with
 
 This is your class's original `forward` method, containing the primary logic. The `@contract` decorator wraps this method.
 
-*   **Signature**: `def forward(self, input: YourInputModel, **kwargs) -> YourOutputModel:`
-    *   The `input` parameter **must be named `input`** and be type-hinted with an `LLMDataModel` subclass that matches (or is compatible with) the input to `pre` and `act`.
-    *   It **must have a return type annotation** (e.g., `-> YourOutputModel`), which must be an `LLMDataModel` subclass. This declared type is crucial for the contract's type validation and output generation phases.
-    *   It **must not use positional arguments (`*args`)**; only keyword arguments are supported for the main input. Other `**kwargs` are passed through to the neurosymbolic engine.
+*   **Signature**: `def forward(self, model_input: YourInputModel, **kwargs) -> YourOutputModel:`
+    *   The decorator binds the **first positional or positional-or-keyword parameter after `self`** as the canonical contract input. Naming the parameter `input` is still idiomatic, but any identifier works.
+    *   That parameter must be type-hinted with an `LLMDataModel` subclass (or a Python type that the decorator can wrap dynamically) compatible with your `pre`/`act` expectations.
+    *   The method **must have a return type annotation** (e.g., `-> YourOutputModel`), which must be an `LLMDataModel` subclass. This declared type is crucial for the contract's type validation and output generation phases.
+    *   Calls may use positional or keyword arguments interchangeably; any remaining `**kwargs` are forwarded unchanged to your logic and downstream engines.
 *   **Behavior**:
     *   This method is **always called** by the contract's `wrapped_forward` (in its `finally` block), regardless of whether the preceding contract validations (`pre`, `act`, `post`, remedies) succeeded or failed.
     *   **Developer Responsibility**: Inside your `forward` method, you *must* check `self.contract_successful` and/or `self.contract_result`.
@@ -219,9 +220,9 @@ This is your class's original `forward` method, containing the primary logic. Th
                 ```python
                 raise self.contract_exception or ValueError("Contract failed!")
                 ```
-    *   The `input` argument received by *this* `forward` method (the one you write) depends on whether the contract succeeded:
-        *   If `contract_successful == True`: `input` is the `current_input` from `wrapped_forward` which was used by `_validate_output`. This `current_input` is the output of `_act` if `act` is defined, otherwise it's the output of `_validate_input`.
-        *   If `contract_successful == False`: `input` is the `original_input` (the raw input to the contract call, after initial type validation by `_is_valid_input` but before `pre` or `act` modifications).
+    *   The argument bound to your first non-`self` parameter (e.g., `model_input`) depends on whether the contract succeeded:
+        *   If `contract_successful == True`: that argument is the `current_input` from `wrapped_forward` which was used by `_validate_output`. This `current_input` is the output of `_act` if `act` is defined, otherwise it's the output of `_validate_input`.
+        *   If `contract_successful == False`: that argument is the `original_input` (the raw value provided to the contract call, after initial type validation by `_is_valid_input` but before `pre` or `act` modifications).
 
 ```python
     def forward(self, input: MyInput, **kwargs) -> MyOutput:
@@ -237,6 +238,16 @@ This is your class's original `forward` method, containing the primary logic. Th
         return final_result
 ```
 
+#### Input Binding Rules
+
+The contract wrapper now resolves the canonical input value without requiring an `input=` keyword argument. The resolution order is:
+
+1.  The first positional argument supplied when you call the contracted instance (i.e., `my_expr(my_input)`).
+2.  If no positional value is provided, the first positional-or-keyword parameter defined after `self` in your `forward` signature (for example, `model_input`) is fetched from `**kwargs`.
+3.  As a backwards-compatible fallback, an explicit `input=` keyword argument is still accepted.
+
+The resolved object is then passed consistently through `_is_valid_input`, `pre`, `act`, `_validate_output`, and finally your original `forward` method. All remaining keyword arguments are forwarded untouched.
+
 #### Error Handling and Propagation
 
 When a contract validation or remediation step fails, the exception is captured in `self.contract_exception`, and `self.contract_successful` is set to `False`. If you prefer to surface these errors instead of returning fallback values, you can propagate the exception in your `forward` implementation:
@@ -285,17 +296,17 @@ To illustrate, say you want a non-trivial `title: str` in your output object, bu
 
 ## Contract Execution Flow
 
-When you call an instance of your contracted class (e.g., `my_instance(input=my_input_data)`), the `wrapped_forward` method (created by the `@contract` decorator) executes the following sequence:
+When you call an instance of your contracted class (e.g., `my_instance(my_input_data)` or `my_instance(input=my_input_data)`), the `wrapped_forward` method (created by the `@contract` decorator) executes the following sequence:
 
 0.  **Return Type Annotation Validation & Dynamic Wrapping (`_is_valid_output` + `_try_dynamic_type_annotation`)**:
     *   Inspects your `forward` method's return type annotation (`sig.return_annotation`).
     *   Ensures you provided a return type annotation and it’s a subclass of `LLMDataModel`.
     *   If the annotation is a native Python/typing type (e.g., `str`, `list[int]`, `Optional[...]`), the system automatically builds a dynamic `LLMDataModel` wrapper for the output type, allowing subsequent validation and unwrapping.
 
-1.  **Initial Input Validation & Dynamic Wrapping (`_is_valid_input` + `_try_dynamic_type_annotation`)**:
-    *   Checks if the provided `input` kwarg is an instance of `LLMDataModel`. Fails fast if not.
-    *   Extracts the `original_input` object.
-    *   If the `input` is a native Python type (and not an `LLMDataModel`), the system inspects your `forward` signature to infer the expected Python type and automatically wraps your primitive or container in a temporary `LLMDataModel` for validation (via `_try_dynamic_type_annotation`).
+1.  **Initial Input Collection & Dynamic Wrapping (`_is_valid_input` + `_try_dynamic_type_annotation`)**:
+    *   Determines the canonical contract input by prioritizing the first positional argument after `self`. If no positional value is provided, it falls back to the first compatible keyword (preferring the corresponding parameter name, then `input` for backward compatibility).
+    *   Validates that canonical value with `_is_valid_input` and stores it as `original_input`.
+    *   If the value is a native Python type (and not already an `LLMDataModel`), the system inspects your `forward` signature to infer the expected Python type and automatically wraps your primitive or container in a temporary `LLMDataModel` for validation (via `_try_dynamic_type_annotation`).
 
 2.  **Pre-condition Validation (`_validate_input`)**:
     *   The `current_input` (initially `original_input`) is passed to your `pre(input)` method.
@@ -304,7 +315,7 @@ When you call an instance of your contracted class (e.g., `my_instance(input=my_
 
 3.  **Intermediate Action (`_act`)**:
     *   If your class defines an `act` method:
-        *   Its signature is validated (parameter named `input`, `LLMDataModel` type hints for input and output).
+        *   Its signature is validated to ensure the first positional (or positional-or-keyword) parameter after `self` is type-hinted, and the return annotation is present.
         *   `act(current_input, **act_kwargs)` is called. `current_input` here is the output from the pre-condition validation step.
         *   The result of `act` becomes the new `current_input`.
         *   The actual type of `act`'s return value is checked against its annotation.
@@ -332,7 +343,7 @@ When you call an instance of your contracted class (e.g., `my_instance(input=my_
     *   It determines the `forward_input` for your original `forward` method:
         *   If `self.contract_successful` is `True`, `forward_input` is the `current_input` that successfully passed through `_act` and was used by `_validate_output`.
         *   If `self.contract_successful` is `False`, `forward_input` is the `original_input`.
-    *   Your class's original `forward(self, input=forward_input, **kwargs)` method is called.
+    *   Your class's original `forward` method is invoked with that canonical input reinserted (as the first positional argument or matching keyword) alongside the untouched auxiliary `**kwargs`.
     *   The value returned by *your* `forward` method becomes the ultimate return value of the contract call.
     *   A final output type check is performed on this returned value against your `forward` method's declared return type annotation. If the contract is configured with `graceful=True`, this final type check is skipped instead of raising a `TypeError`.
 

{symbolicai-0.21.0 → symbolicai-1.0.0}/examples/contracts.ipynb

@@ -26,9 +26,9 @@
     "# ──────────────────────────────────────────────────────────────\n",
     "#  SymbolicAI core                                              │\n",
     "# ──────────────────────────────────────────────────────────────\n",
-    "from symai import Expression           # Base class for your LLM “operators”\n",
+    "from symai import Expression  # Base class for your LLM “operators”\n",
     "from symai.models import LLMDataModel  # Thin Pydantic wrapper w/ LLM hints\n",
-    "from symai.strategy import contract    # The Design-by-Contract decorator"
+    "from symai.strategy import contract  # The Design-by-Contract decorator"
    ]
   },
   {

{symbolicai-0.21.0 → symbolicai-1.0.0}/icon_converter.py

@@ -1,6 +1,7 @@
 import os
 import platform
 import shutil
+
 import cairosvg
 from PIL import Image
 

{symbolicai-0.21.0 → symbolicai-1.0.0}/installer.py

@@ -1,10 +1,11 @@
 import os
 import platform
 import queue
-import customtkinter
-import threading
 import subprocess
-from customtkinter import CTkButton, CTkEntry, CTk, CTkProgressBar, CTkLabel, CTkTextbox
+import threading
+
+import customtkinter
+from customtkinter import CTk, CTkButton, CTkEntry, CTkLabel, CTkProgressBar, CTkTextbox
 
 
 def get_anaconda_url():

{symbolicai-0.21.0 → symbolicai-1.0.0}/legacy/notebooks/Basics.ipynb

@@ -24,12 +24,14 @@
    "source": [
     "import os\n",
     "import warnings\n",
+    "\n",
     "warnings.filterwarnings('ignore')\n",
     "os.chdir('../') # set the working directory to the root of the project\n",
     "import numpy as np\n",
+    "from IPython.display import display\n",
+    "\n",
     "from symai import *\n",
-    "from symai.components import *\n",
-    "from IPython.display import display"
+    "from symai.components import *"
    ]
   },
   {
@@ -587,7 +589,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from examples.docs import Docs, CppDocs\n",
+    "from examples.docs import CppDocs, Docs\n",
+    "\n",
     "docs = Docs()"
    ]
   },

{symbolicai-0.21.0 → symbolicai-1.0.0}/legacy/notebooks/ChatBot.ipynb

@@ -24,11 +24,13 @@
    "source": [
     "import os\n",
     "import warnings\n",
+    "\n",
     "warnings.filterwarnings('ignore')\n",
     "os.chdir('../') # set the working directory to the root of the project\n",
+    "from IPython.display import display\n",
+    "\n",
     "from symai import *\n",
-    "from symai.components import *\n",
-    "from IPython.display import display"
+    "from symai.components import *"
    ]
   },
   {

{symbolicai-0.21.0 → symbolicai-1.0.0}/legacy/notebooks/Indexer.ipynb

@@ -6,9 +6,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from symai.components import *\n",
     "from symai.backend.mixin.tracker import OpenAICostTracker\n",
-    "from symai import *"
+    "\n",
+    "from symai import *\n",
+    "from symai.components import *"
    ]
   },
   {
@@ -124,6 +125,7 @@
    "outputs": [],
    "source": [
     "from symai.extended import RepositoryCloner\n",
+    "\n",
     "cloner = RepositoryCloner() # load repository cloner"
    ]
   },
@@ -301,9 +303,11 @@
     }
    ],
    "source": [
-    "from symai.components import TokenTracker, Stream\n",
     "from symai.backend.mixin.tracker import OpenAICostTracker\n",
+    "\n",
     "from symai import *\n",
+    "from symai.components import Stream, TokenTracker\n",
+    "\n",
     "website = 'wyour datddy' # load page\n",
     "\n",
     "with OpenAICostTracker() as tracker: # track the cost using OpenAI API\n",
@@ -391,6 +395,7 @@
    ],
    "source": [
     "from symai import Interface\n",
+    "\n",
     "res = Interface('selenium')('https://www.baidu-venture.net/touzizuhe.html')"
    ]
   },

{symbolicai-0.21.0 → symbolicai-1.0.0}/legacy/notebooks/News.ipynb

@@ -24,11 +24,13 @@
    "source": [
     "import os\n",
     "import warnings\n",
+    "\n",
     "warnings.filterwarnings('ignore')\n",
     "os.chdir('../') # set the working directory to the root of the project\n",
+    "from IPython.display import display\n",
+    "\n",
     "from symai import *\n",
-    "from symai.components import *\n",
-    "from IPython.display import display"
+    "from symai.components import *"
    ]
   },
   {
@@ -79,7 +81,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from examples.news import HEADER_STYLE_DESCRIPTION, HTML_TEMPLATE, HTML_STREAM_STYLE_DESCRIPTION"
+    "from examples.news import HEADER_STYLE_DESCRIPTION, HTML_STREAM_STYLE_DESCRIPTION, HTML_TEMPLATE"
    ]
   },
   {

{symbolicai-0.21.0 → symbolicai-1.0.0}/legacy/notebooks/Queries.ipynb

@@ -17,11 +17,14 @@
    "source": [
     "import os\n",
     "import warnings\n",
+    "\n",
     "warnings.filterwarnings('ignore')\n",
     "print(os.getcwd())\n",
-    "from symai import *\n",
-    "from IPython.display import display\n",
     "from examples.sql import SQL\n",
+    "from IPython.display import display\n",
+    "\n",
+    "from symai import *\n",
+    "\n",
     "sql = SQL()"
    ]
   },

{symbolicai-0.21.0 → symbolicai-1.0.0}/legacy/notebooks/TTS_Persona.ipynb

@@ -6,11 +6,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from symai.extended.personas import PersonaBuilder\n",
-    "from symai.extended.personas import Dialogue\n",
-    "from symai.extended.api_builder import APIExecutor\n",
+    "from symai.extended.personas import Dialogue, PersonaBuilder\n",
     "from symai.extended.personas.student import MaxTenner\n",
-    "from symai import Interface"
+    "\n",
+    "from symai import Interface\n",
+    "from symai.extended.api_builder import APIExecutor"
    ]
   },
   {

{symbolicai-0.21.0 → symbolicai-1.0.0}/legacy/notebooks/examples/lean.py

@@ -1,4 +1,5 @@
 from symai.backend.engines.lean.engine_lean4 import LeanEngine
+
 # Example usage
 if __name__ == "__main__":
     # Initialize LeanEngine

{symbolicai-0.21.0 → symbolicai-1.0.0}/legacy/notebooks/examples/news.py

@@ -1,7 +1,6 @@
 from symai import *
 from symai.components import *
 
-
 HEADER_STYLE_DESCRIPTION = """Design a web app with HTML, CSS and inline JavaScript.
 Use dark theme and best practices for colors, text font, etc.
 Use Bootstrap for styling.

{symbolicai-0.21.0 → symbolicai-1.0.0}/legacy/notebooks/examples/paper.py

@@ -1,7 +1,6 @@
 from symai import *
 from symai.components import *
 
-
 HEADER_STYLE_DESCRIPTION = """Design a web app with HTML, CSS and inline JavaScript.
 Use dark theme and best practices for colors, text font, etc.
 Use Bootstrap for styling.

{symbolicai-0.21.0 → symbolicai-1.0.0}/legacy/notebooks/examples/sql.py

@@ -1,9 +1,8 @@
 import symai as ai
-from symai.post_processors import StripPostProcessor, CodeExtractPostProcessor
+from symai.post_processors import CodeExtractPostProcessor, StripPostProcessor
 from symai.pre_processors import PreProcessor
 from symai.symbol import Expression, Symbol
 
-
 SQL_CONTEXT = """[Description]
 The following statements describe the Structured Query Language (SQL):
 

{symbolicai-0.21.0 → symbolicai-1.0.0}/pyproject.toml

@@ -66,6 +66,7 @@ dependencies = [
     "nest-asyncio>=1.6.0",
     "rich>=13.9.4",
     "playwright>=1.55.0",
+    "llvmlite>=0.45.1",
 ]
 
 [project.optional-dependencies]
@@ -75,7 +76,7 @@ hf           = ["transformers>=4.45.2", "accelerate>=0.33.0", "peft>=0.13.1", "d
 webscraping  = ["beautifulsoup4>=4.12.3", "trafilatura>=2.0.0", "pdfminer.six", "playwright>=1.45.0"]
 llama_cpp    = ["llama-cpp-python[server]>=0.3.7"] # handle separately since this dependency may not compile and require special maintenance
 wolframalpha = ["wolframalpha>=5.0.0"]
-whisper      = ["openai-whisper>=20240930", "numba>=0.60.0"]
+whisper      = ["openai-whisper>=20240930", "numba>=0.62.1", "llvmlite>=0.45.1"]
 serpapi      = ["google_search_results>=2.4.2"]
 services     = ["fastapi>=0.110.0", "redis>=5.0.2", "uvicorn>=0.27.1"]
 solver       = ["z3-solver>=4.12.6.0"]
@@ -100,7 +101,7 @@ exclude = ["tests", "examples", "notebooks", "outputs", "assets", "app.py"]
 
 [dependency-groups]
 dev = [
-    "isort>=6.0.1",
+    "ruff>=0.14.4",
     "pytest>=8.3.1",
 ]
 

symbolicai-1.0.0/ruff.toml

@@ -0,0 +1,68 @@
+exclude = [
+    ".codex",
+    ".symai",
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".git-rewrite",
+    ".hg",
+    ".ipynb_checkpoints",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pyenv",
+    ".pytest_cache",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    ".vscode",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "site-packages",
+    "venv",
+    "scripts",
+    "tests"
+]
+
+line-length = 100
+indent-width = 4
+target-version = "py312"
+
+[lint]
+# Rules URL: https://docs.astral.sh/ruff/rules
+select = [
+  "F","E4","E7","E9",
+  "I","UP","B","SIM","C4","A","ARG","ISC","RET","RSE",
+  "G","LOG","TC","PTH","EM","C90",
+  "PLE","PLC","PLW",
+  "RUF","T10","T20"
+]
+ignore = [
+  "B028",  # no explicit stacklevel; enable if you rely on warnings for users
+  "PLW0603",  # global statement discouraged; often noisy in legacy code
+  "G004", #  logging-f-string
+  "A002", #  argument-shadowing-builtin
+]
+
+# Allow fix for all enabled rules (when `--fix`) is provided.
+fixable = ["ALL"]
+unfixable = []
+
+# Allow unused variables when underscore-prefixed.
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[lint.mccabe]
+max-complexity = 10
+
+[format]
+quote-style = "double"
+indent-style = "tab"
+skip-magic-trailing-comma = false
+line-ending = "auto"