julee.services.knowledge_service.knowledge_service

KnowledgeService protocol for external service operations in the Capture, Extract, Assemble, Publish workflow.

This module defines the KnowledgeService protocol that handles interactions with external knowledge services, including document registration and query execution. This protocol is separate from the repository layer which only handles local metadata persistence.

Concrete implementations of this protocol are provided for different external services (Anthropic, OpenAI, etc.) and are created via factory functions.

Classes

FileRegistrationResult	Result of registering a file with a knowledge service.
KnowledgeService	Protocol for interacting with external knowledge services.
QueryResult	Result of a knowledge service query execution.

Module Contents

class julee.services.knowledge_service.knowledge_service.FileRegistrationResult(/, **data)

Bases: pydantic.BaseModel

Result of registering a file with a knowledge service.

created_at: datetime.datetime | None = None

document_id: str = None

knowledge_service_file_id: str = None

registration_metadata: dict[str, Any] = None

class julee.services.knowledge_service.knowledge_service.KnowledgeService

Bases: Protocol

Protocol for interacting with external knowledge services.

This protocol defines the interface for external operations that were moved out of the repository layer. Implementations handle the specifics of different knowledge service APIs (Anthropic, OpenAI, etc.).

async execute_query(config, query_text, output_schema=None, service_file_ids=None, query_metadata=None, assistant_prompt=None)

Execute a query against the external knowledge service.

This method executes a text query against the knowledge service, optionally scoping the query to specific documents that have been previously registered with the service.

Parameters:

• config (julee.domain.models.knowledge_service_config.KnowledgeServiceConfig) – KnowledgeServiceConfig for the service to use

• query_text (str) – The query to execute (natural language or structured)

• output_schema (dict[str, Any] | None) – Optional JSON schema for structured response. When provided, the service will attempt to return results conforming to this schema using structured outputs or schema-guided prompting.

• service_file_ids (list[str] | None) – Optional list of service file IDs to provide as context for the query. These are the IDs returned by the knowledge service from register_file operations, and are included in the query to give the service access to specific documents.

• query_metadata (dict[str, Any] | None) – Optional service-specific metadata and configuration options such as model selection, temperature, max_tokens, etc. The structure depends on the specific knowledge service being used.

• assistant_prompt (str | None) – Optional assistant message content to constrain or prime the model’s response. This is added as the final assistant message before the model generates its response, allowing control over response format and structure.

Returns:

QueryResult containing query results and execution metadata

Return type:

QueryResult

Implementation Notes

• Must be idempotent: same query returns consistent results

• Service file IDs are provided as context to enhance query responses

• Should handle service unavailability gracefully

• Query results should be structured as domain objects

• Should track execution time and metadata

• Must handle various query formats (natural language, structured, etc.)

• Should validate that service_file_ids exist in the service before including them in the query context

Workflow Context

In Temporal workflows, this method is implemented as an activity to ensure query results are durably stored and can be replayed consistently.

async register_file(config, document)

Register a document file with the external knowledge service.

This method registers a document with the external knowledge service, allowing that service to analyze and index the document content for future queries.

Parameters:

• config (julee.domain.models.knowledge_service_config.KnowledgeServiceConfig) – KnowledgeServiceConfig for the service to use

• document (julee.domain.models.document.Document) – Document domain object to register

Returns:

FileRegistrationResult containing registration details and the service’s internal file identifier

Return type:

FileRegistrationResult

Implementation Notes

• Must be idempotent: re-registering same document returns same result

• Should handle service unavailability gracefully

• Must return the service’s internal file ID for future queries

• Document content is accessed directly from the Document object

• Should handle various document formats and sizes

Workflow Context

In Temporal workflows, this method is implemented as an activity to ensure registration results are durably stored and consistent across workflow replays.

class julee.services.knowledge_service.knowledge_service.QueryResult(/, **data)

Bases: pydantic.BaseModel

Result of a knowledge service query execution.

created_at: datetime.datetime | None = None

execution_time_ms: int | None = None

query_id: str = None

query_text: str = None

result_data: dict[str, Any] = None