omoika 2.1.1

The Omoika plugins framework for graph-based information analysis and offline local-first investigative workflows.

Introducing the OMOIKA framework

I have no data yet. It is a capital mistake to theorize before one has data. Insensibly one begins to twist facts to suit theories, instead of theories to suit facts.

---

The OMOIKA Plugins Framework

This is the plugin framework for OMOIKA, a graph-based OSINT platform for recon, OSINT investigations, link analysis, and more. Offline. Local-first workflows. No cloud dependency required.

Overview

OMOIKA's plugin system enables you to define entities (nodes in the graph) and transforms (operations that create new entities from existing ones). The framework provides:

• Entity definitions with rich metadata, icons, colors, and form elements
• Transform decorators with dependency management and version targeting
• Result types for subgraphs, custom edges, and file attachments
• Field types for semantic type-based transform matching
• Settings framework for persistent configuration
• CLI tools for development and integration

Installation

pip install omoika[all]

For development:

git clone https://github.com/omoika-institute/framework.git
cd framework/
pip install -e ".[dev]"

Quick Start

Define an Entity

from omoika import Plugin
from omoika.elements import TextInput, CopyText
from omoika.types import FieldType

class EmailEntity(Plugin):
    version = "1.0.0"
    label = "Email"
    icon = "mail"
    color = "#3B82F6"
    category = "Identity"

    elements = [
        TextInput(label="Email", icon="mail", field_type=FieldType.EMAIL),
        CopyText(label="Domain"),
    ]

Create a Transform

from omoika import transform, Entity, Edge

@transform(
    target="email@>=1.0.0",
    label="Extract Domain",
    icon="world",
)
async def extract_domain(entity):
    email = entity.email
    domain = email.split("@")[1] if "@" in email else None

    if domain:
        return Entity(
            data=DomainEntity.blueprint(domain=domain),
            edge=Edge(label="has domain"),
        )

Run a Transform

ob run -T '{"label": "email", "version": "1.0.0", "transform": "extract_domain", "data": {"email": "[e-mail]"}}'

Documentation

Guide	Description
Getting Started	Installation, project setup, and first plugin
Plugins & Entities	Defining entities with the Plugin class
Transforms	Creating transforms with the @transform decorator
Elements	Input and display elements for entity forms
Field Types	Semantic types for fields and type-based matching
Settings	Transform configuration and persistence
CLI Reference	Command-line interface documentation
API Reference	Complete API documentation

Key Concepts

Plugins & Entities

Every node type in the graph is defined as a Plugin subclass. Plugins are automatically registered when defined:

class IPAddress(Plugin):
    version = "1.0.0"
    label = "IP Address"
    elements = [TextInput(label="IP", field_type=FieldType.IP_ADDRESS)]

Transforms

Transforms operate on entities to produce new entities. They target specific entity versions:

@transform(target="ip_address@>=1.0.0", label="GeoIP Lookup", deps=["geoip2"])
async def geoip_lookup(entity):
    # Transform logic
    return Entity(data=Location.blueprint(city="..."))

Result Types

Transforms return Entity, Edge, File, or Subgraph objects:

return Entity(
    data=TargetEntity.blueprint(field="value"),
    edge=Edge(label="discovered", color="#22C55E"),
    files=[File(path="/tmp/report.pdf")],
)

Project Structure

For plugin development and registry submissions, organize your code as:

my-plugins-repo/
├── entities/
│   ├── email.py
│   ├── domain.py
│   └── ip_address.py
└── transforms/
    ├── email_transforms.py
    ├── domain_transforms.py
    ├── network_traceroute_transform.py
    └── network_transforms.py

Load plugins via:

from omoika import load_plugins_fs
load_plugins_fs("/path/to/my-plugins", "my_plugins")

CLI Commands

# List entities and transforms
ob ls entities
ob ls transforms -L email

# Run a transform
ob transform '{"label": "email", "version": "1.0.0", "transform": "to_domain", "data": {...}}'

# Get entity blueprints
ob blueprints -L email

# Initialize a new plugins project
ob init

# Sync manifest and README metadata after repo changes
ob sync

# Compile JSON entity to Python
ob compile entity.json -O entity.py

Requirements

• Python 3.13+

License

MIT License, see LICENSE for details.

Links

• Documentation
• OMOIKA Application
• Issue Tracker