mirror of https://github.com/pocketpaw/pocketpaw.git synced 2026-05-13 21:21:53 +00:00

Files

Prakash fbaea85950 Reapply "Merge pull request #778 from pocketpaw/feat/close-critical-gaps"

This reverts commit 2b76f2acc6.

2026-04-10 17:42:15 +05:30

11 KiB

Raw Blame History

ee/cloud/kb/init — Knowledge Base Domain Package Initialization and Endpoint Exposure

This module serves as the entry point for the Knowledge Base (KB) domain within the Enterprise Edition cloud infrastructure. It acts as a package initializer that exposes workspace-scoped KB endpoints for search, ingest, browse, lint, and stats operations. Its existence as a separate init module indicates KB is a distinct bounded domain within the workspace feature set, following domain-driven design principles.

Categories: Knowledge Management Domain, API Router / Endpoint Layer, Workspace-Scoped Feature, Enterprise Edition Cloud Infrastructure
Concepts: Knowledge Base domain (KB), Workspace scoping, Bounded domain pattern, Domain-driven design, FastAPI router pattern, Dependency injection, Event-driven consistency, Multi-layered authorization, License tier gating, Stateless handler pattern
Words: 1132 | Version: 1

Purpose

The __init__.py module at /ee/cloud/kb/ functions as the package initialization boundary for the Knowledge Base domain. In a domain-driven architecture, this module's primary responsibilities are:

Domain Encapsulation: It marks the kb directory as a Python package and defines the public API surface for all KB-related functionality within the enterprise cloud workspace context.
Problem Space: The Knowledge Base domain solves the problem of managing, searching, ingesting, and maintaining quality of workspace-specific knowledge repositories. Organizations need to search across documents, lint them for quality, browse hierarchies, and collect statistics—all within strict workspace boundaries.
Architectural Role: This module sits within the /ee/cloud/ layer, indicating KB functionality is an enterprise edition feature available to cloud-deployed workspaces. It represents one functional domain among several (workspace, user, agent, message, etc.) that together compose the cloud platform.

Module Organization

While this specific file contains no executable code (only a comment), its imports reveal the KB domain's internal structure and dependencies:

Internal Domain Components (imported from within kb/submodules):

errors — Domain-specific exception types for KB operations
router — FastAPI route handlers exposing KB endpoints (search, ingest, browse, lint, stats)
workspace — Workspace-scoped KB context and bindings
core — Core KB business logic and entity definitions

Cross-Domain Dependencies (shared across cloud platform):

license — Access control based on subscription tier
user — User identity and permission context
deps — FastAPI dependency injection utilities
event_handlers — Event publishing for KB mutations (ingest, delete, etc.)
agent_bridge — Integration with agent execution context
agent — Agent entity references
comment — Comment annotations on KB documents
file — File attachments and references
group — Group access control and permissions
invite — Sharing and access invitation workflows
message — Cross-reference to conversation context
notification — Change notifications
pocket — Pocket/saved item integration
session — Request session and user context

Key Endpoints and Operations

Based on the comment, this domain exposes the following workspace-scoped KB endpoints:

Search: Query knowledge base documents with optional filtering and ranking.

Ingest: Add new documents to the knowledge base, likely triggering indexing and event notifications.

Browse: Navigate KB structure (hierarchies, collections, tags) for discovery and exploration.

Lint: Validate KB documents for quality standards (completeness, format, metadata, etc.).

Stats: Aggregate and report on KB statistics (document count, update frequency, access patterns, etc.).

How It Works

Request Flow

HTTP Request arrives at a KB endpoint (e.g., POST /workspaces/{workspace_id}/kb/search)
FastAPI Routing (via router) matches the request to a handler
Dependency Injection (via deps) injects:
- session — Current user and workspace context
- license — License tier validation
- workspace — Workspace-specific KB configuration
Authorization Check — Handler verifies user has required permissions via group and user modules
Business Logic Execution (via core) — Performs the actual operation (search query, document ingestion, etc.)
Event Publishing (via event_handlers) — Publishes KB mutations for consistency (indexing, notifications, audit)
Response — Returns results to client

Data Flow

Ingest: Documents flow from client → handler → core business logic → storage → event_handlers → indexing/notifications
Search: Query parameters → core search logic → ranking → response
Lint: Documents → validation rules in core → error report
Stats: Aggregate operations on stored KB data → statistics response

Authorization and Security

Knowledge Base access is governed by multiple layers:

Workspace Scoping — All KB operations are workspace-scoped; users can only access KB within authorized workspaces
License Tier — The license module gates KB features (e.g., advanced search may require premium tier)
Group Permissions — The group module defines who can ingest, browse, lint, or manage KB within a workspace
User Context — The user module provides identity; the session module provides request-level user/workspace context
Audit Events — The event_handlers module likely publishes events for audit logging of KB modifications

Dependencies and Integration

Why KB Depends on These Modules

Dependency	Why	Usage Pattern
`workspace`	KB is workspace-scoped	Every KB operation validates workspace context
`user`, `session`	Identify who is accessing KB	Request handlers inject current user/session
`license`	Gate premium KB features	Tier-based endpoint availability
`event_handlers`	Maintain consistency	Publish events on ingest/delete for indexing and notifications
`group`	Enforce KB access control	Check group membership for permission to operate
`core`	Encapsulate KB business logic	Router delegates to core for actual operations
`agent_bridge`, `agent`	Integrate KB with agentic workflows	Agents may query or populate KB
`file`, `comment`, `message`	Cross-domain references	KB documents may attach files, receive comments, relate to messages
`notification`, `pocket`	UX integration	Notify users of KB changes; save KB items

How KB is Used

The KB domain is likely consumed by:

Frontend clients via REST API exposed by router
Agents via agent_bridge for context retrieval
Other domain modules for embedded knowledge features (e.g., message context enrichment)

Design Decisions

1. Domain-Driven Design

KB is organized as a separate bounded domain (kb/) within the cloud workspace, not scattered across other modules. This enforces cohesion and reduces coupling.

2. Workspace Scoping Pattern

All KB operations are workspace-scoped. This is enforced consistently through the workspace dependency and session context, preventing data leakage across organizations.

3. Event-Driven Consistency

Rather than KB handlers directly triggering indexing or notifications, they publish events via event_handlers. This decouples KB business logic from downstream concerns and enables non-blocking operations.

4. Multi-Layered Authorization

Authorization is not just binary (allowed/denied) but layered: license tier gates features, groups gate access, and user context validates ownership. This supports fine-grained access control in enterprise environments.

5. Stateless Handler Pattern

The router module uses stateless handlers (typical FastAPI style) that rely entirely on dependency injection for context. This simplifies testing and horizontal scaling.

6. Functional Decomposition

The five main endpoints (search, ingest, browse, lint, stats) decompose KB responsibilities into focused, composable operations rather than monolithic CRUD.

When to Use This Module

Use KB if you need to:

Allow users to store, organize, and search knowledge documents within a workspace
Ingest external data sources into a centralized knowledge repository
Quality-assure knowledge through linting and validation
Analyze KB usage and document statistics
Integrate knowledge with agents or AI workflows
Control KB access via workspace and group permissions

Don't use KB if:

You're building a general-purpose document search (use generic file search instead)
Users don't need permission-based access control
You're operating outside of workspace context
Your use case doesn't require enterprise edition features

11 KiB Raw Blame History