chore: import upstream snapshot with attribution

docs/python/resource/langfuse.mdx

@@ -0,0 +1,227 @@
+---
+title: Langfuse
+description: Mount Langfuse traces, observations, prompts, datasets, and scores as a Mirage virtual filesystem.
+icon: chart-line
+---
+The Langfuse resource exposes LLM observability data (traces, observations,
+prompts, datasets, scores) as a virtual filesystem mounted at some prefix
+such as `/langfuse/`.
+
+For credential setup, see [Langfuse Setup](/python/setup/langfuse).
+
+## Config
+
+```python
+import os
+
+from mirage import MountMode, Workspace
+from mirage.resource.langfuse import LangfuseConfig, LangfuseResource
+
+config = LangfuseConfig(
+    public_key=os.environ["LANGFUSE_PUBLIC_KEY"],
+    secret_key=os.environ["LANGFUSE_SECRET_KEY"],
+    host=os.environ.get("LANGFUSE_HOST", "https://cloud.langfuse.com"),
+)
+resource = LangfuseResource(config=config)
+ws = Workspace({"/langfuse": resource}, mode=MountMode.READ)
+```
+
+| Config field           | Required | Default                      | Description                                      |
+| ---------------------- | -------- | ---------------------------- | ------------------------------------------------ |
+| `public_key`           | yes      |                              | Langfuse project public key                      |
+| `secret_key`           | yes      |                              | Langfuse project secret key                      |
+| `host`                 | no       | `https://cloud.langfuse.com` | Langfuse API host URL                            |
+| `default_trace_limit`  | no       | 100                          | Default trace/observation cap for listings       |
+| `default_search_limit` | no       | 50                           | Default result cap for search at directory scope |
+
+## Filesystem Layout
+
+```text
+/langfuse/
+  traces/
+    <trace-id>.json
+    ...
+  sessions/
+    <session-id>/
+      <trace-id>.json
+      ...
+  prompts/
+    <prompt-name>/
+      <version>.json
+      ...
+  datasets/
+    <dataset-name>/
+      items.jsonl
+      runs/
+        <run-name>.jsonl
+        ...
+```
+
+Example:
+
+```text
+/langfuse/
+  traces/
+    abc123.json
+    def456.json
+  sessions/
+    chat-session-1/
+      abc123.json
+      ghi789.json
+  prompts/
+    summarize/
+      1.json
+      2.json
+    classify/
+      1.json
+  datasets/
+    eval-v1/
+      items.jsonl
+      runs/
+        run-2026-04-01.jsonl
+```
+
+### Traces
+
+`/langfuse/traces/` lists recent traces (capped at `default_trace_limit`).
+Each trace is a `.json` file containing the full trace object with nested
+observations (spans, generations, events).
+
+### Sessions
+
+`/langfuse/sessions/` groups traces by session ID. Each session directory
+contains trace `.json` files belonging to that session.
+
+### Prompts
+
+`/langfuse/prompts/` lists prompt names as directories. Each prompt directory
+contains version files (`1.json`, `2.json`, etc.) with the prompt content
+and metadata.
+
+### Datasets
+
+`/langfuse/datasets/` lists dataset names as directories. Each contains
+`items.jsonl` (dataset items) and `runs/` with run results.
+
+## Smart Commands
+
+### grep at different scopes
+
+```bash
+# FILE level - downloads the file, greps locally
+grep "error" "/langfuse/traces/abc123.json"
+
+# TRACES level - uses Langfuse trace filter API (name, tags, metadata)
+grep "error" "/langfuse/traces/"
+
+# SESSIONS level - uses Langfuse session listing
+grep "chat" "/langfuse/sessions/"
+
+# PROMPTS level - filters prompt names
+grep "classify" "/langfuse/prompts/"
+
+# ROOT level - searches across all resource types
+grep "error" "/langfuse/"
+```
+
+At directory scope, the resource uses Langfuse's filter API instead of
+downloading data:
+
+- **traces/**: filters by trace name, user ID, or tags
+- **sessions/**: filters by session listing
+- **prompts/**: filters by prompt name
+
+### head / tail
+
+`head` and `tail` on `traces/` use Langfuse API pagination with sort order
+instead of downloading all traces:
+
+```bash
+# Returns 10 most recent traces
+head -n 10 "/langfuse/traces/"
+
+# Returns 10 oldest traces
+tail -n 10 "/langfuse/traces/"
+```
+
+## Limits
+
+| Command                  | Limit behavior                                       |
+| ------------------------ | ---------------------------------------------------- |
+| `ls traces/`             | Returns up to `default_trace_limit` traces           |
+| `cat traces/<id>.json`   | Full trace (single doc, no limit needed)             |
+| `grep` (directory level) | Server-side filter, capped at `default_search_limit` |
+| `wc -l traces/`          | Not supported (Langfuse has no count endpoint)       |
+
+## Cache
+
+The Langfuse resource uses `IndexCacheStore` (same as other resources).
+Index entries store trace IDs, session IDs, and prompt names.
+
+## Example
+
+```python
+import asyncio
+import os
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.langfuse import LangfuseConfig, LangfuseResource
+
+load_dotenv(".env.development")
+
+config = LangfuseConfig(
+    public_key=os.environ["LANGFUSE_PUBLIC_KEY"],
+    secret_key=os.environ["LANGFUSE_SECRET_KEY"],
+)
+resource = LangfuseResource(config=config)
+
+
+async def main():
+    ws = Workspace({"/langfuse": resource}, mode=MountMode.READ)
+
+    # List top-level resources
+    r = await ws.execute("ls /langfuse/")
+    print(await r.stdout_str())
+
+    # List recent traces
+    r = await ws.execute("ls /langfuse/traces/")
+    print(await r.stdout_str())
+
+    # Read a specific trace
+    traces = r.stdout_str().strip().splitlines()
+    if traces:
+        r = await ws.execute(f'cat "/langfuse/traces/{traces[0]}"')
+        print(r.stdout_str()[:500])
+
+    # List prompts
+    r = await ws.execute("ls /langfuse/prompts/")
+    print(await r.stdout_str())
+
+    # Search traces (uses Langfuse filter API)
+    r = await ws.execute('grep "error" "/langfuse/traces/"')
+    print(await r.stdout_str())
+
+    # List datasets
+    r = await ws.execute("ls /langfuse/datasets/")
+    print(await r.stdout_str())
+
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Shell Commands
+
+| Command         | Notes                                                  |
+| --------------- | ------------------------------------------------------ |
+| `ls`            | List traces, sessions, prompts, datasets               |
+| `cat`           | Read trace JSON, prompt version, dataset items         |
+| `head` / `tail` | Paginated trace listing with sort                      |
+| `grep` / `rg`   | Smart: uses Langfuse filter API at directory scope     |
+| `jq`            | Query JSON trace/prompt data                           |
+| `stat`          | Metadata (trace count, prompt versions, dataset items) |
+| `find`          | Search across resources with `-name`                   |
+| `tree`          | Directory tree view                                    |