Skip to content

Commit ab849fc

Browse files
committed
fix(skills): simplify propagation and improve discovery
1 parent 207d877 commit ab849fc

10 files changed

Lines changed: 193 additions & 159 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -79,8 +79,8 @@ Discovery reads `langfuse-skills.lock` from the skills directory, falling back t
7979
Fetch skill contents through the generated API.
8080

8181
```python
82-
skill = langfuse.api.unstable.skills.get("refund-policy", label="production", include_content=True)
83-
skill = await langfuse.async_api.unstable.skills.get("refund-policy", include_content=True)
82+
skill = langfuse.api.skills.get("refund-policy", label="production", include_content=True)
83+
skill = await langfuse.async_api.skills.get("refund-policy", include_content=True)
8484
```
8585

8686
## Docs

‎langfuse/_client/client.py‎

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,6 @@
4343
from langfuse._client.attributes import (
4444
LangfuseOtelSpanAttributes,
4545
_serialize,
46-
create_available_skills_attributes,
4746
)
4847
from langfuse._client.constants import (
4948
LANGFUSE_SDK_EXPERIMENT_ENVIRONMENT,
@@ -708,7 +707,6 @@ def start_observation(
708707
):
709708
otel_span = self._otel_tracer.start_span(
710709
name=name,
711-
attributes=create_available_skills_attributes(available_skills),
712710
)
713711
_set_span_attributes_within_limit(
714712
otel_span, {LangfuseOtelSpanAttributes.AS_ROOT: True}
@@ -732,9 +730,7 @@ def start_observation(
732730
prompt=prompt,
733731
)
734732

735-
otel_span = self._otel_tracer.start_span(
736-
name=name, attributes=create_available_skills_attributes(available_skills)
737-
)
733+
otel_span = self._otel_tracer.start_span(name=name)
738734

739735
return self._create_observation_from_otel_span(
740736
otel_span=otel_span,
@@ -1356,7 +1352,6 @@ def _start_as_current_otel_span_with_processed_media(
13561352
prompt: Optional[PromptClient] = None,
13571353
) -> Any:
13581354
with self._otel_tracer.start_as_current_span(
1359-
attributes=create_available_skills_attributes(available_skills),
13601355
name=name,
13611356
end_on_exit=end_on_exit if end_on_exit is not None else True,
13621357
) as otel_span:
@@ -1668,7 +1663,6 @@ def create_event(
16681663
cast(otel_trace_api.Span, remote_parent_span)
16691664
):
16701665
otel_span = self._otel_tracer.start_span(
1671-
attributes=create_available_skills_attributes(available_skills),
16721666
name=name,
16731667
start_time=timestamp,
16741668
)
@@ -1696,7 +1690,6 @@ def create_event(
16961690
otel_span = self._otel_tracer.start_span(
16971691
name=name,
16981692
start_time=timestamp,
1699-
attributes=create_available_skills_attributes(available_skills),
17001693
)
17011694

17021695
return cast(

‎langfuse/_client/propagation.py‎

Lines changed: 6 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -103,9 +103,6 @@ class PropagatedExperimentAttributes(TypedDict):
103103
experiment_item_root_observation_id: str
104104

105105

106-
_ATTACH_SKILLS_CONTEXT_KEY = otel_context_api.create_key("langfuse_attach_skills")
107-
108-
109106
def _detach_context_token_safely(token: Any) -> None:
110107
"""Detach a context token without emitting noisy async teardown errors.
111108
@@ -195,9 +192,10 @@ def propagate_attributes(
195192
`Langfuse(environment=...)` or `LANGFUSE_TRACING_ENVIRONMENT` for spans
196193
created while this propagation context is active.
197194
skills_available: Skill references with name and optional version; replaces
198-
the inherited catalog, including when empty. Never sent as baggage.
199-
attach_skills: Attach the configured skill catalog to new spans
200-
in this context; disabled by default. Never sent as baggage.
195+
skills on the current span and in inherited context, including when empty.
196+
Never sent as baggage.
197+
attach_skills: Attach the configured skill catalog to spans
198+
created in this context; disabled by default. Never sent as baggage.
201199
as_baggage: If True, propagates attributes using OpenTelemetry baggage for
202200
cross-process/service propagation. **Security warning**: When enabled,
203201
attribute values are added to HTTP headers on ALL outbound requests.
@@ -363,7 +361,7 @@ def _propagate_attributes(
363361
)
364362
if isinstance(attach_skills, bool):
365363
context = otel_context_api.set_value(
366-
key=_ATTACH_SKILLS_CONTEXT_KEY,
364+
key=_get_propagated_context_key("attach_skills"),
367365
value=attach_skills,
368366
context=context,
369367
)
@@ -520,13 +518,7 @@ def _get_propagated_attributes_from_context(
520518
# Handle baggage
521519
baggage_entries = baggage.get_all(context=context)
522520
for baggage_key, baggage_value in baggage_entries.items():
523-
if baggage_key in (
524-
LANGFUSE_TRACE_ID_BAGGAGE_KEY,
525-
"langfuse_skills_available",
526-
"langfuse_attach_skills",
527-
"langfuse_available_skills",
528-
"langfuse_attach_discovered_skills",
529-
):
521+
if baggage_key == LANGFUSE_TRACE_ID_BAGGAGE_KEY:
530522
continue
531523

532524
if baggage_key.startswith(LANGFUSE_BAGGAGE_PREFIX):

‎langfuse/_client/skills.py‎

Lines changed: 35 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -15,31 +15,51 @@
1515
def discover_skills(*, dir: str) -> list[SkillReference]:
1616
"""Read immediate skill directories and optional CLI installation metadata.
1717
18-
Directories must contain a regular SKILL.md file. Hidden directories and
19-
symlinks are skipped. The configured directory's langfuse-skills.lock takes
20-
precedence over the working directory's lock. Unlocked skills use their
21-
directory name without a version. Lock records do not verify local edits.
22-
23-
Missing directories return an empty list. Unreadable directories or malformed
24-
lockfiles raise; invalid individual lock entries and duplicate names are skipped.
18+
Directories must contain a regular SKILL.md file. Hidden directories are
19+
skipped and symlinks are followed. The configured directory's
20+
langfuse-skills.lock takes precedence over the working directory's lock.
21+
Unlocked skills use their directory name without a version. Lock records
22+
do not verify local edits.
23+
24+
Missing directories return an empty list. Unreadable or malformed lockfiles
25+
warn and fall back to directory names. Entries that cannot be inspected,
26+
invalid lock entries, and duplicate names are skipped with a warning.
2527
"""
2628
root = Path(os.path.abspath(dir))
2729
if _stat_if_exists(root) is None:
2830
return []
2931

30-
locked = _read_cli_lock(_find_cli_lock(root))
32+
locked: dict[Path, SkillReference] = {}
33+
try:
34+
locked = _read_cli_lock(_find_cli_lock(root))
35+
except (OSError, ValueError) as error:
36+
langfuse_logger.warning(
37+
"Could not read skill lockfile for %s. Using directory names without versions: %s",
38+
root,
39+
error,
40+
)
3141
available: dict[str, SkillReference] = {}
3242
with os.scandir(root) as entries:
3343
candidates = sorted(entries, key=lambda entry: entry.name)
3444
for candidate in candidates:
35-
if candidate.name.startswith(".") or not candidate.is_dir(
36-
follow_symlinks=False
37-
):
45+
if candidate.name.startswith("."):
3846
continue
39-
skill_file = _stat_if_exists(Path(candidate.path) / "SKILL.md")
40-
if skill_file is None or not stat.S_ISREG(skill_file.st_mode):
47+
directory = Path(candidate.path)
48+
try:
49+
directory_stat = _stat_if_exists(directory)
50+
if directory_stat is None or not stat.S_ISDIR(directory_stat.st_mode):
51+
continue
52+
skill_file = _stat_if_exists(directory / "SKILL.md")
53+
if skill_file is None or not stat.S_ISREG(skill_file.st_mode):
54+
continue
55+
except OSError as error:
56+
langfuse_logger.warning(
57+
"Skipping skill directory %s: could not inspect files: %s",
58+
directory,
59+
error,
60+
)
4161
continue
42-
skill = locked.get(Path(candidate.path), {"name": candidate.name})
62+
skill = locked.get(directory, {"name": candidate.name})
4363
name = skill["name"]
4464
if len(name) > 128:
4565
langfuse_logger.warning(
@@ -55,7 +75,7 @@ def discover_skills(*, dir: str) -> list[SkillReference]:
5575

5676
def _stat_if_exists(path: Path) -> Optional[os.stat_result]:
5777
try:
58-
return path.lstat()
78+
return path.stat()
5979
except FileNotFoundError:
6080
return None
6181

@@ -80,7 +100,6 @@ def _read_cli_lock(file: Optional[Path]) -> dict[Path, SkillReference]:
80100
if (
81101
not isinstance(value, dict)
82102
or type(value.get("lockVersion")) is not int
83-
or value["lockVersion"] != 1
84103
or not isinstance(value.get("skills"), list)
85104
):
86105
message = f"Unsupported or invalid skill lockfile {file}."

‎langfuse/_client/span.py‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,6 @@
4141

4242
from langfuse._client.attributes import (
4343
LangfuseOtelSpanAttributes,
44-
create_available_skills_attributes,
4544
create_generation_attributes,
4645
create_span_attributes,
4746
create_trace_attributes,
@@ -1178,7 +1177,6 @@ def start_observation(
11781177
with otel_trace_api.use_span(self._otel_span):
11791178
new_otel_span = self._langfuse_client._otel_tracer.start_span(
11801179
name=name,
1181-
attributes=create_available_skills_attributes(available_skills),
11821180
)
11831181

11841182
common_args = {
@@ -1469,7 +1467,6 @@ def create_event(
14691467

14701468
with otel_trace_api.use_span(self._otel_span):
14711469
new_otel_span = self._langfuse_client._otel_tracer.start_span(
1472-
attributes=create_available_skills_attributes(available_skills),
14731470
name=name,
14741471
start_time=timestamp,
14751472
)

‎langfuse/_client/span_processor.py‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,9 @@
3838
LANGFUSE_OTEL_TRACES_EXPORT_PATH,
3939
)
4040
from langfuse._client.propagation import (
41-
_ATTACH_SKILLS_CONTEXT_KEY,
4241
_get_langfuse_trace_id_from_baggage,
4342
_get_propagated_attributes_from_context,
43+
_get_propagated_context_key,
4444
)
4545
from langfuse._client.skills import serialize_available_skills
4646
from langfuse._client.span import _set_span_attributes_within_limit
@@ -252,13 +252,16 @@ def on_start(self, span: Span, parent_context: Optional[Context] = None) -> None
252252
}
253253

254254
skills_key = LangfuseOtelSpanAttributes.OBSERVATION_SKILLS_AVAILABLE
255+
# Existing span skills take precedence over propagation, then configured skills.
255256
if skills_key in existing_attributes:
256257
propagated_attributes.pop(skills_key, None)
257258
elif (
258259
skills_key not in propagated_attributes
259260
and self._available_skills is not None
260261
and (not is_langfuse_span(span) or self._is_langfuse_project_span(span))
261-
and context_api.get_value(_ATTACH_SKILLS_CONTEXT_KEY, context=context)
262+
and context_api.get_value(
263+
_get_propagated_context_key("attach_skills"), context=context
264+
)
262265
is True
263266
):
264267
propagated_attributes[skills_key] = self._available_skills

‎tests/unit/test_api_skills.py‎

Lines changed: 0 additions & 76 deletions
This file was deleted.

‎tests/unit/test_propagate_attributes.py‎

Lines changed: 34 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -10,12 +10,14 @@
1010
from datetime import datetime
1111

1212
import pytest
13+
from opentelemetry import baggage, context
1314
from opentelemetry.instrumentation.threading import ThreadingInstrumentor
1415

1516
from langfuse import propagate_attributes
1617
from langfuse._client.attributes import LangfuseOtelSpanAttributes, _serialize
1718
from langfuse._client.constants import LANGFUSE_SDK_EXPERIMENT_ENVIRONMENT
1819
from langfuse._client.datasets import DatasetClient
20+
from langfuse._client.propagation import _get_propagated_attributes_from_context
1921
from langfuse.api import Dataset, DatasetItem, DatasetStatus
2022
from tests.unit.test_otel import TestOTelBase
2123

@@ -3860,11 +3862,36 @@ def test_catalog_replaces_inherited_and_updates_current_span(
38603862
LangfuseOtelSpanAttributes.OBSERVATION_SKILLS_AVAILABLE,
38613863
)
38623864

3863-
def test_skills_never_use_baggage(self):
3864-
from opentelemetry import baggage, context
3865-
3866-
from langfuse._client.propagation import _get_propagated_attributes_from_context
3865+
@pytest.mark.parametrize("skills", [[{"name": "refund"}], []])
3866+
@pytest.mark.parametrize("set_on_update", [False, True])
3867+
def test_propagation_updates_current_observation_skills(
3868+
self, langfuse_client, memory_exporter, skills, set_on_update
3869+
):
3870+
inherited = [{"name": "child"}]
3871+
with propagate_attributes(skills_available=[{"name": "outer"}]):
3872+
with langfuse_client.start_as_current_observation(
3873+
name="parent", available_skills=None if set_on_update else skills
3874+
) as parent:
3875+
if set_on_update:
3876+
parent.update(available_skills=skills)
3877+
assert (
3878+
json.loads(
3879+
parent._otel_span.attributes[
3880+
LangfuseOtelSpanAttributes.OBSERVATION_SKILLS_AVAILABLE
3881+
]
3882+
)
3883+
== skills
3884+
)
3885+
with propagate_attributes(skills_available=inherited):
3886+
langfuse_client.start_observation(name="child").end()
3887+
for name, expected in (("parent", inherited), ("child", inherited)):
3888+
_assert_json_attribute(
3889+
self.get_span_by_name(memory_exporter, name),
3890+
LangfuseOtelSpanAttributes.OBSERVATION_SKILLS_AVAILABLE,
3891+
expected,
3892+
)
38673893

3894+
def test_skills_baggage_is_read_but_not_written(self):
38683895
with propagate_attributes(
38693896
skills_available=[{"name": "local"}],
38703897
attach_skills=True,
@@ -3874,16 +3901,9 @@ def test_skills_never_use_baggage(self):
38743901
incoming = baggage.set_baggage(
38753902
"langfuse_skills_available", '[{"name":"remote"}]'
38763903
)
3877-
incoming = baggage.set_baggage(
3878-
"langfuse_attach_skills", "true", context=incoming
3879-
)
3880-
incoming = baggage.set_baggage(
3881-
"langfuse_available_skills", '[{"name":"legacy"}]', context=incoming
3882-
)
3883-
incoming = baggage.set_baggage(
3884-
"langfuse_attach_discovered_skills", "true", context=incoming
3885-
)
3886-
assert not _get_propagated_attributes_from_context(incoming)
3904+
assert _get_propagated_attributes_from_context(incoming) == {
3905+
LangfuseOtelSpanAttributes.OBSERVATION_SKILLS_AVAILABLE: '[{"name":"remote"}]'
3906+
}
38873907
assert not _get_propagated_attributes_from_context(context.get_current())
38883908

38893909
def test_invalid_serialization_keeps_outer_catalog(

0 commit comments

Comments
 (0)