Workspace and Projects

This guide covers how to organize your models using workspaces and projects in the ViewAI platform.

Overview

ViewAI uses a hierarchical organization system:

• Workspaces: Top-level containers for organizing work by team, environment, or organization

• Projects: Sub-containers within workspaces for grouping related models

This structure helps you:

• Separate development, staging, and production environments

• Organize models by business domain or use case

• Control access and permissions

• Track model lineage and relationships

Quick Start

quickstart.py

from viewai_client import ViewAIClient

# Initialize client
client = ViewAIClient(api_key="your-api-key")

# List workspaces
workspaces = client.list_accessible_workspaces()
for ws in workspaces:
    print(f"{ws.workspace_name}: {ws.workspace_id}")

# Get default workspace
workspace = client.retrieve_default_workspace()

# Set current workspace
client.set_current_workspace(workspace)

# List projects in workspace
projects = client.list_accessible_projects(workspace_id=workspace.workspace_id)
for proj in projects:
    print(f"{proj.project_name}: {proj.project_id}")

Understanding Workspaces

What is a Workspace?

A workspace is a top-level container that provides:

• Isolation: Separate environments for different purposes

• Access Control: Team-based permissions and sharing

• Resource Organization: Group related projects and models

• Billing: Track usage and costs by workspace

Common Workspace Patterns

workspace_patterns.py

# Environment-based workspaces
development_ws = client.retrieve_workspace_by_name("development")
staging_ws = client.retrieve_workspace_by_name("staging")
production_ws = client.retrieve_workspace_by_name("production")

# Team-based workspaces
ml_team_ws = client.retrieve_workspace_by_name("ml-team")
data_science_ws = client.retrieve_workspace_by_name("data-science")

# Organization-based workspaces
company_a_ws = client.retrieve_workspace_by_name("company-a")
company_b_ws = client.retrieve_workspace_by_name("company-b")

Workspace Attributes

workspace_attributes.py

workspace = client.retrieve_default_workspace()

# Access workspace properties
print(f"Name: {workspace.workspace_name}")
print(f"ID: {workspace.workspace_id}")

# Workspace object representation
print(workspace)

# Output: Workspace(workspace_id='ws-123', workspace_name='production')

Understanding Projects

What is a Project?

A project is a sub-container within a workspace that provides:

• Model Grouping: Organize related models together

• Use Case Tracking: Group models by business problem

• Version Management: Track model iterations

• Collaboration: Share project context across team members

Common Project Patterns

project_patterns.py

# Get workspace
workspace = client.retrieve_workspace_by_name("production")

# Use case-based projects
churn_project = client.retrieve_project_by_name("customer-churn")
fraud_project = client.retrieve_project_by_name("fraud-detection")
recommendation_project = client.retrieve_project_by_name("recommendations")

# Domain-based projects
marketing_project = client.retrieve_project_by_name("marketing-analytics")
finance_project = client.retrieve_project_by_name("financial-models")
operations_project = client.retrieve_project_by_name("operations")

Project Attributes

project_attributes.py

project = client.retrieve_project_by_name("customer-churn")

# Access project properties
print(f"Name: {project.project_name}")
print(f"ID: {project.project_id}")

# Project object representation
print(project)

# Output: Project(project_id='proj-456', project_name='customer-churn')

Managing Workspaces

Listing Workspaces

list_workspaces.py

# List all accessible workspaces
workspaces = client.list_accessible_workspaces()

print(f"You have access to {len(workspaces)} workspaces:")
for ws in workspaces:
    print(f"  - {ws.workspace_name} (ID: {ws.workspace_id})")

# Using workspace manager service
workspaces = client.workspace_manager.list_accessible_workspaces()

Getting Default Workspace

default_workspace.py

# Get default workspace (first in user's list)
default_workspace = client.retrieve_default_workspace()

if default_workspace:
    print(f"Default workspace: {default_workspace.workspace_name}")
    print(f"ID: {default_workspace.workspace_id}")
else:
    print("No default workspace available")

Finding Workspaces by Name

find_workspace_by_name.py

# Retrieve specific workspace by name
workspace = client.retrieve_workspace_by_name("production")

if workspace:
    print(f"Found workspace: {workspace.workspace_id}")
else:
    print("Workspace 'production' not found")

# Using workspace manager service
workspace = client.workspace_manager.retrieve_workspace_by_name("production")

Finding Workspaces by ID

find_workspace_by_id.py

# Retrieve workspace by ID
workspace = client.workspace_manager.retrieve_workspace_by_id("ws-123abc")

if workspace:
    print(f"Found workspace: {workspace.workspace_name}")
else:
    print("Workspace not found")

Checking Workspace Existence

workspace_exists.py

# Check if workspace exists
exists = client.workspace_manager.workspace_exists("production")

if exists:
    print("Workspace exists")
    workspace = client.retrieve_workspace_by_name("production")
else:
    print("Workspace does not exist")

Counting Workspaces

count_workspaces.py

# Count accessible workspaces
count = client.workspace_manager.count_accessible_workspaces()
print(f"You have access to {count} workspaces")

Workspace Discovery Pattern

discover_workspaces.py

def discover_workspaces(client):
    """Discover and display all accessible workspaces."""
    workspaces = client.list_accessible_workspaces()

    print(f"{'='*60}")
    print(f"WORKSPACE DISCOVERY")
    print(f"{'='*60}")
    print(f"Found {len(workspaces)} workspaces:\n")

    for i, ws in enumerate(workspaces, 1):
        print(f"{i}. {ws.workspace_name}")
        print(f"   ID: {ws.workspace_id}")

        # Get projects in workspace
        projects = client.list_accessible_projects(
            workspace_id=ws.workspace_id
        )
        print(f"   Projects: {len(projects)}")

        if projects:
            for proj in projects[:3]:
                print(f"     - {proj.project_name}")
            if len(projects) > 3:
                print(f"     ... and {len(projects) - 3} more")
        print()

    return workspaces

# Use discovery function
workspaces = discover_workspaces(client)

Managing Projects

Listing Projects

list_projects.py

# List all accessible projects
projects = client.list_accessible_projects()

print(f"You have access to {len(projects)} projects:")
for proj in projects:
    print(f"  - {proj.project_name} (ID: {proj.project_id})")

# List projects in specific workspace
workspace = client.retrieve_workspace_by_name("production")
projects = client.list_accessible_projects(
    workspace_id=workspace.workspace_id
)

print(f"Projects in {workspace.workspace_name}:")
for proj in projects:
    print(f"  - {proj.project_name}")

Finding Projects by Name

find_project_by_name.py

# Retrieve specific project by name
project = client.retrieve_project_by_name("customer-churn")

if project:
    print(f"Found project: {project.project_id}")
else:
    print("Project 'customer-churn' not found")

# Using project manager service
project = client.project_manager.retrieve_project_by_name("customer-churn")

Finding Projects by ID

find_project_by_id.py

# Retrieve project by ID
project = client.project_manager.retrieve_project_by_id("proj-456abc")

if project:
    print(f"Found project: {project.project_name}")
else:
    print("Project not found")

Checking Project Existence

project_exists.py

# Check if project exists
exists = client.project_manager.project_exists("customer-churn")

if exists:
    print("Project exists")
    project = client.retrieve_project_by_name("customer-churn")
else:
    print("Project does not exist")

Counting Projects

count_projects.py

# Count all accessible projects
count = client.project_manager.count_accessible_projects()
print(f"You have access to {count} projects")

# Count projects in specific workspace
count = client.project_manager.count_accessible_projects(
    workspace_id="ws-123"
)
print(f"Workspace has {count} projects")

Searching Projects

search_projects.py

# Search for projects by name pattern (case-insensitive)
matching_projects = client.project_manager.search_projects_by_name_pattern("churn")

print(f"Found {len(matching_projects)} projects matching 'churn':")
for proj in matching_projects:
    print(f"  - {proj.project_name}")

Project Discovery Pattern

discover_projects.py

def discover_projects(client, workspace_id=None):
    """Discover and display all accessible projects."""
    projects = client.list_accessible_projects(workspace_id=workspace_id)

    print(f"{'='*60}")
    print(f"PROJECT DISCOVERY")
    print(f"{'='*60}")
    print(f"Found {len(projects)} projects:\n")

    for i, proj in enumerate(projects, 1):
        print(f"{i}. {proj.project_name}")
        print(f"   ID: {proj.project_id}")
        print()

    return projects

# Use discovery function
projects = discover_projects(client)

# Or discover projects in specific workspace
workspace = client.retrieve_workspace_by_name("production")
projects = discover_projects(client, workspace_id=workspace.workspace_id)

Context Management

Setting Current Workspace

Set a workspace as the current context for operations:

set_current_workspace.py

# Set current workspace by object
workspace = client.retrieve_workspace_by_name("production")
client.set_current_workspace(workspace)

# Or set by name (automatically retrieves workspace)
client.set_current_workspace("production")

# Now training jobs will use this workspace by default
job = client.initiate_training_job(
    dataset=df,
    target_column="churn",
    model_name="My Model"
    # workspace parameter not needed - uses current workspace
)

Setting Current Project

Set a project as the current context:

set_current_project.py

# Set current project by object
project = client.retrieve_project_by_name("customer-churn")
client.set_current_project(project)

# Or set by name
client.set_current_project("customer-churn")

# Now models can be associated with this project

Context Initialization

context_initialization.py

from viewai_client.config import ClientConfiguration

# Configure with default workspace
config = ClientConfiguration(
    api_key="your-api-key",
    default_workspace="production",
    default_project="customer-churn"
)

client = ViewAIClient(config=config)

# Workspace and project are automatically set
print(f"Current workspace: {client._current_workspace.workspace_name}")
print(f"Current project: {client._current_project.project_name}")

Context Switching Pattern

workspace_context.py

class WorkspaceContext:
    """Context manager for temporary workspace switching."""

    def __init__(self, client, workspace_name):
        self.client = client
        self.workspace_name = workspace_name
        self.original_workspace = None

    def __enter__(self):
        # Save current workspace
        self.original_workspace = self.client._current_workspace

        # Switch to new workspace
        workspace = self.client.retrieve_workspace_by_name(self.workspace_name)
        self.client.set_current_workspace(workspace)
        return workspace

    def __exit__(self, exc_type, exc_val, exc_tb):
        # Restore original workspace
        if self.original_workspace:
            self.client.set_current_workspace(self.original_workspace)

# Usage
with WorkspaceContext(client, "staging") as workspace:
    # Operations in staging workspace
    job = client.initiate_training_job(
        dataset=df,
        target_column="target",
        model_name="Staging Model"
    )

# Automatically switched back to original workspace

Organizing Models

Training Models in Workspace

Train models within a specific workspace:

train_in_workspace.py

# Get workspace
workspace = client.retrieve_workspace_by_name("production")

# Train model in workspace
job = client.initiate_training_job(
    dataset=df,
    target_column="churn",
    workspace=workspace,  # Explicit workspace
    model_name="Customer Churn Model"
)

# Or set workspace context first
client.set_current_workspace("production")

job = client.initiate_training_job(
    dataset=df,
    target_column="churn",
    model_name="Customer Churn Model"
    # Uses current workspace
)

Training Models in Project

Train models within a specific project:

train_in_project.py

# Get workspace and project
workspace = client.retrieve_workspace_by_name("production")
project = client.retrieve_project_by_name("customer-analytics")

# Train model in project
job = client.initiate_training_job(
    dataset=df,
    target_column="churn",
    workspace=workspace,
    project=project,  # Associate with project
    model_name="Churn Model v1.0"
)

Deploying Models in Workspace

Deploy models within a specific workspace:

deploy_in_workspace.py

from sklearn.ensemble import RandomForestClassifier

# Train model
model = RandomForestClassifier()
model.fit(X_train, y_train)

# Get workspace
workspace = client.retrieve_workspace_by_name("production")

# Deploy in workspace
deployable = client.create_deployable_model(
    model=model,
    dataset=train_df,
    target_column="target",
    model_name="RF Classifier",
    workspace=workspace  # Explicit workspace
)

dashboard_id = deployable.deploy()

Deploying Models in Project

Deploy models within a specific project:

deploy_in_project.py

# Get workspace and project
workspace = client.retrieve_workspace_by_name("production")
project = client.retrieve_project_by_name("fraud-detection")

# Deploy in project
deployable = client.create_deployable_model(
    model=model,
    dataset=train_df,
    target_column="target",
    model_name="Fraud Classifier v2.0",
    workspace=workspace,
    project=project  # Associate with project
)

dashboard_id = deployable.deploy()

Multi-Environment Deployment

Deploy the same model across multiple environments:

deploy_to_environments.py

def deploy_to_environments(model, train_df, target_column, model_name, environments):
    """Deploy model to multiple workspace environments."""
    deployments = {}

    for env_name in environments:
        print(f"\nDeploying to {env_name}...")

        workspace = client.retrieve_workspace_by_name(env_name)

        deployable = client.create_deployable_model(
            model=model,
            dataset=train_df,
            target_column=target_column,
            model_name=f"{model_name}_{env_name}",
            workspace=workspace
        )

        dashboard_id = deployable.deploy()
        deployments[env_name] = dashboard_id

        print(f"Deployed to {env_name}: {dashboard_id}")

    return deployments

# Deploy to dev, staging, and production
environments = ["development", "staging", "production"]
deployments = deploy_to_environments(
    model=model,
    train_df=train_df,
    target_column="target",
    model_name="MyModel_v1.0",
    environments=environments
)

Project-Based Model Organization

Organize models by project:

organize_by_project.py

def organize_by_project(client):
    """Organize and display models by project."""

    # Get workspace
    workspace = client.retrieve_workspace_by_name("production")

    # Get all projects
    projects = client.list_accessible_projects(
        workspace_id=workspace.workspace_id
    )

    print(f"Model Organization in {workspace.workspace_name}:\n")

    for project in projects:
        print(f"Project: {project.project_name}")
        print(f"  ID: {project.project_id}")

        # List models in project (using registry)
        try:
            models = client.registry.list_models(project_id=project.project_id)
            print(f"  Models: {len(models)}")

            for model in models[:3]:
                print(f"    - {model.model_name}")

            if len(models) > 3:
                print(f"    ... and {len(models) - 3} more")
        except:
            print(f"  Models: Unable to retrieve")

        print()

# Use organization function
organize_by_project(client)

Best Practices

1

Use Consistent Naming Conventions

Use clear, consistent names for workspaces and projects.

naming_conventions.py

# Good naming patterns
WORKSPACE_NAMES = {
    "dev": "development",
    "staging": "staging",
    "prod": "production"
}

PROJECT_NAMES = {
    "churn": "customer-churn-prediction",
    "fraud": "fraud-detection",
    "recommend": "product-recommendations"
}

# Get workspace with consistent naming
workspace = client.retrieve_workspace_by_name(WORKSPACE_NAMES["prod"])

2

Set Context Early

Set workspace and project context at the start of your script so subsequent operations use them by default.

set_context.py

# Set context once at initialization
client = ViewAIClient(api_key="your-api-key")

workspace = client.retrieve_workspace_by_name("production")
client.set_current_workspace(workspace)

project = client.retrieve_project_by_name("customer-analytics")
client.set_current_project(project)

# Now all operations use this context
job1 = client.initiate_training_job(...)
job2 = client.initiate_training_job(...)

3

Validate Workspace/Project Existence

Always validate existence before using to avoid runtime errors.

validate_existence.py

def get_workspace_or_fail(client, workspace_name):
    """Get workspace or raise error."""
    workspace = client.retrieve_workspace_by_name(workspace_name)

    if not workspace:
        raise ValueError(f"Workspace '{workspace_name}' not found")

    return workspace

def get_project_or_fail(client, project_name):
    """Get project or raise error."""
    project = client.retrieve_project_by_name(project_name)

    if not project:
        raise ValueError(f"Project '{project_name}' not found")

    return project

# Use validation functions
try:
    workspace = get_workspace_or_fail(client, "production")
    project = get_project_or_fail(client, "customer-churn")

    # Proceed with operations
    job = client.initiate_training_job(
        dataset=df,
        target_column="churn",
        workspace=workspace,
        project=project,
        model_name="My Model"
    )
except ValueError as e:
    print(f"Error: {e}")

4

Organize by Environment

Use workspace-based environment separation and environment-specific settings.

environment_config.py

# Environment configuration
ENVIRONMENTS = {
    "development": {
        "workspace": "development",
        "project": "experiments",
        "wait_for_completion": False  # Don't wait in dev
    },
    "staging": {
        "workspace": "staging",
        "project": "validation",
        "wait_for_completion": True  # Validate in staging
    },
    "production": {
        "workspace": "production",
        "project": "deployed-models",
        "wait_for_completion": True  # Monitor in prod
    }
}

def train_for_environment(client, df, target_column, model_name, env_name):
    """Train model for specific environment."""
    env_config = ENVIRONMENTS[env_name]

    workspace = client.retrieve_workspace_by_name(env_config["workspace"])
    project = client.retrieve_project_by_name(env_config["project"])

    return client.initiate_training_job(
        dataset=df,
        target_column=target_column,
        workspace=workspace,
        project=project,
        model_name=f"{model_name}_{env_name}",
        wait_for_completion=env_config["wait_for_completion"]
    )

# Train in development
dev_job = train_for_environment(client, df, "churn", "ChurnModel", "development")

5

Use Workspace Health Checks

Implement checks to verify workspace accessibility and basic health before operations.

check_workspace_health.py

def check_workspace_health(client, workspace_name):
    """Check if workspace is accessible and healthy."""
    try:
        workspace = client.retrieve_workspace_by_name(workspace_name)

        if not workspace:
            return {"healthy": False, "error": "Workspace not found"}

        # Try to list projects (verifies access)
        projects = client.list_accessible_projects(
            workspace_id=workspace.workspace_id
        )

        return {
            "healthy": True,
            "workspace_id": workspace.workspace_id,
            "project_count": len(projects)
        }

    except Exception as e:
        return {"healthy": False, "error": str(e)}

# Check workspace health before operations
health = check_workspace_health(client, "production")

if health["healthy"]:
    print(f"Workspace healthy: {health['project_count']} projects")
else:
    print(f"Workspace unhealthy: {health['error']}")

6

Implement Access Patterns

Create reusable patterns (e.g., caching) for workspace and project retrieval.

workspace_manager.py

class WorkspaceManager:
    """Manage workspace and project access."""

    def __init__(self, client):
        self.client = client
        self._workspace_cache = {}
        self._project_cache = {}

    def get_workspace(self, name, use_cache=True):
        """Get workspace with optional caching."""
        if use_cache and name in self._workspace_cache:
            return self._workspace_cache[name]

        workspace = self.client.retrieve_workspace_by_name(name)
        if workspace and use_cache:
            self._workspace_cache[name] = workspace

        return workspace

    def get_project(self, name, use_cache=True):
        """Get project with optional caching."""
        if use_cache and name in self._project_cache:
            return self._project_cache[name]

        project = self.client.retrieve_project_by_name(name)
        if project and use_cache:
            self._project_cache[name] = project

        return project

    def list_all(self):
        """List all workspaces and projects."""
        workspaces = self.client.list_accessible_workspaces()
        projects = self.client.list_accessible_projects()

        return {
            "workspaces": workspaces,
            "projects": projects
        }

# Usage
manager = WorkspaceManager(client)

workspace = manager.get_workspace("production")
project = manager.get_project("customer-churn")

7

Document Your Organization Structure

Maintain documentation describing workspace and project roles and scope.

workspace_structure.py

# workspace_structure.py
"""
Workspace and Project Organization
===================================

Workspaces:
-----------
- development: For experimental models and testing
- staging: For validated models before production
- production: For deployed production models

Projects (in production workspace):
------------------------------------
- customer-churn: Customer retention models
- fraud-detection: Fraud prevention models
- recommendations: Product recommendation models
- forecasting: Time series forecasting models
"""

WORKSPACE_DOCS = {
    "development": "Experimental models and testing",
    "staging": "Validated models before production",
    "production": "Deployed production models"
}

PROJECT_DOCS = {
    "customer-churn": "Customer retention models",
    "fraud-detection": "Fraud prevention models",
    "recommendations": "Product recommendation models",
    "forecasting": "Time series forecasting models"
}

def print_organization_docs():
    """Print organization structure documentation."""
    print("Workspace and Project Organization\n")

    print("Workspaces:")
    for name, description in WORKSPACE_DOCS.items():
        print(f"  - {name}: {description}")

    print("\nProjects:")
    for name, description in PROJECT_DOCS.items():
        print(f"  - {name}: {description}")

print_organization_docs()

See Also

• Training Models - Train models in workspaces/projects

• Model Deployment - Deploy models to workspaces/projects

• Getting Started - Basic setup and configuration

• API Reference - Workspace manager API