46 lines
3.3 KiB
Markdown
46 lines
3.3 KiB
Markdown
# skill-embedding-retrieval Specification
|
|
|
|
## Purpose
|
|
TBD - created by archiving change skill-learning-runtime. Update Purpose after archive.
|
|
## Requirements
|
|
### Requirement: Skill text embedded on synthesis and re-synthesis
|
|
The system SHALL compute and persist an embedding vector for each locally-authored skill's name, description, and originating goal text whenever that skill is first synthesized or a new version is stored, associated with that skill's id and version.
|
|
|
|
#### Scenario: New skill gains an embedding
|
|
- **WHEN** a flow-template skill is synthesized for the first time
|
|
- **THEN** the system computes an embedding vector from its name, description, and originating goal, and stores it alongside the skill record
|
|
|
|
#### Scenario: New version gains its own embedding
|
|
- **WHEN** a new version of an existing skill is created
|
|
- **THEN** the system computes and stores an embedding for that version, independent of any embedding stored for prior versions
|
|
|
|
### Requirement: Embedding failure degrades to non-retrievable-by-similarity, never blocks synthesis
|
|
The system SHALL NOT allow an embedding-provider failure (timeout, rate limit, disabled configuration, connection error) to prevent a skill from being synthesized or versioned; on such failure, the skill SHALL be stored without a similarity-searchable embedding.
|
|
|
|
#### Scenario: Embedding call fails but skill is still stored
|
|
- **WHEN** the embedding provider call fails or times out during synthesis of an otherwise-successful skill
|
|
- **THEN** the skill's flow-template record is still stored, and it is retrievable by exact name/id lookup but excluded from similarity-based retrieval results until a subsequent embedding attempt succeeds
|
|
|
|
### Requirement: Ranked retrieval of candidate skills by goal similarity
|
|
The system SHALL provide a function that, given a new goal string and a requested result count, returns locally-authored skills that have a stored embedding, ranked by descending semantic similarity between the goal and each skill's stored embedding.
|
|
|
|
#### Scenario: Similar goal returns matching skill highest-ranked
|
|
- **WHEN** a new goal is semantically similar to a previously-learned skill's originating goal
|
|
- **THEN** that skill appears in the ranked candidate results, ordered ahead of less-similar skills
|
|
|
|
#### Scenario: Requested count limits results
|
|
- **WHEN** a caller requests the top `k` candidate skills for a goal
|
|
- **THEN** the system returns at most `k` ranked results, even if more embedded skills exist
|
|
|
|
#### Scenario: No embedded skills yields an empty result
|
|
- **WHEN** no locally-authored skill currently has a stored embedding
|
|
- **THEN** the retrieval function returns an empty ranked list rather than raising an error
|
|
|
|
### Requirement: Retrieval scoped to locally-authored skills unless explicitly extended
|
|
The system SHALL restrict ranked candidate retrieval to skills stored by this capability's own local-synthesis store by default, and SHALL treat inclusion of externally-synced skills as a separate, explicit extension rather than an implicit default.
|
|
|
|
#### Scenario: Default retrieval excludes synced-only skills without embeddings
|
|
- **WHEN** the skill catalog contains externally-synced skills that have never been embedded by this capability
|
|
- **THEN** ranked candidate retrieval returns only locally-authored skills with stored embeddings, without erroring on the presence of unembedded synced skills
|
|
|