Skip to content

Prompts

patronus.prompts

clients

load_prompt module-attribute 

load_prompt = get

Alias for PromptClient.get.

aload_prompt module-attribute 

aload_prompt = get

Alias for AsyncPromptClient.get.

push_prompt module-attribute 

push_prompt = push

Alias for PromptClient.push.

apush_prompt module-attribute 

apush_prompt = push

Alias for AsyncPromptClient.push.

PromptNotFoundError 

PromptNotFoundError(
    name: str,
    project: Optional[str] = None,
    revision: Optional[int] = None,
    label: Optional[str] = None,
)

Bases: Exception

Raised when a prompt could not be found.

Source code in src/patronus/prompts/clients.py 
28
29
30
31
32
33
34
35
36
def __init__(
    self, name: str, project: Optional[str] = None, revision: Optional[int] = None, label: Optional[str] = None
):
    self.name = name
    self.project = project
    self.revision = revision
    self.label = label
    message = f"Prompt not found (name={name!r}, project={project!r}, revision={revision!r}, label={label!r})"
    super().__init__(message)

PromptProviderError

Bases: Exception

Base class for prompt provider errors.

PromptProviderConnectionError

Bases: PromptProviderError

Raised when there's a connectivity issue with the prompt provider.

PromptProviderAuthenticationError

Bases: PromptProviderError

Raised when there's an authentication issue with the prompt provider.

PromptProvider

Bases: ABC

get_prompt abstractmethod 
get_prompt(
    name: str,
    revision: Optional[int],
    label: Optional[str],
    project: str,
    engine: TemplateEngine,
) -> Optional[LoadedPrompt]

Get prompts, returns None if prompt was not found

Source code in src/patronus/prompts/clients.py 
52
53
54
55
56
@abc.abstractmethod
def get_prompt(
    self, name: str, revision: Optional[int], label: Optional[str], project: str, engine: TemplateEngine
) -> Optional[LoadedPrompt]:
    """Get prompts, returns None if prompt was not found"""
aget_prompt abstractmethod async 
aget_prompt(
    name: str,
    revision: Optional[int],
    label: Optional[str],
    project: str,
    engine: TemplateEngine,
) -> Optional[LoadedPrompt]

Get prompts, returns None if prompt was not found

Source code in src/patronus/prompts/clients.py 
58
59
60
61
62
@abc.abstractmethod
async def aget_prompt(
    self, name: str, revision: Optional[int], label: Optional[str], project: str, engine: TemplateEngine
) -> Optional[LoadedPrompt]:
    """Get prompts, returns None if prompt was not found"""

PromptClientMixin

PromptClient 

PromptClient(
    provider_factory: Optional[ProviderFactory] = None,
)

Bases: PromptClientMixin

Source code in src/patronus/prompts/clients.py 
303
304
305
306
307
308
309
def __init__(self, provider_factory: Optional[ProviderFactory] = None) -> None:
    self._cache: PromptCache = PromptCache()
    self._provider_factory: ProviderFactory = provider_factory or {
        "local": lambda: LocalPromptProvider(),
        "api": lambda: APIPromptProvider(),
    }
    self._api_provider = APIPromptProvider()
get 
get(
    name: str,
    revision: Optional[int] = None,
    label: Optional[str] = None,
    project: Union[str, Type[NOT_GIVEN]] = NOT_GIVEN,
    disable_cache: bool = False,
    provider: Union[
        PromptProvider,
        _DefaultProviders,
        Sequence[Union[PromptProvider, _DefaultProviders]],
        Type[NOT_GIVEN],
    ] = NOT_GIVEN,
    engine: Union[
        TemplateEngine,
        DefaultTemplateEngines,
        Type[NOT_GIVEN],
    ] = NOT_GIVEN,
) -> LoadedPrompt

Get the prompt. If neither revision nor label is specified then the prompt with latest revision is returned.

Project is loaded from the config by default. You can specify the project name of the prompt if you want to override the value from the config.

By default, once a prompt is retrieved it's cached. You can disable caching.

Parameters:

Name Type Description Default
name str

The name of the prompt to retrieve.

 required
revision Optional[int]

Optional specific revision number to retrieve. If not specified, the latest revision is used.

 None
label Optional[str]

Optional label to filter by. If specified, only prompts with this label will be returned.

 None
project Union[str, Type[NOT_GIVEN]]

Optional project name override. If not specified, the project name from config is used.

 NOT_GIVEN
disable_cache bool

If True, bypasses the cache for both reading and writing.

 False
provider Union[PromptProvider, _DefaultProviders, Sequence[Union[PromptProvider, _DefaultProviders]], Type[NOT_GIVEN]]

The provider(s) to use for retrieving prompts. Can be a string identifier ('local', 'api'), a PromptProvider instance, or a sequence of these. If not specified, defaults to config setting.

 NOT_GIVEN
engine Union[TemplateEngine, DefaultTemplateEngines, Type[NOT_GIVEN]]

The template engine to use for rendering prompts. Can be a string identifier ('f-string', 'mustache', 'jinja2') or a TemplateEngine instance. If not specified, defaults to config setting.

 NOT_GIVEN

Returns:

Name Type Description
LoadedPrompt LoadedPrompt

The retrieved prompt object.

Raises:

Type Description
PromptNotFoundError

If the prompt could not be found with the specified parameters.
ValueError

If the provided provider or engine is invalid.
PromptProviderError

If there was an error communicating with the prompt provider.
Source code in src/patronus/prompts/clients.py 
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
def get(
    self,
    name: str,
    revision: Optional[int] = None,
    label: Optional[str] = None,
    project: Union[str, Type[NOT_GIVEN]] = NOT_GIVEN,
    disable_cache: bool = False,
    provider: Union[
        PromptProvider,
        _DefaultProviders,
        Sequence[Union[PromptProvider, _DefaultProviders]],
        Type[NOT_GIVEN],
    ] = NOT_GIVEN,
    engine: Union[TemplateEngine, DefaultTemplateEngines, Type[NOT_GIVEN]] = NOT_GIVEN,
) -> LoadedPrompt:
    """
    Get the prompt.
    If neither revision nor label is specified then the prompt with latest revision is returned.

    Project is loaded from the config by default.
    You can specify the project name of the prompt if you want to override the value from the config.

    By default, once a prompt is retrieved it's cached. You can disable caching.

    Args:
        name: The name of the prompt to retrieve.
        revision: Optional specific revision number to retrieve. If not specified, the latest revision is used.
        label: Optional label to filter by. If specified, only prompts with this label will be returned.
        project: Optional project name override. If not specified, the project name from config is used.
        disable_cache: If True, bypasses the cache for both reading and writing.
        provider: The provider(s) to use for retrieving prompts. Can be a string identifier ('local', 'api'),
                 a PromptProvider instance, or a sequence of these. If not specified, defaults to config setting.
        engine: The template engine to use for rendering prompts. Can be a string identifier ('f-string', 'mustache', 'jinja2')
               or a TemplateEngine instance. If not specified, defaults to config setting.

    Returns:
        LoadedPrompt: The retrieved prompt object.

    Raises:
        PromptNotFoundError: If the prompt could not be found with the specified parameters.
        ValueError: If the provided provider or engine is invalid.
        PromptProviderError: If there was an error communicating with the prompt provider.
    """
    project_name: str = self._resolve_project(project)
    resolved_providers: list[PromptProvider] = self._resolve_providers(provider, self._provider_factory)
    resolved_engine: TemplateEngine = self._resolve_engine(engine)

    cache_key: _CacheKey = _CacheKey(project_name=project_name, prompt_name=name, revision=revision, label=label)
    if not disable_cache:
        cached_prompt: Optional[LoadedPrompt] = self._cache.get(cache_key)
        if cached_prompt is not None:
            return cached_prompt

    prompt: Optional[LoadedPrompt] = None
    provider_errors: list[str] = []

    for i, prompt_provider in enumerate(resolved_providers):
        log.debug("Trying prompt provider %d (%s)", i + 1, prompt_provider.__class__.__name__)
        try:
            prompt = prompt_provider.get_prompt(name, revision, label, project_name, engine=resolved_engine)
            if prompt is not None:
                log.debug("Prompt found using provider %s", prompt_provider.__class__.__name__)
                break
        except PromptProviderConnectionError as e:
            provider_errors.append(str(e))
            continue
        except PromptProviderAuthenticationError as e:
            provider_errors.append(str(e))
            continue
        except Exception as e:
            provider_errors.append(f"Unexpected error from provider {prompt_provider.__class__.__name__}: {str(e)}")
            continue

    if prompt is None:
        if provider_errors:
            error_msg: str = self._format_provider_errors(provider_errors)
            raise PromptNotFoundError(
                name=name, project=project_name, revision=revision, label=label
            ) from Exception(error_msg)
        else:
            raise PromptNotFoundError(name=name, project=project_name, revision=revision, label=label)

    if not disable_cache:
        self._cache.put(cache_key, prompt)

    return prompt
push 
push(
    prompt: Prompt,
    project: Union[str, Type[NOT_GIVEN]] = NOT_GIVEN,
    engine: Union[
        TemplateEngine,
        DefaultTemplateEngines,
        Type[NOT_GIVEN],
    ] = NOT_GIVEN,
) -> LoadedPrompt

Push a prompt to the API, creating a new revision only if needed.

If a prompt revision with the same normalized body and metadata already exists, the existing revision will be returned. If the metadata differs, a new revision will be created.

The engine parameter is only used to set property on output LoadedPrompt object. It is not persisted in any way and doesn't affect how the prompt is stored in Patronus AI Platform.

Note that when a new prompt definition is created, the description is used as provided. However, when creating a new revision for an existing prompt definition, the description parameter doesn't update the existing prompt definition's description.

Parameters:

Name Type Description Default
prompt Prompt

The prompt to push

 required
project Union[str, Type[NOT_GIVEN]]

Optional project name override. If not specified, the project name from config is used.

 NOT_GIVEN
engine Union[TemplateEngine, DefaultTemplateEngines, Type[NOT_GIVEN]]

The template engine to use for rendering the returned prompt. If not specified, defaults to config setting.

 NOT_GIVEN

Returns:

Name Type Description
LoadedPrompt LoadedPrompt

The created or existing prompt revision

Raises:

Type Description
PromptProviderError

If there was an error communicating with the prompt provider.
Source code in src/patronus/prompts/clients.py 
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
def push(
    self,
    prompt: Prompt,
    project: Union[str, Type[NOT_GIVEN]] = NOT_GIVEN,
    engine: Union[TemplateEngine, DefaultTemplateEngines, Type[NOT_GIVEN]] = NOT_GIVEN,
) -> LoadedPrompt:
    """
    Push a prompt to the API, creating a new revision only if needed.

    If a prompt revision with the same normalized body and metadata already exists,
    the existing revision will be returned. If the metadata differs, a new revision will be created.

    The engine parameter is only used to set property on output LoadedPrompt object.
    It is not persisted in any way and doesn't affect how the prompt is stored in Patronus AI Platform.

    Note that when a new prompt definition is created, the description is used as provided.
    However, when creating a new revision for an existing prompt definition, the
    description parameter doesn't update the existing prompt definition's description.

    Args:
        prompt: The prompt to push
        project: Optional project name override. If not specified, the project name from config is used.
        engine: The template engine to use for rendering the returned prompt. If not specified, defaults to config setting.

    Returns:
        LoadedPrompt: The created or existing prompt revision

    Raises:
        PromptProviderError: If there was an error communicating with the prompt provider.
    """
    project_name: str = self._resolve_project(project)
    resolved_engine: TemplateEngine = self._resolve_engine(engine)

    normalized_body_sha256 = calculate_normalized_body_hash(prompt.body)

    cli = context.get_api_client().prompts
    # Try to find existing revision with same hash
    resp = cli.list_revisions(
        prompt_name=prompt.name,
        project_name=project_name,
        normalized_body_sha256=normalized_body_sha256,
    )

    # Variables for create_revision parameters
    prompt_id = patronus_api.NOT_GIVEN
    prompt_name = prompt.name
    create_new_prompt = True
    prompt_def = None

    # If we found a matching revision, check if metadata is the same
    if resp.prompt_revisions:
        log.debug("Found %d revisions with matching body hash", len(resp.prompt_revisions))
        prompt_id = resp.prompt_revisions[0].prompt_definition_id
        create_new_prompt = False

        resp_pd = cli.list_definitions(prompt_id=prompt_id, limit=1)
        if not resp_pd.prompt_definitions:
            raise PromptProviderError(
                "Prompt revision has been found but prompt definition was not found. This should not happen"
            )
        prompt_def = resp_pd.prompt_definitions[0]

        # Check if the provided description is different from existing one and warn if so
        if prompt.description is not None and prompt.description != prompt_def.description:
            warnings.warn(
                f"Prompt description ({prompt.description!r}) differs from the existing one "
                f"({prompt_def.description!r}). The description won't be updated."
            )

        new_metadata_cmp = json.dumps(prompt.metadata, sort_keys=True)
        for rev in resp.prompt_revisions:
            metadata_cmp = json.dumps(rev.metadata, sort_keys=True)
            if new_metadata_cmp == metadata_cmp:
                log.debug("Found existing revision with matching metadata, returning revision %d", rev.revision)
                return self._api_provider._create_loaded_prompt(
                    prompt_revision=rev,
                    prompt_def=prompt_def,
                    engine=resolved_engine,
                )

        # For existing prompt, don't need name/project
        prompt_name = patronus_api.NOT_GIVEN
        project_name = patronus_api.NOT_GIVEN
    else:
        # No matching revisions found, will create new prompt
        log.debug("No revisions with matching body hash found, creating new prompt and revision")

    # Create a new revision with appropriate parameters
    log.debug(
        "Creating new revision (new_prompt=%s, prompt_id=%s, prompt_name=%s)",
        create_new_prompt,
        prompt_id if prompt_id != patronus_api.NOT_GIVEN else "NOT_GIVEN",
        prompt_name if prompt_name != patronus_api.NOT_GIVEN else "NOT_GIVEN",
    )
    resp = cli.create_revision(
        body=prompt.body,
        prompt_id=prompt_id,
        prompt_name=prompt_name,
        project_name=project_name if create_new_prompt else patronus_api.NOT_GIVEN,
        prompt_description=prompt.description,
        metadata=prompt.metadata,
    )

    prompt_revision = resp.prompt_revision

    # If we created a new prompt, we need to fetch the definition
    if create_new_prompt:
        resp_pd = cli.list_definitions(prompt_id=prompt_revision.prompt_definition_id, limit=1)
        if not resp_pd.prompt_definitions:
            raise PromptProviderError(
                "Prompt revision has been created but prompt definition was not found. This should not happen"
            )
        prompt_def = resp_pd.prompt_definitions[0]

    return self._api_provider._create_loaded_prompt(prompt_revision, prompt_def, resolved_engine)

AsyncPromptClient 

AsyncPromptClient(
    provider_factory: Optional[ProviderFactory] = None,
)

Bases: PromptClientMixin

Source code in src/patronus/prompts/clients.py 
516
517
518
519
520
521
522
def __init__(self, provider_factory: Optional[ProviderFactory] = None) -> None:
    self._cache: AsyncPromptCache = AsyncPromptCache()
    self._provider_factory: ProviderFactory = provider_factory or {
        "local": lambda: LocalPromptProvider(),
        "api": lambda: APIPromptProvider(),
    }
    self._api_provider = APIPromptProvider()
get async 
get(
    name: str,
    revision: Optional[int] = None,
    label: Optional[str] = None,
    project: Union[str, Type[NOT_GIVEN]] = NOT_GIVEN,
    disable_cache: bool = False,
    provider: Union[
        PromptProvider,
        _DefaultProviders,
        Sequence[Union[PromptProvider, _DefaultProviders]],
        Type[NOT_GIVEN],
    ] = NOT_GIVEN,
    engine: Union[
        TemplateEngine,
        DefaultTemplateEngines,
        Type[NOT_GIVEN],
    ] = NOT_GIVEN,
) -> LoadedPrompt

Get the prompt asynchronously. If neither revision nor label is specified then the prompt with latest revision is returned.

Project is loaded from the config by default. You can specify the project name of the prompt if you want to override the value from the config.

By default, once a prompt is retrieved it's cached. You can disable caching.

Parameters:

Name Type Description Default
name str

The name of the prompt to retrieve.

 required
revision Optional[int]

Optional specific revision number to retrieve. If not specified, the latest revision is used.

 None
label Optional[str]

Optional label to filter by. If specified, only prompts with this label will be returned.

 None
project Union[str, Type[NOT_GIVEN]]

Optional project name override. If not specified, the project name from config is used.

 NOT_GIVEN
disable_cache bool

If True, bypasses the cache for both reading and writing.

 False
provider Union[PromptProvider, _DefaultProviders, Sequence[Union[PromptProvider, _DefaultProviders]], Type[NOT_GIVEN]]

The provider(s) to use for retrieving prompts. Can be a string identifier ('local', 'api'), a PromptProvider instance, or a sequence of these. If not specified, defaults to config setting.

 NOT_GIVEN
engine Union[TemplateEngine, DefaultTemplateEngines, Type[NOT_GIVEN]]

The template engine to use for rendering prompts. Can be a string identifier ('f-string', 'mustache', 'jinja2') or a TemplateEngine instance. If not specified, defaults to config setting.

 NOT_GIVEN

Returns:

Name Type Description
LoadedPrompt LoadedPrompt

The retrieved prompt object.

Raises:

Type Description
PromptNotFoundError

If the prompt could not be found with the specified parameters.
ValueError

If the provided provider or engine is invalid.
PromptProviderError

If there was an error communicating with the prompt provider.
Source code in src/patronus/prompts/clients.py 
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
async def get(
    self,
    name: str,
    revision: Optional[int] = None,
    label: Optional[str] = None,
    project: Union[str, Type[NOT_GIVEN]] = NOT_GIVEN,
    disable_cache: bool = False,
    provider: Union[
        PromptProvider, _DefaultProviders, Sequence[Union[PromptProvider, _DefaultProviders]], Type[NOT_GIVEN]
    ] = NOT_GIVEN,
    engine: Union[TemplateEngine, DefaultTemplateEngines, Type[NOT_GIVEN]] = NOT_GIVEN,
) -> LoadedPrompt:
    """
    Get the prompt asynchronously.
    If neither revision nor label is specified then the prompt with latest revision is returned.

    Project is loaded from the config by default.
    You can specify the project name of the prompt if you want to override the value from the config.

    By default, once a prompt is retrieved it's cached. You can disable caching.

    Args:
        name: The name of the prompt to retrieve.
        revision: Optional specific revision number to retrieve. If not specified, the latest revision is used.
        label: Optional label to filter by. If specified, only prompts with this label will be returned.
        project: Optional project name override. If not specified, the project name from config is used.
        disable_cache: If True, bypasses the cache for both reading and writing.
        provider: The provider(s) to use for retrieving prompts. Can be a string identifier ('local', 'api'),
                 a PromptProvider instance, or a sequence of these. If not specified, defaults to config setting.
        engine: The template engine to use for rendering prompts. Can be a string identifier ('f-string', 'mustache', 'jinja2')
               or a TemplateEngine instance. If not specified, defaults to config setting.

    Returns:
        LoadedPrompt: The retrieved prompt object.

    Raises:
        PromptNotFoundError: If the prompt could not be found with the specified parameters.
        ValueError: If the provided provider or engine is invalid.
        PromptProviderError: If there was an error communicating with the prompt provider.
    """
    project_name: str = self._resolve_project(project)
    resolved_providers: list[PromptProvider] = self._resolve_providers(provider, self._provider_factory)
    resolved_engine: TemplateEngine = self._resolve_engine(engine)

    cache_key: _CacheKey = _CacheKey(project_name=project_name, prompt_name=name, revision=revision, label=label)
    if not disable_cache:
        cached_prompt: Optional[LoadedPrompt] = await self._cache.get(cache_key)
        if cached_prompt is not None:
            return cached_prompt

    prompt: Optional[LoadedPrompt] = None
    provider_errors: list[str] = []

    for i, prompt_provider in enumerate(resolved_providers):
        log.debug("Trying prompt provider %d (%s) async", i + 1, prompt_provider.__class__.__name__)
        try:
            prompt = await prompt_provider.aget_prompt(name, revision, label, project_name, engine=resolved_engine)
            if prompt is not None:
                log.debug("Prompt found using async provider %s", prompt_provider.__class__.__name__)
                break
        except PromptProviderConnectionError as e:
            provider_errors.append(str(e))
            continue
        except PromptProviderAuthenticationError as e:
            provider_errors.append(str(e))
            continue
        except Exception as e:
            provider_errors.append(f"Unexpected error from provider {prompt_provider.__class__.__name__}: {str(e)}")
            continue

    if prompt is None:
        if provider_errors:
            error_msg: str = self._format_provider_errors(provider_errors)
            raise PromptNotFoundError(
                name=name, project=project_name, revision=revision, label=label
            ) from Exception(error_msg)
        else:
            raise PromptNotFoundError(name=name, project=project_name, revision=revision, label=label)

    if not disable_cache:
        await self._cache.put(cache_key, prompt)

    return prompt
push async 
push(
    prompt: Prompt,
    project: Union[str, Type[NOT_GIVEN]] = NOT_GIVEN,
    engine: Union[
        TemplateEngine,
        DefaultTemplateEngines,
        Type[NOT_GIVEN],
    ] = NOT_GIVEN,
) -> LoadedPrompt

Push a prompt to the API asynchronously, creating a new revision only if needed.

If a prompt revision with the same normalized body and metadata already exists, the existing revision will be returned. If the metadata differs, a new revision will be created.

The engine parameter is only used to set property on output LoadedPrompt object. It is not persisted in any way and doesn't affect how the prompt is stored in Patronus AI Platform.

Note that when a new prompt definition is created, the description is used as provided. However, when creating a new revision for an existing prompt definition, the description parameter doesn't update the existing prompt definition's description.

Parameters:

Name Type Description Default
prompt Prompt

The prompt to push

 required
project Union[str, Type[NOT_GIVEN]]

Optional project name override. If not specified, the project name from config is used.

 NOT_GIVEN
engine Union[TemplateEngine, DefaultTemplateEngines, Type[NOT_GIVEN]]

The template engine to use for rendering the returned prompt. If not specified, defaults to config setting.

 NOT_GIVEN

Returns:

Name Type Description
LoadedPrompt LoadedPrompt

The created or existing prompt revision

Raises:

Type Description
PromptProviderError

If there was an error communicating with the prompt provider.
Source code in src/patronus/prompts/clients.py 
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
async def push(
    self,
    prompt: Prompt,
    project: Union[str, Type[NOT_GIVEN]] = NOT_GIVEN,
    engine: Union[TemplateEngine, DefaultTemplateEngines, Type[NOT_GIVEN]] = NOT_GIVEN,
) -> LoadedPrompt:
    """
    Push a prompt to the API asynchronously, creating a new revision only if needed.

    If a prompt revision with the same normalized body and metadata already exists,
    the existing revision will be returned. If the metadata differs, a new revision will be created.

    The engine parameter is only used to set property on output LoadedPrompt object.
    It is not persisted in any way and doesn't affect how the prompt is stored in Patronus AI Platform.

    Note that when a new prompt definition is created, the description is used as provided.
    However, when creating a new revision for an existing prompt definition, the
    description parameter doesn't update the existing prompt definition's description.

    Args:
        prompt: The prompt to push
        project: Optional project name override. If not specified, the project name from config is used.
        engine: The template engine to use for rendering the returned prompt. If not specified, defaults to config setting.

    Returns:
        LoadedPrompt: The created or existing prompt revision

    Raises:
        PromptProviderError: If there was an error communicating with the prompt provider.
    """
    project_name: str = self._resolve_project(project)
    resolved_engine: TemplateEngine = self._resolve_engine(engine)

    normalized_body_sha256 = calculate_normalized_body_hash(prompt.body)

    cli = context.get_async_api_client().prompts
    # Try to find existing revision with same hash
    resp = await cli.list_revisions(
        prompt_name=prompt.name,
        project_name=project_name,
        normalized_body_sha256=normalized_body_sha256,
    )

    # Variables for create_revision parameters
    prompt_id = patronus_api.NOT_GIVEN
    prompt_name = prompt.name
    create_new_prompt = True
    prompt_def = None

    # If we found a matching revision, check if metadata is the same
    if resp.prompt_revisions:
        log.debug("Found %d revisions with matching body hash", len(resp.prompt_revisions))
        prompt_id = resp.prompt_revisions[0].prompt_definition_id
        create_new_prompt = False

        resp_pd = await cli.list_definitions(prompt_id=prompt_id, limit=1)
        if not resp_pd.prompt_definitions:
            raise PromptProviderError(
                "Prompt revision has been found but prompt definition was not found. This should not happen"
            )
        prompt_def = resp_pd.prompt_definitions[0]

        # Check if the provided description is different from existing one and warn if so
        if prompt.description is not None and prompt.description != prompt_def.description:
            warnings.warn(
                f"Prompt description ({prompt.description!r}) differs from the existing one "
                f"({prompt_def.description!r}). The description won't be updated."
            )

        new_metadata_cmp = json.dumps(prompt.metadata, sort_keys=True)
        for rev in resp.prompt_revisions:
            metadata_cmp = json.dumps(rev.metadata, sort_keys=True)
            if new_metadata_cmp == metadata_cmp:
                log.debug("Found existing revision with matching metadata, returning revision %d", rev.revision)
                return self._api_provider._create_loaded_prompt(
                    prompt_revision=rev,
                    prompt_def=prompt_def,
                    engine=resolved_engine,
                )

        # For existing prompt, don't need name/project
        prompt_name = patronus_api.NOT_GIVEN
        project_name = patronus_api.NOT_GIVEN
    else:
        # No matching revisions found, will create new prompt
        log.debug("No revisions with matching body hash found, creating new prompt and revision")

    # Create a new revision with appropriate parameters
    log.debug(
        "Creating new revision (new_prompt=%s, prompt_id=%s, prompt_name=%s)",
        create_new_prompt,
        prompt_id if prompt_id != patronus_api.NOT_GIVEN else "NOT_GIVEN",
        prompt_name if prompt_name != patronus_api.NOT_GIVEN else "NOT_GIVEN",
    )
    resp = await cli.create_revision(
        body=prompt.body,
        prompt_id=prompt_id,
        prompt_name=prompt_name,
        project_name=project_name if create_new_prompt else patronus_api.NOT_GIVEN,
        prompt_description=prompt.description,
        metadata=prompt.metadata,
    )

    prompt_revision = resp.prompt_revision

    # If we created a new prompt, we need to fetch the definition
    if create_new_prompt:
        resp_pd = await cli.list_definitions(prompt_id=prompt_revision.prompt_definition_id, limit=1)
        if not resp_pd.prompt_definitions:
            raise PromptProviderError(
                "Prompt revision has been created but prompt definition was not found. This should not happen"
            )
        prompt_def = resp_pd.prompt_definitions[0]

    return self._api_provider._create_loaded_prompt(prompt_revision, prompt_def, resolved_engine)

models

BasePrompt

with_engine 
with_engine(
    engine: Union[TemplateEngine, DefaultTemplateEngines],
) -> typing.Self

Create a new prompt with the specified template engine.

Parameters:

Name Type Description Default
engine Union[TemplateEngine, DefaultTemplateEngines]

Either a TemplateEngine instance or a string identifier ('f-string', 'mustache', 'jinja2')

 required

Returns:

Type Description
Self

A new prompt instance with the specified engine
Source code in src/patronus/prompts/models.py 
19
20
21
22
23
24
25
26
27
28
29
30
def with_engine(self, engine: Union[TemplateEngine, DefaultTemplateEngines]) -> typing.Self:
    """
    Create a new prompt with the specified template engine.

    Args:
        engine: Either a TemplateEngine instance or a string identifier ('f-string', 'mustache', 'jinja2')

    Returns:
        A new prompt instance with the specified engine
    """
    resolved_engine = get_template_engine(engine)
    return dataclasses.replace(self, _engine=resolved_engine)
render 
render(**kwargs: Any) -> str

Render the prompt template with the provided arguments.

If no engine is set on the prompt, the default engine from context/config will be used. If no arguments are provided, the template body is returned as-is.

Parameters:

Name Type Description Default
**kwargs Any

Template arguments to be rendered in the prompt body

 {}

Returns:

Type Description
str

The rendered prompt
Source code in src/patronus/prompts/models.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
def render(self, **kwargs: Any) -> str:
    """
    Render the prompt template with the provided arguments.

    If no engine is set on the prompt, the default engine from context/config will be used.
    If no arguments are provided, the template body is returned as-is.

    Args:
        **kwargs: Template arguments to be rendered in the prompt body

    Returns:
        The rendered prompt
    """
    if not kwargs:
        return self.body

    engine = self._engine
    if engine is None:
        # Get default engine from context
        engine_name = context.get_prompts_config().templating_engine
        engine = get_template_engine(engine_name)

    return engine.render(self.body, **kwargs)

calculate_normalized_body_hash 

calculate_normalized_body_hash(body: str) -> str

Calculate the SHA-256 hash of normalized prompt body.

Normalization is done by stripping whitespace from the start and end of the body.

Parameters:

Name Type Description Default
body str

The prompt body

 required

Returns:

Type Description
str

SHA-256 hash of the normalized body
Source code in src/patronus/prompts/models.py 
87
88
89
90
91
92
93
94
95
96
97
98
99
def calculate_normalized_body_hash(body: str) -> str:
    """Calculate the SHA-256 hash of normalized prompt body.

    Normalization is done by stripping whitespace from the start and end of the body.

    Args:
        body: The prompt body

    Returns:
        SHA-256 hash of the normalized body
    """
    normalized_body = body.strip()
    return hashlib.sha256(normalized_body.encode()).hexdigest()

templating

TemplateEngine

Bases: ABC

render abstractmethod 
render(template: str, **kwargs) -> str

Render the template with the given arguments.

Source code in src/patronus/prompts/templating.py 
 9
10
11
@abc.abstractmethod
def render(self, template: str, **kwargs) -> str:
    """Render the template with the given arguments."""

get_template_engine 

get_template_engine(
    engine: Union[TemplateEngine, DefaultTemplateEngines],
) -> TemplateEngine

Convert a template engine name to an actual engine instance.

Parameters:

Name Type Description Default
engine Union[TemplateEngine, DefaultTemplateEngines]

Either a template engine instance or a string identifier ('f-string', 'mustache', 'jinja2')

 required

Returns:

Type Description
TemplateEngine

A template engine instance

Raises:

Type Description
ValueError

If the provided engine string is not recognized
Source code in src/patronus/prompts/templating.py 
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
80
def get_template_engine(engine: Union[TemplateEngine, DefaultTemplateEngines]) -> TemplateEngine:
    """
    Convert a template engine name to an actual engine instance.

    Args:
        engine: Either a template engine instance or a string identifier ('f-string', 'mustache', 'jinja2')

    Returns:
        A template engine instance

    Raises:
        ValueError: If the provided engine string is not recognized
    """
    if isinstance(engine, TemplateEngine):
        return engine

    if engine == "f-string":
        return FStringTemplateEngine()
    elif engine == "mustache":
        return MustacheTemplateEngine()
    elif engine == "jinja2":
        return Jinja2TemplateEngine()

    raise ValueError(
        "Provided engine must be an instance of TemplateEngine or "
        "one of the default engines ('f-string', 'mustache', 'jinja2'). "
        f"Instead got {engine!r}"
    )