Skip to content

docs: add missing examples to Python and Node bindings #1266

@chaliy

Description

@chaliy

Context

Node has 5+ runnable examples covering diverse use cases. Python has only 2. Each binding should have equivalent examples demonstrating the same patterns, adapted to language idioms.

This is part of the Python ↔ Node binding parity effort (Phase 4 — Documentation Alignment).

Current state

Example pattern Python (examples/) Node (examples/)
Basic bash usage bash_basics.py bash_basics.ts
Data pipeline data_pipeline.ts
LLM tool usage llm_tool.ts
K8s orchestrator (ScriptedTool) k8s_orchestrator.py
LangChain integration langchain_integration.ts

What to implement

Add to Python (crates/bashkit-python/examples/)

data_pipeline.py — Data processing pipeline example

  • Read/generate sample data (CSV or JSON)
  • Use bash pipelines (sort, uniq, awk, jq) to transform data
  • Demonstrate VFS for intermediate files
  • Show both sync and async execution
  • Mirror the patterns in Node's data_pipeline.ts

llm_tool.py — LLM tool usage example

  • Create a BashTool instance
  • Show tool metadata (description(), input_schema(), output_schema())
  • Demonstrate the execute → result → parse cycle an LLM agent would use
  • Show system_prompt() for LLM context
  • Mirror the patterns in Node's llm_tool.ts

Add to Node (crates/bashkit-js/examples/)

k8s_orchestrator.ts — ScriptedTool orchestration example

  • Create a ScriptedTool with mock K8s API tools (get-pods, get-deployments, scale, etc.)
  • Register 5+ tools with callbacks and schemas
  • Execute a bash script that orchestrates multiple tools via pipes and jq
  • Mirror the patterns in Python's k8s_orchestrator.py

Acceptance criteria

  • data_pipeline.py created and runs successfully: python examples/data_pipeline.py
  • llm_tool.py created and runs successfully: python examples/llm_tool.py
  • k8s_orchestrator.ts created and runs successfully (via ts-node or compiled)
  • Each example has a header comment explaining what it demonstrates
  • Examples are self-contained (no external dependencies beyond bashkit)
  • Examples use realistic, non-trivial patterns (not just "hello world")
  • Python examples follow existing style in bash_basics.py (print output, show both sync/async)
  • Node example follows existing style in other TS examples
  • CI smoke tests updated to run the new examples:
    • Python: add data_pipeline.py and llm_tool.py to .github/workflows/python.yml examples job
    • Node: add k8s_orchestrator.ts to .github/workflows/js.yml examples job

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions