EchoBot Documentation

To reuse a browser instance, maintain cookies, and keep a consistent fingerprint across multiple requests, use StealthySession (sync) or AsyncStealthySession (async). This is significantly more efficient than launching a new browser for every request.

Key Features:

• Browser Reuse: Reuses the same browser instance for subsequent requests.
• Cookie Persistence: Automatically handles session state and cookies.
• Rotating Tab Pool: Use the max_pages argument to create a pool of browser tabs. The fetcher will manage opening new tabs up to the limit and closing finished ones, allowing for high-speed parallel fetching within a single browser instance.

from scrapling.fetchers import StealthySession

# Create a session with a shared configuration
with StealthySession(
    headless=True,
    real_chrome=True,
    block_webrtc=True,
    solve_cloudflare=True
) as session:
    page1 = session.fetch('https://example1.com')
    page2 = session.fetch('https://example2.com') 

When developing for EchoBot, adhere to these architectural constraints:

• Async Safety: Do not block the event loop. Move blocking file, network, or CPU-heavy work to asyncio.to_thread(...) or an executor.
• Single Source of Truth: Maintain one source of truth for sessions, tools, skills, route modes, runtime settings, and scheduling. Use echobot/runtime/bootstrap.py to wire features that should exist across multiple entrypoints.
• Tool Registry: Extend create_basic_tool_registry(...) or the tool-registry factory instead of hand-building tool lists for a single surface.
• Skill Location: Keep skill behavior inside echobot/skill_support/ and repository-local skills under skills/.
• JSON Formatting: Use json.dumps(..., ensure_ascii=False) for JSON output.
• Context Separation: Preserve the separation between user-facing roleplay context and background agent execution context.

Use DynamicSession (sync) or AsyncDynamicSession (async) to reuse a browser instance across multiple requests. This provides:

• Browser reuse: Faster subsequent requests.
• Cookie persistence: Automatic handling of session state.
• Consistent fingerprint: Same browser fingerprint across requests.
• Memory efficiency: Lower resource usage than launching new browsers.

Rotating Tab Pool: The max_pages argument allows you to create a rotating pool of browser tabs. The fetcher will limit the number of concurrent tabs to max_pages. If the limit is reached, it will wait up to 60 seconds for a tab to finish before raising a TimeoutError.

# Synchronous Session
from scrapling.fetchers import DynamicSession

with DynamicSession(
    headless=True,
    disable_resources=True,
    real_chrome=True
) as session:
    page1 = session.fetch('https://example1.com')
    page2 = session.fetch('https://example2.com')

# Asynchronous Session with tab pooling
import asyncio
from scrapling.fetchers import AsyncDynamicSession

async def scrape_multiple_sites():
    async with AsyncDynamicSession(
        network_idle=True,
        timeout=30000,
        max_pages=3
    ) as session:
        pages = await asyncio.gather(
            session.fetch('https://spa-app1.com'),
            session.fetch('https://spa-app2.com'),
            session.fetch('https://dynamic-content.com')
        )
        return pages

A skill is organized as a directory containing a required SKILL.md and optional bundled resources.

Directory Anatomy

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/    - Executable code for deterministic/repetitive tasks
    ├── references/ - Docs loaded into context as needed
    └── assets/     - Files used in output (templates, icons, fonts)

Progressive Disclosure (Loading Model)

To manage context window efficiency, skills follow a three-level loading system:

1. Metadata (name + description): Always in context (~100 words).
2. SKILL.md body: In context whenever the skill triggers (<500 lines ideal).
3. Bundled resources: Loaded only as needed (unlimited size; scripts execute without loading).

Best Practices

• Triggering: In the description field, be "pushy" to prevent Claude from "undertriggering". Instead of just describing the task, explicitly list contexts: "Use this skill whenever the user mentions dashboards, data visualization, or internal metrics..."
• Organization: For multi-domain skills, use a references/ folder with specific files (e.g., aws.md, gcp.md) so Claude only reads the relevant context.
• Complexity: If SKILL.md approaches 500 lines, introduce a hierarchy and pointers to other files.

When choosing between or migrating to Scrapling, keep these architectural differences in mind:

• Read-Only: BeautifulSoup allows DOM manipulation (modifying/manipulating the parsed tree). Scrapling is read-only and optimized strictly for high-performance extraction.
• Parsers: BeautifulSoup supports various engines (like html.parser). Scrapling uses lxml exclusively for maximum speed.
• Element Types: BeautifulSoup uses Tag objects; Scrapling uses Selector objects.
• Error Handling:
  • Both return None if find() fails to locate an element.
  • page.css() returns an empty Selectors list if no matches are found. To safely get a single element, use page.css('.selector').first to ensure you get None instead of an empty list if nothing matches.
• Text Processing: Scrapling includes a TextHandler for advanced cleaning, such as clean() to remove extra whitespace or unwanted characters.