omega_architecture 0.0.5

A reactive, agent-based architecture framework for Flutter applications.

Ω Omega Architecture

A reactive, agent-based architecture framework for Flutter applications.

Features

• Reactive Agents — Autonomous entities that react to system events and direct messages.
• Behavior Engine — Decoupled logic using rules and conditions to determine agent reactions.
• Event-Driven — Global communication through OmegaChannel.
• Flow Management — Orchestrate complex state transitions and business logic flows; run one or multiple flows at once.
• Semantic Intents — High-level abstraction for user or system requests.
• CLI — Scaffold setup and generate ecosystems (agent, flow, behavior, page) from the command line.

Core Concepts

Concept	Description
OmegaAgent	Building block of the architecture. Has an ID, a channel, and a behavior engine.
OmegaAgentBehaviorEngine	Evaluates events/intents and returns reactions (actions to run).
OmegaChannel	Event bus. Agents and flows subscribe to events and use emit() to publish.
OmegaFlow	Business flow with states (idle, running, paused, etc.). Orchestrates UI and agents.
OmegaFlowManager	Registers flows, routes intents to running flows, and activates/pauses them.

Getting Started

Add the dependency to your pubspec.yaml:

dependencies:
  omega_architecture: ^0.0.5

Omega CLI

The CLI helps you bootstrap Omega in your app and generate new ecosystems.

How to run

From a project that depends on omega_architecture:

dart run omega_architecture:omega <command> [options] [arguments]

Or by path (from the omega_architecture repo):

dart run bin/omega.dart <command> [options] [arguments]

Important: The CLI runs in your app’s project (the host app that depends on omega_architecture). It uses the current directory to find your project root. omega init creates lib/omega/omega_setup.dart in your app. omega g ecosystem creates the ecosystem files in the directory where you open the terminal (current working directory), then finds omega_setup.dart in your project and registers the new agent and flow there. You own the setup and add your own routes.

Commands

Command	Description
init [--force]	Creates lib/omega/omega_setup.dart in your app with an empty OmegaConfig (agents, flows, routes). Use --force to overwrite if it already exists. Run from your app root (where pubspec.yaml is).
g ecosystem <Name>	Generates agent, flow, behavior and page in the current directory (where you run the command). Finds lib/omega/omega_setup.dart in your project and registers the new agent and flow (refreshes imports and adds the flow to OmegaConfig; if flows: is missing, it is added). Run omega init first.

How g ecosystem uses omega_setup

When you run omega g ecosystem <Name> from your host app:

1. The CLI resolves your project root (directory that contains pubspec.yaml).
2. It looks for lib/omega/omega_setup.dart in that project. If it doesn’t exist, it prints "Run 'omega init' first" and does not create any files.
3. It creates the ecosystem files (agent, flow, behavior, page) in the current directory (the folder where you opened the terminal).
4. It updates omega_setup.dart: removes any existing imports for that ecosystem and adds the new imports (package or relative path depending on location). It registers the agent and flow in OmegaConfig; if the file has no flows: section, it adds it with the new flow.

Aliases: generate and create are equivalent to g.

Global options

Option	Description
-h, --help	Show help.
-v, --version	Show CLI version.

Examples

# First-time setup
dart run omega_architecture:omega init

# Overwrite existing setup
dart run omega_architecture:omega init --force

# Generate an ecosystem (e.g. Auth, Orders, Profile)
dart run omega_architecture:omega g ecosystem Auth
dart run omega_architecture:omega generate ecosystem Orders

Generated by omega g ecosystem Auth (in the directory where you run the command):

• auth/auth_agent.dart, auth/auth_flow.dart, auth/auth_behavior.dart
• auth/ui/auth_page.dart
• Updates to lib/omega/omega_setup.dart: the CLI finds this file in your app, refreshes the imports for this ecosystem (correct path), and registers the new agent and flow in OmegaConfig (adds flows: if it was missing).

Usage

Agent and behavior

class MyBehavior extends OmegaAgentBehaviorEngine {
  @override
  OmegaAgentReaction? evaluate(OmegaAgentBehaviorContext ctx) {
    if (ctx.event?.name == "greet") {
      return const OmegaAgentReaction("sayHello", payload: "Welcome!");
    }
    return null;
  }
}

class MyAgent extends OmegaAgent {
  MyAgent(OmegaChannel channel)
      : super(id: "my_agent", channel: channel, behavior: MyBehavior());

  @override
  void onMessage(OmegaAgentMessage msg) {}

  @override
  void onAction(String action, dynamic payload) {
    if (action == "sayHello") print(payload);
  }
}

void main() {
  final channel = OmegaChannel();
  final agent = MyAgent(channel);
  channel.emit(const OmegaEvent(id: "1", name: "greet"));
}

Flutter: OmegaScope and OmegaBuilder

Wrap your app with OmegaScope to provide OmegaChannel and OmegaFlowManager:

OmegaScope(
  channel: myChannel,
  flowManager: myFlowManager,
  child: MyApp(),
)

Use OmegaBuilder to rebuild UI when specific events occur:

OmegaBuilder(
  eventName: 'user.updated',
  builder: (context, event) {
    return Text('User: ${event?.payload['name']}');
  },
)

Activating flows

• Several flows at once: use flowManager.activate("flowId") for each. All stay in running and receive intents via handleIntent.
• Single “main” flow: use flowManager.switchTo("flowId") to activate one and pause the others.

Lifecycle and dispose

• OmegaChannel — Whoever creates it should call channel.dispose() when the app is shutting down.
• OmegaFlowManager — Call flowManager.dispose() to cancel the subscription used by wireNavigator.
• OmegaAgent — Call agent.dispose() so the agent unsubscribes from the channel.
• OmegaScope does not dispose anything; the widget that creates channel and flowManager should call their dispose() in its State.dispose.

Example: Authentication flow

A full example lives under lib/examples/ and shows:

1. UI — Login screen that emits intents.
2. Flow — Orchestrates login, navigation, and UI expressions.
3. Agent — Performs login logic and emits success/error events.
4. Behavior — Rules and reactions for the auth agent.

Relevant files:

• Main setup
• Auth flow
• Login page

Project structure

lib/
├── omega/
│   ├── core/          # Channel, events, intents, types
│   ├── agents/        # OmegaAgent, behavior engine, protocol
│   ├── flows/         # OmegaFlow, OmegaFlowManager, expressions
│   ├── ui/            # OmegaScope, OmegaBuilder, navigation
│   └── bootstrap/     # Config, runtime
├── examples/          # Full examples and feature demos
└── omega_architecture.dart  # Barrel exports

License

See LICENSE.