Solutions¶

A solution is the top-level container in the Solution Builder. It groups related components into a single versioned, deployable unit that solves a specific business problem.

Creating a Solution¶

Every solution starts with a name, description, and a Mermaid diagram that describes the system architecture. The platform uses the diagram to auto-generate a component skeleton.

PythonUI

Coming Soon

The Python SDK for local development is not yet publicly available.

from flow_sdk.cli_client import CLIClient

client = CLIClient(config)

solution = client.solutions.create({
    "name": "Customer Support Automation",
    "description": "AI-powered ticket triage and response system",
    "mermaid_source": """
    graph TD
        Classifier["Ticket Classifier Agent"]
        Router["Routing Workflow"]
        Responder["Response Agent"]
        KB["Knowledge Base Tool"]

        Classifier --> Router
        Router --> Responder
        Responder --> KB
    """,
    "visibility_level": "workspace",
})

print(f"Solution created: {solution.id} (v{solution.version})")

Navigate to Solutions > New. Enter a name, description, and visibility level. Paste your Mermaid diagram into the architecture editor. Click Create.

Solution Structure¶

A solution contains metadata and a list of components:

{
  "id": "a1b2c3d4-...",
  "slug": "customer-support-automation",
  "version": "0.1.0",
  "name": "Customer Support Automation",
  "description": "AI-powered ticket triage and response system",
  "mermaid_source": "graph TD\n  ...",
  "status": "draft",
  "visibility_level": "workspace",
  "component_count": 4,
  "completed_count": 0
}

Key Fields¶

Field	Description
`slug`	URL-safe identifier that groups all versions of a solution together
`version`	Semantic version (`major.minor.patch`) starting at `0.1.0`
`status`	Lifecycle status: `draft`, `in_progress`, `completed`, `archived`
`visibility_level`	Access scope: `private`, `workspace`, `organization`, `marketplace`
`mermaid_source`	The Mermaid flowchart that defines the solution architecture
`component_count`	Total number of components in the skeleton
`completed_count`	Number of components that have been fully configured

Solution Lifecycle¶

Solutions move through a defined lifecycle from creation to deployment:

stateDiagram-v2
    [*] --> Draft: Create solution
    Draft --> InProgress: Start building
    InProgress --> Completed: All components done
    Completed --> Archived: Archive
    InProgress --> Draft: Reset
    Completed --> InProgress: Revise

    Draft: draft
    InProgress: in_progress
    Completed: completed
    Archived: archived

Status	Meaning
`draft`	Solution created, skeleton may or may not be generated
`in_progress`	Actively building -- at least one component is being worked on
`completed`	All components have been configured and are ready
`archived`	Solution is retired and no longer active

Versioning¶

Solutions use semantic versioning (major.minor.patch). Creating a new version copies the solution and its component skeleton, allowing you to iterate without affecting the previous version.

Coming Soon

The Python SDK for local development is not yet publicly available.

new_version = client.solutions.create_version(solution.id, {
    "version_increment": "minor",  # "major", "minor", or "patch"
    "mermaid_source": updated_mermaid,  # Optional: update the diagram
})

print(f"New version: {new_version.version}")  # e.g., "0.2.0"

Version Increment Rules¶

Increment	When to Use	Example
`patch`	Bug fixes, minor config tweaks	`0.1.0` -> `0.1.1`
`minor`	New components, feature additions	`0.1.0` -> `0.2.0`
`major`	Breaking changes, architecture redesign	`0.1.0` -> `1.0.0`

Versions share a slug

All versions of a solution share the same slug. This makes it easy to query the full version history of a solution and compare changes across versions.

Component Skeleton¶

When you create a solution with a Mermaid diagram, the platform generates a component skeleton -- a structured plan of every component that needs to be built.

Each skeleton entry includes:

Field	Description
`component_type`	Inferred type (`agent`, `workflow`, `codeblock`, `tool`, etc.)
`node_id`	The node identifier from the Mermaid diagram
`node_label`	The display label from the Mermaid diagram
`inferred_description`	AI-generated description of what this component should do
`inferred_dependencies`	List of other node IDs this component depends on
`creation_order`	Recommended build order (topologically sorted)
`status`	Component status: `pending`, `in_progress`, `completed`, `skipped`

Regenerating the Skeleton¶

If you update the Mermaid diagram, you can regenerate the skeleton:

Coming Soon

The Python SDK for local development is not yet publicly available.

# Add new nodes, keep completed components
client.solutions.regenerate_skeleton(solution.id, mode="add_new")

# Or start fresh
client.solutions.regenerate_skeleton(solution.id, mode="clear_and_rebuild")

Clear and rebuild

The clear_and_rebuild mode removes all existing skeleton entries, including completed ones. Use add_new if you want to preserve work already done.

Visibility Levels¶

Solutions support four visibility levels that control who can discover and use them:

Level	Access
`private`	Only the owner can see and edit
`workspace`	All members of the workspace
`organization`	All members of the organization
`marketplace`	Published to the marketplace for cross-organization sharing

Deploying Solutions¶

Once a solution is completed, deploy it through deployment rings. The platform packages all linked components and manages the deployment lifecycle.

Before deleting a solution, a preflight check verifies that no components have blocking external references. In the UI, click Action menu > Delete on any solution to see the preflight check with affected components listed before you confirm.

To review a solution's history programmatically:

Coming Soon

The Python SDK for local development is not yet publicly available.

history = client.solutions.get_history(solution.id)

for entry in history.items:
    print(f"v{entry.version} [{entry.status}] — {entry.component_count} components")

Managing Solutions¶

Listing Solutions¶

Coming Soon

The Python SDK for local development is not yet publicly available.

solutions = client.solutions.list(page=1, page_size=20)

for s in solutions.items:
    print(f"{s.name} v{s.version} [{s.status}] — {s.completed_count}/{s.component_count} components")

Updating a Solution¶

Coming Soon

The Python SDK for local development is not yet publicly available.

client.solutions.update(solution.id, {
    "name": "Customer Support Automation v2",
    "status": "in_progress",
})

Archiving a Solution¶

Coming Soon

The Python SDK for local development is not yet publicly available.

client.solutions.update(solution.id, {
    "status": "archived",
})