DOCSEARCHbyAlgolia
Submit Docs

MASFactory

repository·main·Indexed 19 days ago

https://github.com/bupt-gamma/masfactory

A graph-centric framework for orchestrating LLM-based multi-agent systems (MAS) using Vibe Graphing. Version 1.0.4 provides Declarative, Imperative, and Vibe Graphing development modes with unified runtime tracing. The framework includes ports for AgentVerse, CAMEL, and ChatDev Lite, as well as a Browser Game Agent application for designing, coding, and testing browser games via a multi-agent pipeline.

Tokens
102.5K
Snippets
234
Records
364
Agent score
65%

What's inside masfactory

  1. Overview of OhNoPPT

    main

    OhNoPPT is a MASFactory-based application designed to convert research papers into editable .pptx presentation decks.

    Unlike static slide exporters, OhNoPPT uses a multi-agent pipeline that includes human-in-the-loop review stages. The workflow follows three main stages:

    1. Outline Generation: Converts requirements into a slide outline.
    2. HTML Slide Generation: Converts the outline into HTML and a validation PDF.
    3. PPTX Reconstruction: Reconstructs the PDF content into an editable .pptx file using python-pptx.

    Users can inspect intermediate results and request revisions at each stage, making the process highly controllable for research talks and project demos.

  2. Overview of CAMEL application structure

    main

    The CAMEL port within MASFactory is organized into the following functional components:

    • main.py: The CLI entry point.
    • workflow.py: Defines the graph builder for the role-playing workflow.
    • conversation_loop.py: Implements the core logic for the multi-turn conversation.
    • prompts.py: Contains role definitions and prompt templates.
    • result_writer.py: Handles saving the conversation or task results.
    • eval/: Contains general evaluation helpers.
    • Benchmark Directories: Specific directories for running evaluations on benchmarks including gaia/, gpqa/, mmlu-pro/, mbpp/, livecodebench/, bigcodebench/, and commongen/.

  3. Overview of MASFactory

    main

    MASFactory is a graph-centric framework designed for orchestrating Multi-Agent Systems (MAS). It focuses on bridging the gap between natural-language intent and executable workflows through a concept called Vibe Graphing.

    Key capabilities include:

    • Vibe Graphing: Designing and iterating on multi-agent systems through AI-driven dialogue, moving from high-level intent to executable structures.
    • Graph-Based Composition: Using graphs as the primary unit of composition, allowing developers to package common flows as reusable structural units and encapsulate subgraphs as nodes.
    • Visualization & Debugging: Utilizing the MASFactory Visualizer to preview system topology and trace runtime behavior for white-box debugging.
    • Context Protocol Adapters: Providing a unified model for managing multi-source context (memory, retrieval, external knowledge, and tool results) to ensure context is controllable and traceable.

  4. Features of MASFactory Visualizer

    main

    The Visualizer supports several modes of interaction:

    • Graph Preview: Real-time visualization of Python (.py) workflow code.
    • Vibe Mode: Preview and edit .aml workflow documents (also supports legacy graph_design*.json files).
    • AML Source Preview: Syntax highlighting for AML files within the VS Code editor.
    • Run/Debug Session View: Inspect execution state, node details, and edge transitions during a live session.
    • Human-in-the-loop: View per-session conversation history via popups.
    • Customization: Configure custom graph colors via extension settings.

  6. ChatDev Application Layout

    main

    The ChatDev port is organized into the following functional areas:

    • assets/config/: Contains JSON configurations for ChatChains, Phases, and Roles (ChatChainConfig.json, PhaseConfig.json, RoleConfig.json).
    • assets/output/WareHouse/: Stores the output of completed runs.
    • chatdev/: Contains helper modules for managing code, documents, and utilities.
    • components/: Contains the implementation of individual phases and composed-phase nodes.
    • workflow/: The core execution logic, including the main entry point (main.py), handlers for workspace/log management, and configuration loading utilities.

  7. HuggingGPT2 Project Layout

    main

    The HuggingGPT2 application structure is organized as follows:

    • main.py: The CLI entry point.
    • workflow.py: Defines the graph builder logic.
    • config.yaml: Runtime configuration (model routing, endpoints, logging).
    • prompts.py: Contains system prompts.
    • adapters/: Contains model and tool adapters (supporting local, HuggingFace, or selector modes).
    • components/: Core logic for task parsing, model choosing, execution, and response generation.
    • demos/: Demo assets.
    • result_writer.py: Handles saving results.

  8. MASFactory Visualizer feature overview

    main

    The Visualizer provides four primary functional modes:

    • Preview: Inspects the graph topology parsed from Python or JSON files, including complex structures like subgraphs, loops, and switches.
    • Vibe: Specifically for VibeGraphing iterations, this mode allows you to preview and edit .aml workflows (includes legacy graph-design preview support).
    • Run / Debug: Provides runtime observability by tracking node states, message events, and errors during execution.
    • Human-in-the-loop: Enables interaction with the running process, allowing the user to receive requests (via chat or file preview/edit) and send replies back to the workflow.

  9. Understand the MetaGPT application layout

    main

    The MetaGPT port is organized as follows:

    • software_company/components.py: Contains Agent and node implementations.
    • software_company/dev_loop.py: Implements the DevLoop (the iterative development, testing, and fixing cycle).
    • software_company/run.py: The main entrypoint for running a single task.
    • software_company/software_company.py: The root Graph factory.
    • software_company/tools.py: Workspace helper tools.
    • software_company/projects/: Directory where run outputs are stored, organized by the --name provided at runtime.

  10. Configure selectors and path_filters for template scopes

    main

    When using template_defaults_for or template_overrides_for, you use a selector to target specific NodeTemplate declarations.

    Selector Components

    • type_filter: Uses issubclass semantics to match the template class.
    • name_filter: Matches the declaration name (exact, case-sensitive). Can accept a callable or regex-like object.
    • predicate: A callable receiving SelectionTarget(name, cls, obj=None). Note that obj is always None during template materialization.

    Path Filtering

    path_filter allows you to scope matches by the node's creation path to disambiguate nested nodes with the same name.

    Path Syntax: segment > segment > ...

    • segment: A concrete name (letters, digits, _, -).
    • *: Matches exactly one segment.
    • **: Matches zero or more segments.

    Note: Matching is "anywhere" by default (implicitly wrapped in **).

    Examples:

    • name_filter="instructor": Targets all nodes named instructor.
    • path_filter="demand_analysis>instructor": Targets only the instructor node inside the demand_analysis subgraph.

  11. Use NodeTemplate for reusable node configurations

    main

    A NodeTemplate is a declarative configuration that captures a node constructor (like Agent, Loop, or Switch) and its keyword arguments. It is not a node instance itself, but a blueprint that the graph materializes into concrete nodes during assembly.

    Key Characteristics:

    • Reusable: Use the same template across multiple graphs or subgraphs.
    • Derivable: Create new templates by overriding specific arguments from an existing one.

    Constraints:

    • NodeTemplate(...) accepts keyword arguments only.
    • It does not accept a name= argument; node names are determined by the graph during assembly (either in the nodes list or via g.create_node).
    from masfactory import RootGraph, Agent, OpenAIModel, NodeTemplate

model = OpenAIModel(model_name="gpt-4o-mini", api_key="...", base_url="...")

# Define a reusable template
BaseAgent = NodeTemplate(Agent, model=model)

g = RootGraph(
    name="demo",
    nodes=[
        ("assistant", BaseAgent(instructions="You are the Assistant.", prompt_template="Input: {x}")),
        ("instructor", BaseAgent(instructions="You are the Instructor.", prompt_template="Input: {x}\nDraft: {draft}")),
    ],
    edges=[
        ("ENTRY", "assistant", {"x": "input"}),
        ("assistant", "instructor", {"x": "input", "draft": "draft"}),
        ("instructor", "EXIT", {"plan": "final plan"}),
    ],
)

g.build()

  12. Understand the app_runtime Shared Dependencies

    main

    The app_runtime object, located in ddo/runtime/app_runtime.py, holds static dependencies that are shared across all cases in an experiment.

    Shared keys in app_runtime include:

    • cfg: Configuration settings.
    • dataset_ctx: Dataset context.
    • client: API client.
    • model: The LLM model (e.g., gpt-4o-mini).
    • sampler: Sampler instance.
    • base_agent: Base agent configuration.
    • token_usage: Tracking for token consumption.

    Note: To prevent cross-case contamination, individual case states, interaction records, and experiment summary results are not stored in app_runtime.