achemdb

README

AchemDB

An artificial chemistry database – transform data through reactive patterns instead of queries.

---

What is AchemDB?

AchemDB is a Go library and server that implements an artificial chemistry database – a novel approach to data processing inspired by chemical reactions. Instead of traditional database queries, data entities (molecules) interact through reactions that transform them based on patterns, rates, and environmental conditions.

• Reactive data processing – Molecules transform through reactions over discrete time steps
• Pattern detection – Reactions match molecules by species and conditions, enabling complex correlation
• Probabilistic behavior – Reactions fire with configurable rates, creating natural variability
• Event-driven notifications – Get notified when reactions fire, no polling required

Perfect for: security alert systems, anomaly detection, event correlation, complex state machines, and reactive data pipelines.

---

Installation

Go Package

go get github.com/daniacca/achemdb

Server Binary

go install github.com/daniacca/achemdb/cmd/achemdb-server@latest

---

Quickstart

Minimal Example

Here's a simple example using the Go client:

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/daniacca/achemdb/pkg/client"
)

func main() {
	// Create a schema with species and reactions
	schema := client.NewSchema("security-alerts").
		Species("Event", "Raw events", nil).
		Species("Suspicion", "Suspicious entities", nil).
		Reaction(client.NewReaction("login_failure_to_suspicion").
			Input("Event", client.WhereEq("type", "login_failed")).
			Rate(1.0).
			Effect(
				client.Consume(),
				client.Create("Suspicion").
					Payload("ip", client.Ref("m.ip")).
					Energy(1.0),
			),
		)

	// Apply schema to server
	ctx := context.Background()
	if err := client.ApplySchema(ctx, "http://localhost:8080", "production", schema); err != nil {
		log.Fatal(err)
	}

	fmt.Println("Schema applied successfully!")
}

Server Installation

From Source

go install github.com/daniacca/achemdb/cmd/achemdb-server@latest

Docker

You can run AChemDB as a standalone server using the official Docker image:

docker run -p 8080:8080 kaelisra/achemdb:latest

For advanced configuration (env vars, snapshots, docker-compose examples), see docs/docker.md.

1. Start the server

achemdb-server
# Server listening on :8080

2. Create a schema

curl -X POST http://localhost:8080/env/production/schema \
  -H "Content-Type: application/json" \
  -d '{
    "name": "security-alerts",
    "species": [
      {"name": "Event", "description": "Raw events"},
      {"name": "Suspicion", "description": "Suspicious entities"},
      {"name": "Alert", "description": "Alerts"}
    ],
    "reactions": [
      {
        "id": "login_failure_to_suspicion",
        "name": "Promote login failures",
        "input": {
          "species": "Event",
          "where": {"type": {"eq": "login_failed"}}
        },
        "rate": 1.0,
        "effects": [
          {"consume": true},
          {
            "create": {
              "species": "Suspicion",
              "payload": {"ip": "$m.ip"},
              "energy": 1.0
            }
          }
        ]
      }
    ]
  }'

3. Insert a molecule

curl -X POST http://localhost:8080/env/production/molecule \
  -H "Content-Type: application/json" \
  -d '{"species": "Event", "payload": {"type": "login_failed", "ip": "1.2.3.4"}}'

4. Run a tick

curl -X POST http://localhost:8080/env/production/tick

The reaction will fire, consuming the Event and creating a Suspicion molecule. Check results:

curl http://localhost:8080/env/production/molecules

---

Core Concepts

Molecules

Data entities with species, payload, energy, stability, and timestamps. Molecules are created, consumed, and transformed by reactions.

Reactions & DSL

Reactions define how molecules transform. Use the JSON DSL to define:

• Input patterns (species + conditions)
• Probabilistic rates
• Effects (consume, create, update, conditional logic)
• Catalysts (rate boosters)
• Partners (multi-molecule reactions)

Notifications

Get real-time notifications when reactions fire via webhooks or WebSocket. No polling needed.

Environments

Isolated containers for molecules and reactions. Each environment has its own schema, molecules, and time. Multiple environments can run on a single server.

---

Usage as Go Package

AchemDB can also be used as a Go library:

import "github.com/daniacca/achemdb/internal/achem"

schema := achem.NewSchema("my-system").WithSpecies(
    achem.Species{Name: "Event", Description: "Events"},
).WithReactions(...)

env := achem.NewEnvironment(schema)
env.Insert(achem.NewMolecule("Event", map[string]any{"type": "login_failed"}, 0))
env.Step()

See Core Concepts for more details on the Go API.

---

Client Package

Use the fluent Go client to build schemas programmatically:

import "github.com/daniacca/achemdb/pkg/client"

schema := client.NewSchema("security-alerts").
    Species("Event", "Raw events", nil).
    Reaction(client.NewReaction("login_failure_to_suspicion").
        Input("Event", client.WhereEq("type", "login_failed")).
        Rate(1.0).
        Effect(
            client.Consume(),
            client.Create("Suspicion").
                Payload("ip", client.Ref("m.ip")),
        ),
    )

err := client.ApplySchema(ctx, "http://localhost:8080", "production", schema)

See the DSL Reference for the equivalent JSON structure.

---

Requirements

• Go 1.25.4 or later

Run Demo

cd cmd/demo
go run .

---

Documentation

• Overview – High-level architecture, use cases, and design philosophy
• Core Concepts – Deep dive into molecules, reactions, environments, and notifications
• DSL Reference – Complete JSON schema and reaction syntax
• HTTP API – All endpoints, request/response formats, and examples
• Notifications – Notification system, event format, and notifier configuration
• Persistence – Design for snapshots and persistence (planned)

---

Special thanks to Francesco Cacciante and his book for inspiring this works.