core

README

core

Overview

Core is a collection of software to enable "agents" to communicate and share data via a "blackboard".

More technically, Core is first and foremost a protocol for distributed multi-agent systems. We also aim to provide high quality reference implementations of client APIs and backend resources usable for others.

The core tool is the only entrypoint we officially support to these resources. The main build process (make install) builds the core tool binary. Which is our universal CLI to these resources.

Version 0.2.4

Version 0.2.4 rewrites much of the core protocol and broader project with different patterns that we think will be easier and more maintainable to work with going forward for both the core developers and people building applications on top of core.

Although the fundamental interaction patterns are the same, some aspect of pretty much everything has changed a little bit. We apologize and hope that this version of the protocol should be the protocol version for the foreseeable future.

We thank you in advance for your patience. Please utilize the issues if you have questions about porting your agents over to the new system. Using a public issue will allow others to also benefit from any debugging we can help provide.

Documentation and resources

• Top level README (this document) contains high-level instructions for getting started
• Agent API documentation (go, python)
• Full multi-agent system example (go, python)
• Blackboard chat agent (go, python)
• FAQ Issues
• Client API development (advanced users)
• Other examples: ping.go, pong.go, network_benchmark.go, agent_example.py

Support for our users

We aim to make core a useful tool/set of tools. It is also a research project and will thus, for now, be likely to experience breaking changes. We will aim to make this as non-disruptive as possible. We make no guarantees about pretty much anything (for now). At this time you are free to utilize this work in your own research.

To Install

For now, we only support installation via the go tool:

(easiest) Via go install:

go install gitlab.com/hoffman-lab/core@latest

A word of caution: using @latest will download the latest full release of core, however pre-release versions are ignored. For pre-release versions, please use the full tag e.g. @v0.2.4-rc3

go install gitlab.com/hoffman-lab/core@v0.2.4-rc3

To build from source:

git clone https://gitlab.com/hoffman-lab/core
cd core 
go install

Make sure that you've updated your system path to include the go install path. For linux/mac systems, ensure the following is in ~/.zshrc or ~/.bashrc

export PATH=$PATH:${HOME}/go/bin

Quickstart

Create a core project

Core projects require a lot of organization and configuration.

To help with this (hopefully... feedback welcome!) 0.2.4 introduces the concept of the core project to manage your agents and your project configuration.

mkdir test-project && cd test-project
core init

Configure the project

Use the core executable to manage your project configuration:

core config show
core config set blackboard.addr localhost:8080

We'll describe configuration of distributed systems elsewhere.

For now, we recommend utilizing the default localhost:8080.

The Blackboard HTTP server

core multiagent systems are built around a blackboard. The default blackboard makes itself available over the network as an HTTP service.

core start server

Start Some Agents

The source code for these agents can be found in cmd/agents/ and cmd.

core start ping &
core start pong

Multi-Agent System (MAS) mode (experimental)

Multi-agent systems mode (MAS mode) puts a "controller" in the drivers seat. A controller is an agent that handles the scheduling of other agents. We'll write more on this later.

core start mas slipnet slipnet-config.yaml

Core registries (new, experimental, probably should be avoided for now)

BE CAREFUL all the usual disclaimers about running software you found on the internet apply here. You should only run software you trust from known publishers. Better yet, check out each agent's code ahead of using it.

Agents should be ubiquitously available. Easy to get and easy to share. We now provide a hub-like registry for agents that you can pull from and push to:

core pull dicom-uploader 

You can also pull whole knowledge graphs, although this is still pretty experimental:

core pull emphysema-scoring-kg

So see the available agents and knowledge graphs you can pull from the current registry:

bash core registry ls

Finally, my hope is that everyone starts to run their own registries to have their "quiver" of agents to pull from for different tasks. To run your own registry:

core config set registry.addr <hostname:port or IP:port> 
core start
registry

Finally, when you have an agent ready to share, you can push your agent to the registry

core push <agent-dir-name> 

you can use tags to keep your agents organized and versioned:

core push <agent-dir-name>

The registry server

If you want to run your own registry server, please refer to the separate documentation.

Core Philosophies

Core is not a neutral project with some strong opinions about the right and wrong ways to do projects. They're not entirely useful for "getting started" style documentation, but they are important if you want to go deeper. They'll help you understand why the architecture is what it is and some of the problems we think might also be addressed by these choices. Check them out.

If you like to read more of the philosophical ramblings about what core really is, please head over to John's site

Key to the project are:

• Ease of use (we also build tools with core so we're heavily invested in making it easy and fast to use)
• Interoperability
• Networking and scalability
• Portability

Documentation

Overview

Copyright © 2024 NAME HERE <EMAIL ADDRESS>