cattykit 0.1.0__tar.gz → 0.1.2__tar.gz

{cattykit-0.1.0 → cattykit-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cattykit
-Version: 0.1.0
+Version: 0.1.2
 Summary: A framework for implementing artificial intelligence models using components from the cognitive models of the Fluid Analogies Research Group
 Author-email: George Alexander Wright <me@georgeaw.com>
 License:                     GNU AFFERO GENERAL PUBLIC LICENSE
@@ -672,58 +672,67 @@ Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=2.4.3
+Requires-Dist: pandas>=3.0.5
 Dynamic: license-file
 
 # Cattykit
 
-Cattykit is a framework for implementing artificial intelligence models based on components from the cognitive models of the Fluid Analogies Research Group including a shared workspace, slipnet, coderack, and codelets.
+Cattykit (in development) is a framework for implementing artificial intelligence models based on components from the cognitive models of the Fluid Analogies Research Group described in Hofstadter _et al_ 1995. Their models are typically built with similar components, including: a shared _workspace_, _slipnet_, _coderack_, and _codelets_.
 
-## Usage
+Models solve problems represented by graph-like structures in a workspace which is incrementally edited by micro-agents called _codelets_ that propose, build, and destroy new structures. The _slipnet_ keeps track of concepts relevant to the structures present in the workspace and encourages codelets that continue their construction. The _coderack_ is a stochastic scheduler of codelets, which are selected according to urgency. All processes in each model occur with a degree of randomness mediated by its _temperature_ which (unlike the related concept used in language model decoding and simulated annealing) is a measure of workspace quality constantly adjusted by the model itself.
 
-To install and run a model once on a single problem:
+This repository was initially motivated by the lack of a common software framework for FARG models, which were typically developed as isolated projects, often using different programming languages (some of which are now obsolete). This hinders further research into the models and, despite the promise they show as an approach to symbolic AI, acts as a barrier to their adoption in AI more widely.
 
-```python
+## Installation
+
+Install with pip:
+
+``` bash
+pip install cattykit
+```
+
+## Quick start
+
+Start by installing a model in your environment (this requires pip in the local environment).
+
+``` python
 import cattykit
-from cattykit.logging import PrintLogger
 
-# Install a model package once. The source can also be a model name or HTTPS URL.
-cattykit.install_model("./models/copycat")
+# providing a name will install the model from the Cattykit repository
+cattykit.install_model("copycat")
 
 print(cattykit.available_models())
-# ("copycat",)
+# ('cattykit',)
 
-logger = PrintLogger()
-try:
-    copycat = cattykit.load_model(
-        "copycat",
-        config={"seed": 1234},
-        logger=logger,
-    )
-    copycat.solve("abc -> abd ==> ijk -> ?")
-finally:
-    logger.close()
+# providing a uri will install a model from your computer or elsewhere
+cattykit.install_model("path/to/model")
 ```
 
-To run a suite of problems on a single model:
+The same installation is available from the command line:
 
-``` python
-from cattykit import install_model, run_experiment
+```bash
+cattykit install copycat --version 0.1.0
+```
+
+Once you have installed a model, you can ask it to solve a problem.
+
+```python
+import cattykit
 
-# Install the model if necessary.
-cattykit.install_model("./models/copycat")
+copycat = cattykit.load_model("copycat", config={"seed": 1234})
 
-results_db = run_experiment(
-    model_name="copycat",
-    problems=[
-	    "abc -> abd ==> ijk -> ?",
-		"abc -> abc ==> iijjkk -> ?",
-		"abc -> abc ==> kji -> ?",
-		"abc -> abc ==> mrrjjj -> ?",
-		"abc -> abc ==> xyz -> ?",
-    ],
-	iterations=1000
-)
-print(results_db)
+result = copycat.solve("abc -> abd ==> ijk -> ?")
+
+print(result)
+# 'ijl'
 ```
 
-This will generate a database located at `results_db` containing logs of the runs and summary statistics. These can be explored using the Cattycam package.
+## References
+
+* Hofstadter, D. R., et al. (1995). Fluid Concepts and Creative Analogies: Computer Models of the Fundamental Mechanisms of Thought. Basic Books. [doi:10.5555/218753](https://dl.acm.org/doi/10.5555/218753)
+* Mitchell, M (1993). Analogy-Making as Perception: A Computer Model. The MIT Press. [doi:10.5555/152203](https://dl.acm.org/doi/book/10.5555/152203)
+
+## License
+
+Cattykit is licensed under the GNU Affero General Public License v3.0 or later.
+See [LICENSE](LICENSE) for details.

cattykit-0.1.2/README.md

@@ -0,0 +1,61 @@
+# Cattykit
+
+Cattykit (in development) is a framework for implementing artificial intelligence models based on components from the cognitive models of the Fluid Analogies Research Group described in Hofstadter _et al_ 1995. Their models are typically built with similar components, including: a shared _workspace_, _slipnet_, _coderack_, and _codelets_.
+
+Models solve problems represented by graph-like structures in a workspace which is incrementally edited by micro-agents called _codelets_ that propose, build, and destroy new structures. The _slipnet_ keeps track of concepts relevant to the structures present in the workspace and encourages codelets that continue their construction. The _coderack_ is a stochastic scheduler of codelets, which are selected according to urgency. All processes in each model occur with a degree of randomness mediated by its _temperature_ which (unlike the related concept used in language model decoding and simulated annealing) is a measure of workspace quality constantly adjusted by the model itself.
+
+This repository was initially motivated by the lack of a common software framework for FARG models, which were typically developed as isolated projects, often using different programming languages (some of which are now obsolete). This hinders further research into the models and, despite the promise they show as an approach to symbolic AI, acts as a barrier to their adoption in AI more widely.
+
+## Installation
+
+Install with pip:
+
+``` bash
+pip install cattykit
+```
+
+## Quick start
+
+Start by installing a model in your environment (this requires pip in the local environment).
+
+``` python
+import cattykit
+
+# providing a name will install the model from the Cattykit repository
+cattykit.install_model("copycat")
+
+print(cattykit.available_models())
+# ('cattykit',)
+
+# providing a uri will install a model from your computer or elsewhere
+cattykit.install_model("path/to/model")
+```
+
+The same installation is available from the command line:
+
+```bash
+cattykit install copycat --version 0.1.0
+```
+
+Once you have installed a model, you can ask it to solve a problem.
+
+```python
+import cattykit
+
+copycat = cattykit.load_model("copycat", config={"seed": 1234})
+
+result = copycat.solve("abc -> abd ==> ijk -> ?")
+
+print(result)
+# 'ijl'
+```
+
+## References
+
+* Hofstadter, D. R., et al. (1995). Fluid Concepts and Creative Analogies: Computer Models of the Fundamental Mechanisms of Thought. Basic Books. [doi:10.5555/218753](https://dl.acm.org/doi/10.5555/218753)
+* Mitchell, M (1993). Analogy-Making as Perception: A Computer Model. The MIT Press. [doi:10.5555/152203](https://dl.acm.org/doi/book/10.5555/152203)
+
+## License
+
+Cattykit is licensed under the GNU Affero General Public License v3.0 or later.
+See [LICENSE](LICENSE) for details.

cattykit-0.1.2/cattykit/cli.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+
+from .models import ModelInstallationError, ModelSourceError, install_model
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Run the CattyKit command-line interface."""
+    parser = argparse.ArgumentParser(prog="cattykit")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    install_parser = commands.add_parser("install", help="Install a model.")
+    install_parser.add_argument(
+        "source", help="Official model name, HTTPS URL, or local path."
+    )
+    install_parser.add_argument(
+        "--version",
+        help="Official model version to install.",
+    )
+
+    args = parser.parse_args(argv)
+
+    try:
+        install_model(args.source, version=args.version)
+    except (ModelInstallationError, ModelSourceError) as error:
+        parser.error(str(error))