polycog-cognition 1.0.0__tar.gz

polycog_cognition-1.0.0/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Polycog, Inc.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

polycog_cognition-1.0.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: polycog-cognition
+Version: 1.0.0
+Summary: Polycog cognition library
+Author-email: Nate Derbinsky <nate@polycog.ai>
+Project-URL: Homepage, https://polycog.ai
+Project-URL: Repository, https://github.com/polycog/cognition.git
+Keywords: ai,neurosymbolic
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: pydantic-ai-slim[spec]~=2.9.1
+Requires-Dist: networkx~=3.6.1
+Requires-Dist: types-networkx~=3.6.1.0
+Dynamic: license-file
+
+<div align="center">
+
+# Polycog cognition
+
+[![Checks](https://github.com/polycog/cognition/actions/workflows/checks.yml/badge.svg)](https://github.com/polycog/cognition/actions/workflows/checks.yml)
+[![License: FSL-1.1-ALv2](https://img.shields.io/badge/license-FSL--1.1--ALv2-blue.svg)](https://fsl.software)
+![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fpolycog%2Fcognition%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)
+[![Discord](https://img.shields.io/discord/1498434981788123206)](https://discord.gg/Uqhjq9vBnV)
+
+<p>
+    <a href="https://polycog.ai" target="_blank">Website</a> &bull;
+    <a href="https://github.com/polycog/tutorials" target="_blank">Tutorials</a> &bull;
+    <a href="https://docs.polycog.ai" target="_blank">Docs</a>
+</p>
+
+</div>
+
+Reasoning infrastructure for trustworthy agents.
+

polycog_cognition-1.0.0/README.md

@@ -0,0 +1,19 @@
+<div align="center">
+
+# Polycog cognition
+
+[![Checks](https://github.com/polycog/cognition/actions/workflows/checks.yml/badge.svg)](https://github.com/polycog/cognition/actions/workflows/checks.yml)
+[![License: FSL-1.1-ALv2](https://img.shields.io/badge/license-FSL--1.1--ALv2-blue.svg)](https://fsl.software)
+![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fpolycog%2Fcognition%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)
+[![Discord](https://img.shields.io/discord/1498434981788123206)](https://discord.gg/Uqhjq9vBnV)
+
+<p>
+    <a href="https://polycog.ai" target="_blank">Website</a> &bull;
+    <a href="https://github.com/polycog/tutorials" target="_blank">Tutorials</a> &bull;
+    <a href="https://docs.polycog.ai" target="_blank">Docs</a>
+</p>
+
+</div>
+
+Reasoning infrastructure for trustworthy agents.
+

polycog_cognition-1.0.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools >= 82.0.1"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "polycog-cognition"
+dynamic = ["version"]
+dependencies = [
+    "pydantic-ai-slim[spec] ~= 2.9.1",
+    "networkx ~= 3.6.1",
+    "types-networkx ~= 3.6.1.0",
+]
+requires-python = ">=3.13"
+authors = [
+    { name="Nate Derbinsky", email="nate@polycog.ai" }
+]
+description = "Polycog cognition library"
+readme = "README.md"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+keywords = [
+    "ai",
+    "neurosymbolic",
+]
+
+[project.urls]
+Homepage = "https://polycog.ai"
+Repository = "https://github.com/polycog/cognition.git"
+
+[tool.setuptools.dynamic]
+version = {attr = "cognition.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"cognition" = ["py.typed"]
+
+[tool.black]
+target-version = ["py313",]
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+
+[tool.pylint.MAIN]
+ignored-classes = ["AttrReferral"]
+
+[tool.pylint.similarities]
+min-similarity-lines=8

polycog_cognition-1.0.0/setup.cfg

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

polycog_cognition-1.0.0/src/cognition/__init__.py

@@ -0,0 +1,22 @@
+"""
+Polycog cognition library
+"""
+
+import logging
+
+from .cogent import *
+from .decision import *
+from .knowledge import *
+from .language import *
+from .reasoning import *
+from .util import *
+
+# ===
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.NOTSET)
+logger.addHandler(logging.NullHandler())
+
+# ===
+
+__version__ = "1.0.0"

polycog_cognition-1.0.0/src/cognition/cogent/__init__.py

@@ -0,0 +1,44 @@
+"""
+Cogent sub-module
+"""
+
+from . import cogent, env
+from .cogent import (
+    Cogent,
+    self_actuator,
+    self_sensor,
+)
+from .env import (
+    Actuator,
+    ActuatorInvoker,
+    BaseActuator,
+    BaseSensor,
+    Sensor,
+    SensorReader,
+    create_actuator,
+    create_sensor,
+    install,
+    invoke_actuator,
+    perceive,
+    read_sensor_data,
+)
+
+__all__ = [
+    "Actuator",
+    "ActuatorInvoker",
+    "BaseActuator",
+    "BaseSensor",
+    "Cogent",
+    "Sensor",
+    "SensorReader",
+    "cogent",
+    "create_actuator",
+    "create_sensor",
+    "env",
+    "install",
+    "invoke_actuator",
+    "perceive",
+    "read_sensor_data",
+    "self_actuator",
+    "self_sensor",
+]

polycog_cognition-1.0.0/src/cognition/cogent/cogent.py

@@ -0,0 +1,384 @@
+"""
+(Cog)nitive ag(ents)
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Any, Literal, Self
+
+from ..decision.core import (
+    BaseDecisionProcess,
+    DecisionProcessErrorMessage,
+    DecisionProcessExecutionError,
+)
+from ..decision.dp import NamedObject, args_added, format_name_params
+from ..util.functypes import BiFunction, BiPredicate, Function, Predicate, Supplier
+from ..util.misc import stringify
+from .env import (
+    BaseActuator,
+    BaseSensor,
+    create_actuator,
+    create_sensor,
+    install,
+    perceive,
+)
+
+# ===
+
+_logger = logging.getLogger(__name__)
+
+# ===
+
+
+def self_sensor[C: Cogent[Any], T](m: Function[C, T]) -> Function[C, T]:
+    """
+    Decorator to mark a cogent method for use as a sensor upon instance init
+
+    :param m: method
+    :return: supplied method (tagged for later init)
+    """
+
+    # pylint: disable=protected-access
+    m._is_selfsensor = True  # type: ignore[attr-defined]
+    return m
+
+
+def self_actuator[C: Cogent[Any], P, F](
+    m: BiFunction[C, P, F],
+) -> BiFunction[C, P, F]:
+    """
+    Decorator to mark a cogent method for use as an actuator upon instance init
+
+    :param m: method
+    :return: supplied method (tagged for later init)
+    """
+
+    # pylint: disable=protected-access
+    m._is_selfactuator = True  # type: ignore[attr-defined]
+    return m
+
+
+class Cogent[DP: BaseDecisionProcess[Any]](NamedObject):
+    """
+    Base for a cognitive agent that uses type ``S``
+    for decision process state, and ``DP`` as the
+    type of decision process
+    """
+
+    DEFAULT_NAME: str = "cogent"
+
+    _self_sensors: dict[str, Function[Cogent[DP], Any]]
+    _self_actuators: dict[str, BiFunction[Cogent[DP], Any, Any]]
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+
+        cls._self_sensors = {
+            name: val
+            for name, val in vars(cls).items()
+            if callable(val) and getattr(val, "_is_selfsensor", False)
+        }
+
+        cls._self_actuators = {
+            name: val
+            for name, val in vars(cls).items()
+            if callable(val) and getattr(val, "_is_selfactuator", False)
+        }
+
+    def _add_self_tagged(self) -> None:
+
+        if hasattr(self, "_self_sensors"):
+            for s_n, s_m in self._self_sensors.items():
+
+                def _self_sensor[T](orig_method: Function[Cogent[DP], T] = s_m) -> T:
+                    return orig_method(self)
+
+                self.add_sensor(create_sensor(s_n, _self_sensor))
+
+        if hasattr(self, "_self_actuators"):
+            for a_n, a_m in self._self_actuators.items():
+
+                def _self_actuator[P, F](
+                    param: P, orig_method: BiFunction[Cogent[DP], P, F] = a_m
+                ) -> F:
+                    return orig_method(self, param)
+
+                self.add_actuator(create_actuator(a_n, _self_actuator))
+
+    # ===
+
+    def __init__(
+        self, decision_process: DP, name: str = DEFAULT_NAME, **kwargs: Any
+    ) -> None:
+        """
+        :param decision_process: agent control
+        :param name: agent name
+        :param kwargs: optional parameters to describe the agent
+        """
+
+        self._dp = decision_process
+        self._sensors: set[BaseSensor[Any]] = set()
+
+        self._name = name
+        self._params = kwargs
+        self._str = format_name_params(name, **kwargs)
+
+        # ===
+
+        self._add_self_tagged()
+
+        _logger.info("Cogent (%s): initialized", self)
+
+    def __str__(self) -> str:
+        return self._str
+
+    @property
+    def dp(self) -> DP:
+        """
+        :return: decision process for this cogent
+        """
+
+        return self._dp
+
+    @property
+    def name(self) -> str:
+        """
+        :return: cogent's name
+        """
+
+        return self._name
+
+    @property
+    def params(self) -> Mapping[str, Any]:
+        """
+        :return: optional augmentations to the cogent
+        """
+
+        return MappingProxyType(self._params)
+
+    def add_sensor(self, sensor: BaseSensor[Any]) -> Self:
+        """
+        Add a sensor to the cogent
+
+        :param sensor: sensor to add
+        :return: this cogent (for chaining)
+        """
+
+        _logger.info("Cogent (%s): sensor (%s) added", self, sensor.name)
+
+        self._sensors.add(sensor)
+        return self
+
+    def sensor(
+        self,
+        **kwargs: Any,
+    ) -> Function[type[BaseSensor[Any]], type[BaseSensor[Any]]]:
+        """
+        Decorator version of :meth:`Cogent.add_sensor`
+
+        :param kwargs: instantiation argument(s)
+        :return: parameterized decorator
+        """
+
+        def cls_dec(cls: type[BaseSensor[Any]]) -> type[BaseSensor[Any]]:
+            """
+            Adds a sensor instance to this cogent.
+
+            :param cls: sensor to instantiate
+            :return: added class
+            """
+
+            self.add_sensor(cls(**kwargs))
+            return cls
+
+        return cls_dec
+
+    def as_sensor[T](self, name: str) -> Function[Supplier[T], Supplier[T]]:
+        """
+        Decorator version of :func:`.env.create_sensor`
+
+        :param name: name for the sensor instance
+        :return: parameterized decorator
+        """
+
+        def dec(f: Supplier[T]) -> Supplier[T]:
+            self.add_sensor(create_sensor(name, f))
+            return f
+
+        return dec
+
+    def add_actuator(self, actuator: BaseActuator[Any, Any]) -> Self:
+        """
+        Add an actuator to the cogent
+
+        :param actuator: actuator to add
+        :return: this cogent (for chaining)
+        """
+
+        _logger.info("Cogent (%s): actuator (%s) installed", self, actuator.name)
+
+        install(actuator, self._dp)
+        return self
+
+    def actuator(
+        self,
+        **kwargs: Any,
+    ) -> Function[type[BaseActuator[Any, Any]], type[BaseActuator[Any, Any]]]:
+        """
+        Decorator version of :meth:`Cogent.add_actuator`
+
+        :param kwargs: instantiation argument(s)
+        :return: parameterized decorator
+        """
+
+        def cls_dec(cls: type[BaseActuator[Any, Any]]) -> type[BaseActuator[Any, Any]]:
+            """
+            Adds a actuator instance to this cogent.
+
+            :param cls: actuator to instantiate
+            :return: added class
+            """
+
+            self.add_actuator(cls(**kwargs))
+            return cls
+
+        return cls_dec
+
+    def as_actuator[P, F](self, name: str) -> Function[Function[P, F], Function[P, F]]:
+        """
+        Decorator version of :func:`.env.create_actuator`
+
+        :param name: name for the actuator instance
+        :return: parameterized decorator
+        """
+
+        def dec(f: Function[P, F]) -> Function[P, F]:
+            self.add_actuator(create_actuator(name, f))
+            return f
+
+        return dec
+
+    def perception(self) -> None:
+        """
+        All added sensors are routed to the decision process IO container
+        """
+
+        _logger.info("Cogent (%s): all-sensor perception", self)
+
+        for s in self._sensors:
+            perceive(s, self._dp)
+
+    @stringify("run_once")
+    @staticmethod
+    def gate_run_once(_c: Cogent[Any]) -> Literal[False]:
+        """
+        Immediate end upon decision process termination
+        """
+
+        return False
+
+    @stringify("run_forever")
+    @staticmethod
+    def gate_run_forever(_c: Cogent[Any]) -> Literal[True]:
+        """
+        Restarts decision process upon termination
+        """
+
+        return True
+
+    def __call__(
+        self,
+        repeat_p: Predicate[Cogent[DP]] = gate_run_once,
+        max_cycles: int | None = None,
+        dp_err_p: BiPredicate[DecisionProcessErrorMessage, Self] | None = None,
+        other_err_p: BiPredicate[Exception, Self] | None = None,
+        **args: Any,
+    ) -> Self:
+        """
+        After initialization (dp.reinit, add arguments),
+        runs a cogent loop...
+
+        1. Cache sensor(s) perception to IO
+        2. Run the decision process
+        3. Check the gating predicate
+           (reinitialize the decision process if not done)
+
+        until the supplied gating predicate returns ``False``
+
+        :param repeat_p: gating predicate (assuming no errors)
+        :param max_cycles: maximum dp cycles to run per loop;
+                           ``None`` indicates no limit
+        :param dp_err_p: gating predicate to continue if a known
+                         error type occurs (or raise if ``None``)
+                         (see :class:`cognition.decision.core.DecisionProcessExecutionError`)
+        :param other_err_p: gating predicate to continue if an unknown
+                            error type occurs (or raise if ``None``)
+        :param args: IO args to add (see :func:`cognition.decision.dp.args_added`)
+        :return: this cogent (for chaining)
+        """
+
+        _logger.info("Cogent (%s): run started", self)
+        _logger.debug(
+            "repeat_p=%s, max_cycles=%s, dp_err_p=%s, args=%s",
+            repeat_p,
+            max_cycles,
+            dp_err_p,
+            args,
+        )
+
+        proceed = True
+        self._dp.reinit()
+
+        with args_added(self._dp, **args):
+            while proceed:
+                _logger.debug("Cogent (%s): loop start", self)
+
+                try:
+                    self.perception()
+                    if max_cycles is None:
+                        self._dp.run_until_done()
+                    else:
+                        self._dp.run_cycles(max_cycles)
+
+                    _logger.debug("Cogent (%s): dp run complete", self)
+
+                    proceed = repeat_p(self)
+                    _logger.debug(
+                        "Cogent (%s): gate checked (keep going: %s)", self, proceed
+                    )
+                except DecisionProcessExecutionError as err_dp:
+                    _logger.error(err_dp)
+
+                    if dp_err_p is not None:
+                        proceed = dp_err_p(err_dp.msg, self)
+
+                        _logger.debug(
+                            "Cogent (%s): known error gate checked (keep going: %s)",
+                            self,
+                            proceed,
+                        )
+                    else:
+                        raise
+                except Exception as err_other:  # pylint: disable=broad-exception-caught
+                    _logger.error(err_other)
+
+                    if other_err_p is not None:
+                        proceed = other_err_p(err_other, self)
+
+                        _logger.debug(
+                            "Cogent (%s): unknown error gate checked (keep going: %s)",
+                            self,
+                            proceed,
+                        )
+                    else:
+                        raise
+
+                if proceed:
+                    self._dp.reinit()
+
+        _logger.info("Cogent (%s): run ended", self)
+
+        return self