julee.services
==============

.. py:module:: julee.services

.. autoapi-nested-parse::

   Services for julee domain.

   This module provides service classes and factory functions for interacting
   with external services in the Capture, Extract, Assemble, Publish workflow.

   The services layer handles external integrations while the repository layer
   handles local metadata persistence. Services are organized by service type
   into submodules, each with their own protocols and implementations.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/julee/services/knowledge_service/index
   /autoapi/julee/services/temporal/index


Classes
-------

.. autoapisummary::

   julee.services.KnowledgeService


Package Contents
----------------

.. py:class:: KnowledgeService

   Bases: :py:obj:`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.).


   .. py:method:: execute_query(config, query_text, output_schema = None, service_file_ids = None, query_metadata = None, assistant_prompt = None)
      :async:


      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.

      :param config: KnowledgeServiceConfig for the service to use
      :param query_text: The query to execute (natural language or structured)
      :param output_schema: 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.
      :param service_file_ids: 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.
      :param query_metadata: 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.
      :param assistant_prompt: 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

      .. rubric:: 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

      .. rubric:: Workflow Context

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




   .. py:method:: register_file(config, document)
      :async:


      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.

      :param config: KnowledgeServiceConfig for the service to use
      :param document: Document domain object to register

      :returns: FileRegistrationResult containing registration details and the
                service's internal file identifier

      .. rubric:: 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

      .. rubric:: Workflow Context

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