refactor(examples): consolidate 16 examples into 12

Merge narrow/related examples and remove developer-internals files:

- 04_resources_and_retrieval.py: merge resource management + tool retrieval
- 06_agent_identity.py: rename from 08 (content unchanged)
- 07_skills.py: renumber from 10_skills
- 08_human_in_the_loop.py: renumber from 07
- 09_async_and_streaming.py: merge arun()/gather and run_stream() with
  "Which method to use" preamble distinguishing the two patterns
- 10_error_handling.py: renumber from 11
- 11_multi_agent.py: renumber from 13
- 12_persistence.py: renumber from 16
- Delete 09_repl_isolation.py and 10_extract_subgraph.py (internals)
- Update README to document all 12 examples

Author: BinglanLi

examples/04_resource_management.py

@@ -0,0 +1,93 @@
+"""
+Resource Management and Tool Retrieval
+=======================================
+
+BaseAgent exposes a ResourceManager that tracks data sources, libraries, and
+tools.  You can register custom data and libraries so the agent can reference
+them when planning tasks, and optionally enable automatic tool selection.
+
+DataLakeItem  — a dataset the agent can read (CSV, Parquet, etc.)
+Library       — a Python/R package or CLI tool the agent can use
+use_tool_retriever — when True, the agent embeds available tools and selects
+                     relevant ones by semantic similarity before each run,
+                     instead of passing the full tool list.
+"""
+
+from BaseAgent import BaseAgent
+from BaseAgent.resources import DataLakeItem, Library
+
+# ---------------------------------------------------------------------------
+# 1. Register data sources and libraries
+# ---------------------------------------------------------------------------
+agent = BaseAgent()
+
+agent.resource_manager.add_data_item(
+    DataLakeItem(
+        filename="my_dataset.csv",
+        description="Custom dataset for protein analysis",
+        format="csv",
+        category="research",
+        path="/path/to/my_dataset.csv",
+    )
+)
+
+agent.resource_manager.add_data_item(
+    DataLakeItem(
+        filename="experiment_results.parquet",
+        description="Results from experiment batch #42",
+        format="parquet",
+        category="experiments",
+        size_mb=125.5,
+        path="/path/to/experiment_results.parquet",
+    )
+)
+
+agent.resource_manager.add_library(
+    Library(
+        name="custom_analysis_lib",
+        description="Custom library for advanced protein analysis",
+        type="Python",
+        version="2.1.0",
+        category="analysis",
+        installation_cmd="pip install custom-analysis-lib",
+    )
+)
+
+# Query the registered resources
+print("=== Available Data Sources ===")
+for data in agent.resource_manager.get_all_data():
+    print(f"- {data.filename}: {data.description}")
+
+print("\n=== Python Libraries ===")
+for lib in agent.resource_manager.filter_libraries_by_type("Python")[:5]:
+    print(f"- {lib.name} ({lib.version}): {lib.description}")
+
+summary = agent.resource_manager.get_summary()
+print(f"\n=== Resource Summary ===")
+print(f"Tools: {summary['tools']['total']}")
+print(f"Data Sources: {summary['data']['total']}")
+print(f"Libraries: {summary['libraries']['total']}")
+
+_, result = agent.run("Analyse my_dataset.csv using custom_analysis_lib")
+print(f"\n=== Agent Result ===\n{result}")
+
+# ---------------------------------------------------------------------------
+# 2. Automatic tool selection (tool retriever)
+# ---------------------------------------------------------------------------
+# With use_tool_retriever=True the agent ranks tools by semantic similarity
+# to the task and passes only the top matches to the LLM — useful when the
+# full tool list is large.
+retriever_agent = BaseAgent(
+    llm="claude-sonnet-4-20250514",
+    use_tool_retriever=True,
+)
+
+_, result = retriever_agent.run(
+    "Analyze protein sequences and calculate binding affinities."
+)
+print(result)
+
+# You can also pin a specific tool subset for a single run.
+retriever_agent.resource_manager.select_tools_by_names(["run_python_repl"])
+_, result = retriever_agent.run("Run a quick Python calculation.")
+print(result)

examples/04_resources_and_retrieval.py

@@ -15,6 +15,10 @@
 Single skill:  full body always injected into the system prompt.
 Multiple skills: catalog mode (name + description only) shown initially;
   the retrieve node selects relevant skills per task and injects full bodies.
+
+Run this script from the repo root::
+
+    python examples/07_skills.py
 """
 
 from BaseAgent import BaseAgent, Skill

examples/08_agent_identity.py examples/06_agent_identity.pyexamples/08_agent_identity.py renamed to examples/06_agent_identity.py

@@ -10,6 +10,10 @@
 After agent.run() returns, check agent.is_interrupted:
   True  → a code block is waiting for review; call resume() or reject(feedback)
   False → the agent finished normally; the second return value is the final answer
+
+Run this script from the repo root::
+
+    python examples/08_human_in_the_loop.py
 """
 
 from BaseAgent import BaseAgent
@@ -55,4 +59,3 @@
         print("Final answer:", answer)
     else:
         print("Final answer:", payload2)
-

examples/06_tool_retrieval.py

@@ -0,0 +1,130 @@
+"""Example 9: Async API and streaming events.
+
+Which method to use
+-------------------
+arun()        — async equivalent of run(); returns (log, content) when the
+                agent finishes.  Use inside async orchestrators, web servers,
+                or when running multiple agents concurrently with asyncio.gather().
+run_stream()  — async generator that yields AgentEvent objects *during*
+                execution.  Use when you need real-time visibility into
+                reasoning, code execution, and errors (e.g. feeding a UI or
+                collecting a fine-grained trace).
+
+Both require an async context (async def / asyncio.run()).
+
+Run this script from the repo root::
+
+    python examples/09_async_and_streaming.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from BaseAgent import BaseAgent, EventType
+
+
+# ===========================================================================
+# Part A — arun(), aresume(), areject()
+# ===========================================================================
+
+async def basic_async_run():
+    """arun() returns (log, content) just like run()."""
+    agent = BaseAgent(llm="claude-sonnet-4-20250514")
+    log, answer = await agent.arun("What is 2 + 2?")
+    print("Answer:", answer)
+    print(f"Log entries: {len(log)}")
+
+
+async def async_hitl():
+    """HITL workflow using arun() / aresume() / areject()."""
+    agent = BaseAgent(
+        llm="claude-sonnet-4-20250514",
+        require_approval="always",
+    )
+
+    _, payload = await agent.arun("Compute the sum of 1 through 10 in Python.")
+
+    if agent.is_interrupted:
+        print("Code pending approval:")
+        if isinstance(payload, dict):
+            print(payload.get("code", ""))
+
+        # --- Option A: approve ---
+        _, answer = await agent.aresume()
+        print("Approved. Final answer:", answer)
+
+        # --- Option B: reject with feedback (commented out) ---
+        # _, payload2 = await agent.areject("Use a list comprehension instead.")
+        # if not agent.is_interrupted:
+        #     print("After feedback:", payload2)
+    else:
+        print("Completed without interruption:", payload)
+
+
+async def concurrent_agents():
+    """Run two independent agents concurrently with asyncio.gather()."""
+    agent_a = BaseAgent(llm="claude-sonnet-4-20250514")
+    agent_b = BaseAgent(llm="claude-sonnet-4-20250514")
+
+    (_, ans_a), (_, ans_b) = await asyncio.gather(
+        agent_a.arun("What is the capital of France?"),
+        agent_b.arun("What is the capital of Germany?"),
+    )
+    print("Agent A:", ans_a)
+    print("Agent B:", ans_b)
+
+
+# ===========================================================================
+# Part B — run_stream() and AgentEvent
+# ===========================================================================
+
+async def stream_all_events():
+    """Print every event emitted during a run."""
+    agent = BaseAgent(llm="claude-sonnet-4-20250514", require_approval="never")
+
+    print("=== All events ===")
+    async for event in agent.run_stream("What is the GC content of the sequence ATCGATCG?"):
+        print(f"[{event.event_type.value:20s}] {event.content[:120]}")
+
+
+async def stream_filtered_events():
+    """Receive only THINKING and FINAL_ANSWER events."""
+    agent = BaseAgent(llm="claude-sonnet-4-20250514", require_approval="never")
+
+    print("\n=== Filtered: THINKING + FINAL_ANSWER only ===")
+    async for event in agent.run_stream(
+        "Summarise the role of BRCA1 in DNA repair.",
+        event_types={EventType.THINKING, EventType.FINAL_ANSWER},
+    ):
+        label = "Reasoning" if event.event_type == EventType.THINKING else "Answer"
+        print(f"[{label}] {event.content[:200]}")
+
+
+async def stream_to_json():
+    """Serialise each event to JSON (useful for WebSocket / SSE payloads)."""
+    agent = BaseAgent(llm="claude-sonnet-4-20250514", require_approval="never")
+
+    print("\n=== JSON payloads ===")
+    async for event in agent.run_stream(
+        "Name three model organisms used in genetics research.",
+        event_types={EventType.FINAL_ANSWER},
+    ):
+        print(event.to_json())
+
+
+if __name__ == "__main__":
+    print("=== Basic async run ===")
+    asyncio.run(basic_async_run())
+
+    print("\n=== Async HITL ===")
+    asyncio.run(async_hitl())
+
+    print("\n=== Concurrent agents ===")
+    asyncio.run(concurrent_agents())
+
+    print("\n=== Streaming: all events ===")
+    asyncio.run(stream_all_events())
+
+    asyncio.run(stream_filtered_events())
+    asyncio.run(stream_to_json())