Metadata-Version: 2.4
Name: dct-python
Version: 0.1.5
Summary: Distributed Cognitive Toolkit for codelet-based cognitive architectures.
Author-email: Wandemberg Gibaut <wgibaut@mail.com>
License: MIT License
        
        Copyright (c) 2026 Wandemberg Gibaut
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/wandgibaut/dct
Project-URL: Repository, https://github.com/wandgibaut/dct
Project-URL: Issues, https://github.com/wandgibaut/dct/issues
Keywords: cognitive architecture,codelets,distributed systems,artificial intelligence
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: server
Requires-Dist: flask>=2.2.2; extra == "server"
Requires-Dist: requests>=2.28.1; extra == "server"
Provides-Extra: redis
Requires-Dist: redis>=4.3.4; extra == "redis"
Provides-Extra: mongo
Requires-Dist: pymongo>=4.2.0; extra == "mongo"
Provides-Extra: viz
Requires-Dist: networkx>=2.8.6; extra == "viz"
Requires-Dist: matplotlib>=3.5.3; extra == "viz"
Requires-Dist: numpy>=1.21; extra == "viz"
Provides-Extra: all
Requires-Dist: flask>=2.2.2; extra == "all"
Requires-Dist: matplotlib>=3.5.3; extra == "all"
Requires-Dist: networkx>=2.8.6; extra == "all"
Requires-Dist: numpy>=1.21; extra == "all"
Requires-Dist: pymongo>=4.2.0; extra == "all"
Requires-Dist: redis>=4.3.4; extra == "all"
Requires-Dist: requests>=2.28.1; extra == "all"
Provides-Extra: publish
Requires-Dist: build>=1.2; extra == "publish"
Requires-Dist: twine>=5; extra == "publish"
Dynamic: license-file

# dct-python

Python package for the Distributed Cognitive Toolkit (DCT), a toolkit for building distributed cognitive architectures from codelets and shared memory objects.

The PyPI distribution is named `dct-python`, and the import package is named `dct`. This follows the same style as packages such as `scikit-learn`/`sklearn` and `pytorch`/`torch`.

The package provides:

- `Mind`, a standalone in-process coordinator for codelets and memories.
- `PythonCodelet`, an abstract base class for Python codelets.
- Helpers for reading and writing memory objects through local JSON files, Redis, MongoDB, or HTTP/TCP endpoints.
- A small Flask API server for node/codelet metadata and memory access.
- Utilities for creating Docker-backed nodes and drawing network connectivity.

## Installation

From the repository root:

```bash
python -m pip install .
```

For editable development:

```bash
python -m pip install -e .
```

From PyPI, after publication:

```bash
python -m pip install dct-python
```

The package supports Python 3.9 and newer. The core package can be imported without Redis, MongoDB, Flask, or plotting dependencies installed, but those dependencies are required when using the corresponding runtime features.

Optional extras:

```bash
python -m pip install "dct-python[server]"
python -m pip install "dct-python[redis]"
python -m pip install "dct-python[mongo]"
python -m pip install "dct-python[viz]"
python -m pip install "dct-python[all]"
```

## Codelets

Create a codelet by subclassing `PythonCodelet` and implementing `proc`.

```python
from dct.codelets import PythonCodelet


class MyCodelet(PythonCodelet):
    def calculate_activation(self) -> float:
        return 1.0

    def proc(self, activation: float) -> None:
        print(f"activation={activation}")
```

Each codelet directory is expected to contain a `fields.json` file. A minimal example:

```json
{
  "enable": true,
  "lock": false,
  "timestep": 0.1,
  "inputs": [],
  "outputs": []
}
```

Instantiate a codelet with the directory that contains `fields.json`:

```python
codelet = MyCodelet(name="my-codelet", root_codelet_dir="/path/to/codelet")
codelet.run()
```

## Standalone Mind

The original DCT runtime is distributed: a mind is made of nodes, and each node supervises codelet processes, a server, and optional Redis memory. For local applications, `Mind` gives you the same conceptual structure in one Python process.

```python
import dct
from dct.codelets import PythonCodelet


class Writer(PythonCodelet):
    def proc(self, activation: float) -> None:
        dct.set_memory_objects_by_name(
            str(self.root_codelet_dir),
            "workspace",
            "value",
            "hello",
            "outputs",
        )


mind = dct.Mind(base_dir="./standalone-mind")
mind.add_memory("workspace", "json", initial_value={"value": None})
mind.add_codelet(Writer, outputs=["workspace"])
mind.run(steps=1)
```

Supported standalone memory types:

- `json`, stored as local JSON files. This is normalized internally to DCT's existing `local` memory type.
- `local`, equivalent to `json`.
- `redis`, using `host:port` memory locations.
- `mongo`, using MongoDB connection strings.

By default, standalone Redis memories point to `127.0.0.1:6379`. You can ask `Mind` to start a Redis subprocess:

```python
mind = dct.Mind(start_redis=True, redis_port=6380)
mind.add_memory("workspace", "redis")
mind.start()

# run your app

mind.stop()
```

For deterministic tests or scripts, prefer:

```python
mind.run_once()
mind.run(steps=10)
```

For long-running codelets, use:

```python
mind.start()
mind.stop()
```

## Memory Helpers

Local JSON memory:

```python
import dct

memory = dct.get_local_memory("/path/to/memories", "working_memory")
dct.set_local_memory("/path/to/memories", "working_memory", "value", {"state": "updated"})
```

Generic memory access:

```python
memory = dct.get_memory_object("working_memory", "/path/to/memories", "local")
dct.set_memory_object("working_memory", "/path/to/memories", "local", "value", 42)
```

Supported connection types are:

- `local`
- `redis`
- `mongo`
- `tcp`

## Server

The server exposes HTTP endpoints for node metadata, codelet metadata, memory reads/writes, and idea reads/writes.

Run it with:

```bash
python -m pip install "dct-python[server]"
ROOT_NODE_DIR=/path/to/node python -m dct.server 127.0.0.1:5000
```

Common endpoints:

- `GET /get_node_info`
- `GET /get_codelet_info/<codelet_name>`
- `GET /get_memory/<memory_name>`
- `POST /set_memory/`
- `GET /get_idea/<idea_name>`
- `POST /set_idea/`

## Utilities

`dct/utils.py` includes helper commands for Docker-backed nodes and network drawings.

Install visualization dependencies before using network drawing:

```bash
python -m pip install "dct-python[viz]"
```

Show the available options:

```bash
python dct/utils.py --help
```

Example network drawing:

```bash
python dct/utils.py --option draw-network --list-of-nodes 127.0.0.1:9998,127.0.0.1:9997
```

## Tests

The test suite uses Python's standard `unittest` runner, so it does not require pytest.

Run all tests:

```bash
python -m unittest discover -v
```

Run a syntax check:

```bash
python -m compileall dct tests
```

## Build and Publish

Install publishing tools:

```bash
python -m pip install ".[publish]"
```

Build the source distribution and wheel:

```bash
python -m build
```

Check the built distributions:

```bash
python -m twine check dist/*
```

Upload to TestPyPI first:

```bash
python -m twine upload --repository testpypi dist/*
```

Install from TestPyPI in a clean environment:

```bash
python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ dct-python
```

Upload to PyPI:

```bash
python -m twine upload dist/*
```

Before each release, update `__version__` in `dct/__init__.py`; the build metadata reads the package version from there.

## Development Notes

This package is still alpha software. Some runtime integrations depend on external services:

- Redis-backed memories require a running Redis server.
- Mongo-backed memories require a running MongoDB server.
- HTTP/TCP memory access requires a running DCT node server.
- Docker node utilities require Docker and the expected DCT node scripts/images.

Keep changes covered by tests where possible, especially for codelet field handling, memory helpers, and server request parsing.
