Workspace

The Workspace dataclass represents a local container for graphs, module state, and the path to the SQLite database file. It is a simple value-object — it holds data but delegates persistence to WorkspaceService and SqliteGraphRepository.

What a Workspace Contains

Field Type Description
id WorkspaceId Unique identifier (UUID v4)
name str Human-readable display name
db_path Path Absolute path to the SQLite database file
active_module_ids set[str] Module IDs currently active in this workspace
created_at datetime UTC creation timestamp
updated_at datetime UTC last-modified timestamp

Creating a Workspace

Use WorkspaceService.create_workspace() rather than calling Workspace.create() directly — the service also creates the database file and registers the repository.

from knowledge_platform.services.workspace_service import WorkspaceService

svc = WorkspaceService()
ws = svc.create_workspace("Research Notes")
print(ws.db_path)  # ~/.knowledge_platform/<uuid>.db

Module Activation

Workspaces track which modules are active:

ws.activate_module("outline")
print("outline" in ws.active_module_ids)  # True

ws.deactivate_module("outline")
print("outline" in ws.active_module_ids)  # False

# Deactivating a non-active module is silent (no error)
ws.deactivate_module("nonexistent")

API Reference

knowledge_platform.workspace.workspace.Workspace dataclass

Aggregates all state for a single user workspace.

A workspace lives in a directory on disk, identified by its id. It owns:

  • A reference to the SQLite database path used for persistence.
  • The set of module IDs currently active in this workspace.

Parameters:

Name Type Description Default
id WorkspaceId

Unique identifier (generated if not provided).

 required
name str

Human-readable display name.

 required
db_path Path

Absolute path to the SQLite database file.

 required
active_module_ids set[str]

Set of module IDs loaded for this workspace.

 set()
created_at datetime

UTC creation timestamp.

 (lambda: now(utc))()
updated_at datetime

UTC last-modified timestamp.

 (lambda: now(utc))()
Source code in src/knowledge_platform/workspace/workspace.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
@dataclass
class Workspace:
    """Aggregates all state for a single user workspace.

    A workspace lives in a directory on disk, identified by its *id*.  It
    owns:

    * A reference to the SQLite database path used for persistence.
    * The set of module IDs currently active in this workspace.

    Args:
        id: Unique identifier (generated if not provided).
        name: Human-readable display name.
        db_path: Absolute path to the SQLite database file.
        active_module_ids: Set of module IDs loaded for this workspace.
        created_at: UTC creation timestamp.
        updated_at: UTC last-modified timestamp.
    """

    id: WorkspaceId
    name: str
    db_path: Path
    active_module_ids: set[str] = field(default_factory=set)
    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
    updated_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))

    @classmethod
    def create(cls, name: str, directory: Path) -> "Workspace":
        """Create a new workspace rooted at *directory*.

        The SQLite file is placed at ``<directory>/<workspace_id>.db``.

        Args:
            name: Display name for the workspace.
            directory: Parent directory for the database file.

        Returns:
            A new :class:`Workspace` instance.
        """
        ws_id = new_workspace_id()
        db_path = directory / f"{ws_id}.db"
        now = datetime.now(timezone.utc)
        return cls(
            id=ws_id,
            name=name,
            db_path=db_path,
            active_module_ids=set(),
            created_at=now,
            updated_at=now,
        )

    def activate_module(self, module_id: str) -> None:
        """Mark a module as active in this workspace.

        Args:
            module_id: ID of the module to activate.
        """
        self.active_module_ids.add(module_id)
        self.updated_at = datetime.now(timezone.utc)

    def deactivate_module(self, module_id: str) -> None:
        """Remove a module from the active set.

        Args:
            module_id: ID of the module to deactivate.
        """
        self.active_module_ids.discard(module_id)
        self.updated_at = datetime.now(timezone.utc)

Functions

activate_module 
activate_module(module_id: str) -> None

Mark a module as active in this workspace.

Parameters:

Name Type Description Default
module_id str

ID of the module to activate.

 required
Source code in src/knowledge_platform/workspace/workspace.py 
63
64
65
66
67
68
69
70
def activate_module(self, module_id: str) -> None:
    """Mark a module as active in this workspace.

    Args:
        module_id: ID of the module to activate.
    """
    self.active_module_ids.add(module_id)
    self.updated_at = datetime.now(timezone.utc)
create classmethod 
create(name: str, directory: Path) -> 'Workspace'

Create a new workspace rooted at directory.

The SQLite file is placed at <directory>/<workspace_id>.db.

Parameters:

Name Type Description Default
name str

Display name for the workspace.

 required
directory Path

Parent directory for the database file.

 required

Returns:

Type Description
'Workspace'

A new :class:Workspace instance.
Source code in src/knowledge_platform/workspace/workspace.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
@classmethod
def create(cls, name: str, directory: Path) -> "Workspace":
    """Create a new workspace rooted at *directory*.

    The SQLite file is placed at ``<directory>/<workspace_id>.db``.

    Args:
        name: Display name for the workspace.
        directory: Parent directory for the database file.

    Returns:
        A new :class:`Workspace` instance.
    """
    ws_id = new_workspace_id()
    db_path = directory / f"{ws_id}.db"
    now = datetime.now(timezone.utc)
    return cls(
        id=ws_id,
        name=name,
        db_path=db_path,
        active_module_ids=set(),
        created_at=now,
        updated_at=now,
    )
deactivate_module 
deactivate_module(module_id: str) -> None

Remove a module from the active set.

Parameters:

Name Type Description Default
module_id str

ID of the module to deactivate.

 required
Source code in src/knowledge_platform/workspace/workspace.py 
72
73
74
75
76
77
78
79
def deactivate_module(self, module_id: str) -> None:
    """Remove a module from the active set.

    Args:
        module_id: ID of the module to deactivate.
    """
    self.active_module_ids.discard(module_id)
    self.updated_at = datetime.now(timezone.utc)