Coverage for haystack/skill_stores/types/protocol.py: 100%

1# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai> 

2# 

3# SPDX-License-Identifier: Apache-2.0 

4 

5from typing import Any, Protocol 

6 

7from haystack.dataclasses.file_content import FileContent 

8from haystack.dataclasses.image_content import ImageContent 

9from haystack.dataclasses.skill_info import SkillInfo 

10 

11 

12class SkillStore(Protocol): 

13 """ 

14 Protocol for a skill storage layer. 

15 

16 A `SkillStore` is responsible for discovering available skills and providing their content on demand. Implement 

17 this protocol to back a `haystack.tools.SkillToolset` with any storage system — a local directory, a database, 

18 a remote API, or an in-memory fixture. 

19 

20 Skills are identified by their `name`, which must be unique within a store. The `name` is the lookup key for every 

21 method below; implementations resolve it to their own internal locator (a directory, a row id, an object key, ...). 

22 

23 Implementations may defer all I/O (filesystem reads, database connections, ...) until a method is actually called, 

24 so a store can be constructed cheaply and only touch its backend on first use. 

25 

26 Skill content is text: instruction bodies and bundled files are returned as strings. Binary assets (images, 

27 fonts, ...) are not supported. 

28 """ 

29 

30 def list_skills(self) -> dict[str, SkillInfo]: 

31 """ 

32 Discover and return all available skills. 

33 

34 :returns: Mapping of skill name to its metadata. 

35 """ 

36 ... 

37 

38 def load_skill(self, name: str) -> tuple[str, list[str]]: 

39 """ 

40 Return the named skill's instruction body and the manifest of its bundled files. 

41 

42 :param name: Skill name as returned by `list_skills`. 

43 :returns: A tuple of (markdown body with frontmatter stripped, sorted list of POSIX-style paths relative 

44 to the skill root for any bundled files). The file list is empty when the skill bundles no extras. 

45 :raises KeyError: If no skill with `name` exists. 

46 """ 

47 ... 

48 

49 def read_skill_file(self, name: str, path: str) -> str | ImageContent | FileContent: 

50 """ 

51 Read a file bundled with the named skill. 

52 

53 Implementations should return text files as a `str`, image files as an `ImageContent`, and PDFs as a 

54 `FileContent`, so a multimodal agent can pass binary assets straight to the model. 

55 

56 :param name: Skill name as returned by `list_skills`. 

57 :param path: Path of the file relative to the skill root (e.g. `"reference/forms.md"`). 

58 :returns: The file's text content (`str`), an `ImageContent` for images, or a `FileContent` for PDFs. 

59 :raises KeyError: If no skill with `name` exists. 

60 :raises FileNotFoundError: If the file does not exist within the skill. 

61 """ 

62 ... 

63 

64 def to_dict(self) -> dict[str, Any]: 

65 """ 

66 Serialize this store to a dictionary for use with `from_dict`. 

67 

68 Implement both this method and `from_dict` to make your custom store serializable. 

69 """ 

70 ... 

71 

72 @classmethod 

73 def from_dict(cls, data: dict[str, Any]) -> "SkillStore": 

74 """ 

75 Deserialize a store from a dictionary produced by `to_dict`. 

76 

77 Implement both this method and `to_dict` to make your custom store serializable. 

78 

79 :param data: Dictionary as produced by `to_dict`. 

80 """ 

81 ...