Metadata-Version: 2.4
Name: cattycam
Version: 0.1.0
Summary: An interactive tool for logging and debugging artificial intelligence models built using Cattykit
License-Expression: AGPL-3.0-or-later
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: panel>=1.5
Dynamic: license-file

# Cattycam

Cattycam is an interactive tool for viewing and debugging the internals of artificial intelligence models built using Cattykit.

## Installation

Install with pip:

``` bash
pip install cattycam
```

## Quick start

Run a Cattykit model with the `CattycamLogger` from `cattykit.logging`:

``` python
from cattykit import load_model
from cattykit.logging import CattycamLogger

cattycam_logger = CattycamLogger("history.sqlite", "copycat")

copycat = cattykit.load_model(
    "copycat",
	config={"seed": 1234},
	logger=cattycam_logger
)

copycat.solve("abc -> abd ==> ijk -> ?")
copycat.solve("abc -> abd ==> xyz -> ?")
...
```

Running the model with a Cattycam logger records the internal processes and intermediate structures in a sqlite database.

To view these in graphical user interface, run Cattycam with the path to the generated database:

```shell
cattycam path/to/history.sqlite
```

The app launches your web browser and gives you access to the logs from each recorded run in the database grouped by input problem. The visualizations generated by Cattycam reproduce the images displayed by Mitchell 1993.

![Cattycam runs page](https://raw.githubusercontent.com/georgeawright/cattykit/main/packages/cattycam/docs/images/cattycam-runs.png)

Selecting one problem's overview takes you to a statistical summary of the model when run on the problem (you will have to run the program multiple times with different seeds to get different outputs).

![Cattycam problem overview](https://raw.githubusercontent.com/georgeawright/cattykit/main/packages/cattycam/docs/images/cattycam-problem-overview.png)

The overview displays charts with distribution of answers, the number of codelets run generating each answer, and the final temperature for each answer. There is also a table at the bottom of the page listing each run. Clicking on the row's `view` button opens a run page.

![Cattycam run overview](https://raw.githubusercontent.com/georgeawright/cattykit/main/packages/cattycam/docs/images/cattycam-run-overview.png)

The top of the run page shows a summary of run over time, including the changing population of the coderack and workspace, and the changing temperature of the program.

![Cattycam run details](https://raw.githubusercontent.com/georgeawright/cattykit/main/packages/cattycam/docs/images/cattycam-run-details.png)

Below this are the coderack, workspace, and slipnet at the time that the program finished. There is also a codelet history showing the codelets that ran up to that point in reverse chronological order.

Use the time slider to view the program at a different point in time and the play buttons above the time slider to see a slow motion playback of the program.

## References

* 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

Cattycam is licensed under the GNU Affero General Public License v3.0 or later.
See [LICENSE](LICENSE) for details.
