MeTTa-KG

https://deepfunding.ai/proposal/scalable-metta-knowledge-graphs/

This README is WIP and is subject to change.

Installation

Prerequisites

• Docker and Docker Compose
• Node.js 22

Setup

1. Clone the repository:

   git clone https://github.com/your-repo/MeTTa-KG.git
   cd MeTTa-KG

2. Copy environment variables (if needed):

   • Create a .env file based on required variables (see docker-compose.yml for reference)

3. Build and run with Docker Compose:

   docker-compose up --build

This will start the API, database, Mork server, and Adminer for database management.

Running Locally

Using Docker Compose (Recommended)

docker-compose up

• API: http://localhost:8000 (or configured port)
• Frontend: Served via Vite dev server (run separately if needed)
• Adminer: http://localhost:8080
• Mork: http://localhost:8001

Manual Setup

1. Database: Start PostgreSQL
2. Mork: Build and run the Mork server (see Dockerfile.mork). you can also run it from the official Mork repo (https://github.com/trueagi-io/MORK)
3. Backend:

   cd api
   cargo run

4. Frontend:

   cd frontend
   npm install
   npm run dev

Usage

Spaces

A Knowledge Graph (KG) corresponds to a hierarchy of spaces. Each space has a name, which we refer to as its namespace. The root space is identified by the "/" namespace, while its direct subspaces (spaces on the second level of the hierachy) are identified by namespaces such as "/subspace1/", and so on.

Namespaces are similar to filesystem paths, especially when viewed as a tree. In this view, the difference is that for namespaces, interior nodes play the same role as leaf nodes, while their roles differ in the case of a filesystem path. In particular, every namespace in the hierachy identifies a space. Moreover, namespaces are never "terminal", meaning that it is always possible to embed subspaces further.

Spaces support two operations, read and write. As the name suggests, a read operation on a space provides a read-only view of that space. A write operation works by applying some transformations to the space, creating a new space in the process and preserving the original space. The newly created space is embedded into the space the write operation was used on.

Namespace Rules

A namespace should:

• start with '/'
• end with '/'
• consist of segments separated by '/' that:
  • contain only alphanumeric characters, '-', '_'
  • start with an alphanumeric character
  • end with an alphanumeric character

Tokens

Tokens give access to spaces in the KG by linking to their namespaces. A token has a number of associated permissions:

• read: allow read-only viewing of the space
• write: allow write operations on the space
• share-read: allow creation of a new token with the 'read' permission on the same space
• share-write: allow creation of a new token with the 'write' permission on the same space

There exists a single "admin" token. It is associated with the root namespace / and has a special permission named share-share. The root token can be refreshed (= regenerated), but can not be deleted.

Warning

Operations are recursive. For example, tokens with the write permission for a namespace /space/ can be used to write in /space/subspace/, /space/subspace/another-subspace/.

Existing tokens can be used to create new ones, provided they have any of the share permissions listed above.

Warning

Deleting a token also deletes any tokens that were created from it, recursively.

It is currently not possible to modify an existing token's namespace, description, or permissions. Tokens can be refreshed if leaked by accident.

Tokens are managed on the /tokens page (Demo).

Editor

The editor allows you to interact with the contents of the KG using the MeTTa language.

The editor can be found on the / page (Demo).

Translations

Documentation on translations can be found here.

Development

Frontend

• npm run dev: Start development server
• npm run build: Build for production
• npm run lint: Run ESLint
• npm run prettier: Format code

Backend

• cargo run: Start the API server
• cargo test: Run tests

Contributing

Database Workflow

Prerequisites

• Install the Diesel CLI: cargo install diesel_cli --no-default-features --features postgres.

Schema Changes

• Generate Migration: cd api && diesel migration generate <migration_name> (e.g., add_user_table).
• Edit Migration Files: Modify up.sql (forward changes) and down.sql (rollback) in the new api/migrations/<timestamp>_<name>/ folder.
• Apply Migration: Run the app (cargo run or docker-compose up); migrations execute automatically on startup.
• Verify: Check app logs for migration success. Use Adminer (http://localhost:8080) to inspect the DB.
• Rollback: diesel migration revert (reverts the last migration), then restart the app.

Seeding Data

• Edit the existing seed migration (api/migrations/2024-08-13-154617_seed/up.sql) or generate a new migration for additional data.
• Add INSERT statements in up.sql.
• Restart the app to apply seeds.

Testing DB Changes

• Unit Tests: cargo test (runs with embedded migrations).
• Integration Tests: cargo test --features integration-tests (requires a running DB instance).
• Docker Tests: docker-compose up --build for full-stack testing.

Production Deployment

• Migrations are embedded in the release binary (cargo build --release).
• On deployment, the app runs migrations automatically—no manual steps needed.

Best Practices

• Always use migrations for schema changes to maintain version control.
• Commit migration files to Git; never modify existing migrations directly.
• Backup the DB before applying major changes.
• Use Adminer for DB inspection and manual queries during development.