diff --git a/docs/workspaces.md b/docs/workspaces.md new file mode 100644 index 00000000..cdc4e751 --- /dev/null +++ b/docs/workspaces.md @@ -0,0 +1,111 @@ +# CodeGate Workspaces + +Workspaces help you group related resources together. They can be used to organize your +configurations, muxing rules and custom prompts. It is important to note that workspaces +are not a tenancy concept; CodeGate assumes that it's serving a single user. + +## Global vs Workspace resources + +In CodeGate, resources can be either global (available across all workspaces) or workspace-specific: + +- **Global resources**: These are shared across all workspaces and include provider endpoints, + authentication configurations, and personas. + +- **Workspace resources**: These are specific to a workspace and include custom instructions, + muxing rules, and conversation history. + +### Sessions and Active Workspaces + +CodeGate uses the concept of "sessions" to track which workspace is active. A session represents +a user's interaction context with the system and maintains a reference to the active workspace. + +- **Sessions**: Each session has an ID, an active workspace ID, and a last update timestamp. +- **Active workspace**: The workspace that is currently being used for processing requests. + +Currently, the implementation expects only one active session at a time, meaning only one +workspace can be active. However, the underlying architecture is designed to potentially +support multiple concurrent sessions in the future, which would allow different contexts +to have different active workspaces simultaneously. + +When a workspace is activated, the session's active_workspace_id is updated to point to that +workspace, and the muxing registry is updated to use that workspace's rules for routing requests. + +## Workspace Lifecycle + +Workspaces in CodeGate follow a specific lifecycle: + +1. **Creation**: Workspaces are created with a unique name and optional custom instructions and muxing rules. +2. **Activation**: A workspace can be activated, making it the current context for processing requests. +3. **Archiving**: Workspaces can be archived (soft-deleted) when no longer needed but might be used again. +4. **Recovery**: Archived workspaces can be recovered to make them available again. +5. **Deletion**: Archived workspaces can be permanently deleted (hard-deleted). + +### Default Workspace + +CodeGate includes a default workspace that cannot be deleted or archived. This workspace is used +when no other workspace is explicitly activated. + +## Workspace Features + +### Custom Instructions + +Each workspace can have its own set of custom instructions that are applied to LLM requests. +These instructions can be used to customize the behavior of the LLM for specific use cases. + +### Muxing Rules + +Workspaces can define muxing rules that determine which provider and model to use for different +types of requests. Rules are evaluated in priority order (first rule in the list has highest priority). + +### Token Usage Tracking + +CodeGate tracks token usage per workspace, allowing you to monitor and analyze resource consumption +across different contexts or projects. + +### Prompts, Alerts and Monitoring + +Workspaces maintain their own prompt and alert history, making it easier to monitor and respond to issues within specific contexts. + +## Developing + +### When to use workspaces? + +Consider using separate workspaces when: + +- You need different custom instructions for different projects or use cases +- You want to route different types of requests to different models +- You need to track token usage separately for different projects +- You want to isolate alerts and monitoring for specific contexts +- You're experimenting with different configurations and want to switch between them easily + +### When should a resource be global? + +Resources should be global when: + +- They need to be shared across multiple workspaces +- They represent infrastructure configuration rather than usage patterns +- They're related to provider connectivity rather than specific use cases +- They represent reusable components like personas that might be used in multiple contexts + +### Exporting resources + +Exporting resources in CodeGate is designed to facilitate sharing workspaces between different instances. +This is particularly useful for: + +- **Standardizing configurations**: When you want to ensure consistent behavior across multiple CodeGate instances +- **Sharing best practices**: When you've developed effective muxing rules or custom instructions that others could benefit from +- **Backup and recovery**: To preserve important workspace configurations before making significant changes + +When deciding whether to export resources, consider: + +- **Export workspace configurations** when they represent reusable patterns that could be valuable in other contexts +- **Export muxing rules** when they represent well-tested routing strategies that could be applied in other instances +- **Export custom instructions** when they contain general-purpose prompting strategies not specific to your instance + +Avoid exporting: +- Workspaces with instance-specific configurations that wouldn't be applicable elsewhere +- Workspaces containing sensitive or organization-specific custom instructions +- Resources that are tightly coupled to your specific provider endpoints or authentication setup + +Note that conversation history, alerts, and token usage statistics are not included in exports as they +represent instance-specific usage data rather than reusable configurations.