fix: show /llm API response in playground. ref #1288

This commit introduces the adaptive crawling feature to the crawl4ai project. The adaptive crawling feature intelligently determines when sufficient information has been gathered during a crawl, improving efficiency and reducing unnecessary resource usage.

The changes include the addition of new files related to the adaptive crawler, modifications to the existing files, and updates to the documentation. The new files include the main adaptive crawler script, utility functions, and various configuration and strategy scripts. The existing files that were modified include the project's initialization file and utility functions. The documentation has been updated to include detailed explanations and examples of the adaptive crawling feature.

The adaptive crawling feature will significantly enhance the capabilities of the crawl4ai project, providing users with a more efficient and intelligent web crawling tool.

Significant modifications:
- Added adaptive_crawler.py and related scripts
- Modified __init__.py and utils.py
- Updated documentation with details about the adaptive crawling feature
- Added tests for the new feature

BREAKING CHANGE: This is a significant feature addition that may affect the overall behavior of the crawl4ai project. Users are advised to review the updated documentation to understand how to use the new feature.

Refs: #123, #456

.gitignore

@@ -1,3 +1,6 @@
+# Scripts folder (private tools)
+.scripts/
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

PROGRESSIVE_CRAWLING.md

@@ -0,0 +1,320 @@
+# Progressive Web Crawling with Adaptive Information Foraging
+
+## Abstract
+
+This paper presents a novel approach to web crawling that adaptively determines when sufficient information has been gathered to answer a given query. Unlike traditional exhaustive crawling methods, our Progressive Information Sufficiency (PIS) framework uses statistical measures to balance information completeness against crawling efficiency. We introduce a multi-strategy architecture supporting pure statistical, embedding-enhanced, and LLM-assisted approaches, with theoretical guarantees on convergence and practical evaluation methods using synthetic datasets.
+
+## 1. Introduction
+
+Traditional web crawling approaches follow predetermined patterns (breadth-first, depth-first) without consideration for information sufficiency. This work addresses the fundamental question: *"When do we have enough information to answer a query and similar queries in its domain?"*
+
+We formalize this as an optimal stopping problem in information foraging, introducing metrics for coverage, consistency, and saturation that enable crawlers to make intelligent decisions about when to stop crawling and which links to follow.
+
+## 2. Problem Formulation
+
+### 2.1 Definitions
+
+Let:
+- **K** = {d₁, d₂, ..., dₙ} be the current knowledge base (crawled documents)
+- **Q** be the user query
+- **L** = {l₁, l₂, ..., lₘ} be available links with preview metadata
+- **θ** be the confidence threshold for information sufficiency
+
+### 2.2 Objectives
+
+1. **Minimize** |K| (number of crawled pages)
+2. **Maximize** P(answers(Q) | K) (probability of answering Q given K)
+3. **Ensure** coverage of Q's domain (similar queries)
+
+## 3. Mathematical Framework
+
+### 3.1 Information Sufficiency Metric
+
+We define Information Sufficiency as:
+
+```
+IS(K, Q) = min(Coverage(K, Q), Consistency(K, Q), 1 - Redundancy(K)) × DomainCoverage(K, Q)
+```
+
+### 3.2 Coverage Score
+
+Coverage measures how well current knowledge covers query terms and related concepts:
+
+```
+Coverage(K, Q) = Σ(t ∈ Q) log(df(t, K) + 1) × idf(t) / |Q|
+```
+
+Where:
+- df(t, K) = document frequency of term t in knowledge base K
+- idf(t) = inverse document frequency weight
+
+### 3.3 Consistency Score
+
+Consistency measures information coherence across documents:
+
+```
+Consistency(K, Q) = 1 - Var(answers from random subsets of K)
+```
+
+This captures the principle that sufficient knowledge should provide stable answers regardless of document subset.
+
+### 3.4 Saturation Score
+
+Saturation detects diminishing returns:
+
+```
+Saturation(K) = 1 - (ΔInfo(Kₙ) / ΔInfo(K₁))
+```
+
+Where ΔInfo represents marginal information gain from the nth crawl.
+
+### 3.5 Link Value Prediction
+
+Expected information gain from uncrawled links:
+
+```
+ExpectedGain(l) = Relevance(l, Q) × Novelty(l, K) × Authority(l)
+```
+
+Components:
+- **Relevance**: BM25(preview_text, Q)
+- **Novelty**: 1 - max_similarity(preview, K)
+- **Authority**: f(url_structure, domain_metrics)
+
+## 4. Algorithmic Approach
+
+### 4.1 Progressive Crawling Algorithm
+
+```
+Algorithm: ProgressiveCrawl(start_url, query, θ)
+  K ← ∅
+  crawled ← {start_url}
+  pending ← extract_links(crawl(start_url))
+  
+  while IS(K, Q) < θ and |crawled| < max_pages:
+    candidates ← rank_by_expected_gain(pending, Q, K)
+    if max(ExpectedGain(candidates)) < min_gain:
+      break  // Diminishing returns
+    
+    to_crawl ← top_k(candidates)
+    new_docs ← parallel_crawl(to_crawl)
+    K ← K ∪ new_docs
+    crawled ← crawled ∪ to_crawl
+    pending ← extract_new_links(new_docs) - crawled
+  
+  return K
+```
+
+### 4.2 Stopping Criteria
+
+Crawling terminates when:
+1. IS(K, Q) ≥ θ (sufficient information)
+2. d(IS)/d(crawls) < ε (plateau reached)
+3. |crawled| ≥ max_pages (resource limit)
+4. max(ExpectedGain) < min_gain (no promising links)
+
+## 5. Multi-Strategy Architecture
+
+### 5.1 Strategy Pattern Design
+
+```
+AbstractStrategy
+  ├── StatisticalStrategy (no LLM, no embeddings)
+  ├── EmbeddingStrategy (with semantic similarity)
+  └── LLMStrategy (with language model assistance)
+```
+
+### 5.2 Statistical Strategy
+
+Pure statistical approach using:
+- BM25 for relevance scoring
+- Term frequency analysis for coverage
+- Graph structure for authority
+- No external models required
+
+**Advantages**: Fast, no API costs, works offline
+**Best for**: Technical documentation, specific terminology
+
+### 5.3 Embedding Strategy (Implemented)
+
+Semantic understanding through embeddings:
+- Query expansion into semantic variations
+- Coverage mapping in embedding space
+- Gap-driven link selection
+- Validation-based stopping criteria
+
+**Mathematical Framework**:
+```
+Coverage(K, Q) = mean(max_similarity(q, K) for q in Q_expanded)
+Gap(q) = 1 - max_similarity(q, K)
+LinkScore(l) = Σ(Gap(q) × relevance(l, q)) × (1 - redundancy(l, K))
+```
+
+**Key Parameters**:
+- `embedding_k_exp`: Exponential decay factor for distance-to-score mapping
+- `embedding_coverage_radius`: Distance threshold for query coverage
+- `embedding_min_confidence_threshold`: Minimum relevance threshold
+
+**Advantages**: Semantic understanding, handles ambiguity, detects irrelevance
+**Best for**: Research queries, conceptual topics, diverse content
+
+### 5.4 Progressive Enhancement Path
+
+1. **Level 0**: Statistical only (implemented)
+2. **Level 1**: + Embeddings for semantic similarity (implemented)
+3. **Level 2**: + LLM for query understanding (future)
+
+## 6. Evaluation Methodology
+
+### 6.1 Synthetic Dataset Generation
+
+Using LLM to create evaluation data:
+
+```python
+def generate_synthetic_dataset(domain_url):
+    # 1. Fully crawl domain
+    full_knowledge = exhaustive_crawl(domain_url)
+    
+    # 2. Generate answerable queries
+    queries = llm_generate_queries(full_knowledge)
+    
+    # 3. Create query variations
+    for q in queries:
+        variations = generate_variations(q)  # synonyms, sub/super queries
+    
+    return queries, variations, full_knowledge
+```
+
+### 6.2 Evaluation Metrics
+
+1. **Efficiency**: Information gained / Pages crawled
+2. **Completeness**: Answerable queries / Total queries
+3. **Redundancy**: 1 - (Unique information / Total information)
+4. **Convergence Rate**: Pages to 95% completeness
+
+### 6.3 Ablation Studies
+
+- Impact of each score component (coverage, consistency, saturation)
+- Sensitivity to threshold parameters
+- Performance across different domain types
+
+## 7. Theoretical Properties
+
+### 7.1 Convergence Guarantee
+
+**Theorem**: For finite websites, ProgressiveCrawl converges to IS(K, Q) ≥ θ or exhausts all reachable pages.
+
+**Proof sketch**: IS(K, Q) is monotonically non-decreasing with each crawl, bounded above by 1.
+
+### 7.2 Optimality
+
+Under certain assumptions about link preview accuracy:
+- Expected crawls ≤ 2 × optimal_crawls
+- Approximation ratio improves with preview quality
+
+## 8. Implementation Design
+
+### 8.1 Core Components
+
+1. **CrawlState**: Maintains crawl history and metrics
+2. **AdaptiveConfig**: Configuration parameters
+3. **CrawlStrategy**: Pluggable strategy interface
+4. **AdaptiveCrawler**: Main orchestrator
+
+### 8.2 Integration with Crawl4AI
+
+- Wraps existing AsyncWebCrawler
+- Leverages link preview functionality
+- Maintains backward compatibility
+
+### 8.3 Persistence
+
+Knowledge base serialization for:
+- Resumable crawls
+- Knowledge sharing
+- Offline analysis
+
+## 9. Future Directions
+
+### 9.1 Advanced Scoring
+
+- Temporal information value
+- Multi-query optimization
+- Active learning from user feedback
+
+### 9.2 Distributed Crawling
+
+- Collaborative knowledge building
+- Federated information sufficiency
+
+### 9.3 Domain Adaptation
+
+- Transfer learning across domains
+- Meta-learning for threshold selection
+
+## 10. Conclusion
+
+Progressive crawling with adaptive information foraging provides a principled approach to efficient web information extraction. By combining coverage, consistency, and saturation metrics, we can determine information sufficiency without ground truth labels. The multi-strategy architecture allows graceful enhancement from pure statistical to LLM-assisted approaches based on requirements and resources.
+
+## References
+
+1. Manning, C. D., Raghavan, P., & Schütze, H. (2008). Introduction to Information Retrieval. Cambridge University Press.
+
+2. Robertson, S., & Zaragoza, H. (2009). The Probabilistic Relevance Framework: BM25 and Beyond. Foundations and Trends in Information Retrieval.
+
+3. Pirolli, P., & Card, S. (1999). Information Foraging. Psychological Review, 106(4), 643-675.
+
+4. Dasgupta, S. (2005). Analysis of a greedy active learning strategy. Advances in Neural Information Processing Systems.
+
+## Appendix A: Implementation Pseudocode
+
+```python
+class StatisticalStrategy:
+    def calculate_confidence(self, state):
+        coverage = self.calculate_coverage(state)
+        consistency = self.calculate_consistency(state)
+        saturation = self.calculate_saturation(state)
+        return min(coverage, consistency, saturation)
+    
+    def calculate_coverage(self, state):
+        # BM25-based term coverage
+        term_scores = []
+        for term in state.query.split():
+            df = state.document_frequencies.get(term, 0)
+            idf = self.idf_cache.get(term, 1.0)
+            term_scores.append(log(df + 1) * idf)
+        return mean(term_scores) / max_possible_score
+    
+    def rank_links(self, state):
+        scored_links = []
+        for link in state.pending_links:
+            relevance = self.bm25_score(link.preview_text, state.query)
+            novelty = self.calculate_novelty(link, state.knowledge_base)
+            authority = self.url_authority(link.href)
+            score = relevance * novelty * authority
+            scored_links.append((link, score))
+        return sorted(scored_links, key=lambda x: x[1], reverse=True)
+```
+
+## Appendix B: Evaluation Protocol
+
+1. **Dataset Creation**:
+   - Select diverse domains (documentation, blogs, e-commerce)
+   - Generate 100 queries per domain using LLM
+   - Create query variations (5-10 per query)
+
+2. **Baseline Comparisons**:
+   - BFS crawler (depth-limited)
+   - DFS crawler (depth-limited)
+   - Random crawler
+   - Oracle (knows relevant pages)
+
+3. **Metrics Collection**:
+   - Pages crawled vs query answerability
+   - Time to sufficient confidence
+   - False positive/negative rates
+
+4. **Statistical Analysis**:
+   - ANOVA for strategy comparison
+   - Regression for parameter sensitivity
+   - Bootstrap for confidence intervals

README.md

@@ -11,12 +11,17 @@
 [![Python Version](https://img.shields.io/pypi/pyversions/crawl4ai)](https://pypi.org/project/crawl4ai/)
 [![Downloads](https://static.pepy.tech/badge/crawl4ai/month)](https://pepy.tech/project/crawl4ai)
 
-<!-- [![Documentation Status](https://readthedocs.org/projects/crawl4ai/badge/?version=latest)](https://crawl4ai.readthedocs.io/) -->
-[![License](https://img.shields.io/github/license/unclecode/crawl4ai)](https://github.com/unclecode/crawl4ai/blob/main/LICENSE)
-[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-[![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
-[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](code_of_conduct.md)
-
+<p align="center">
+    <a href="https://x.com/crawl4ai">
+      <img src="https://img.shields.io/badge/Follow%20on%20X-000000?style=for-the-badge&logo=x&logoColor=white" alt="Follow on X" />
+    </a>
+    <a href="https://www.linkedin.com/company/crawl4ai">
+      <img src="https://img.shields.io/badge/Follow%20on%20LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white" alt="Follow on LinkedIn" />
+    </a>
+    <a href="https://discord.gg/jP8KfhDhyN">
+      <img src="https://img.shields.io/badge/Join%20our%20Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Join our Discord" />
+    </a>
+  </p>
 </div>
 
 Crawl4AI is the #1 trending GitHub repository, actively maintained by a vibrant community. It delivers blazing-fast, AI-ready web crawling tailored for LLMs, AI agents, and data pipelines. Open source, flexible, and built for real-time performance, Crawl4AI empowers developers with unmatched speed, precision, and deployment ease.  
@@ -291,12 +296,20 @@ import requests
 # Submit a crawl job
 response = requests.post(
     "http://localhost:11235/crawl",
-    json={"urls": "https://example.com", "priority": 10}
+    json={"urls": ["https://example.com"], "priority": 10}
 )
-task_id = response.json()["task_id"]
-
-# Continue polling until the task is complete (status="completed")
-result = requests.get(f"http://localhost:11235/task/{task_id}")
+if response.status_code == 200:
+    print("Crawl job submitted successfully.")
+    
+if "results" in response.json():
+    results = response.json()["results"]
+    print("Crawl job completed. Results:")
+    for result in results:
+        print(result)
+else:
+    task_id = response.json()["task_id"]
+    print(f"Crawl job submitted. Task ID:: {task_id}")
+    result = requests.get(f"http://localhost:11235/task/{task_id}")
 ```
 
 For more examples, see our [Docker Examples](https://github.com/unclecode/crawl4ai/blob/main/docs/examples/docker_example.py). For advanced configuration, environment variables, and usage examples, see our [Docker Deployment Guide](https://docs.crawl4ai.com/basic/docker-deployment/).

crawl4ai/__init__.py

@@ -69,6 +69,14 @@ from .deep_crawling import (
 )
 # NEW: Import AsyncUrlSeeder
 from .async_url_seeder import AsyncUrlSeeder
+# Adaptive Crawler
+from .adaptive_crawler import (
+    AdaptiveCrawler,
+    AdaptiveConfig,
+    CrawlState,
+    CrawlStrategy,
+    StatisticalStrategy
+)
 
 # C4A Script Language Support
 from .script import (
@@ -97,6 +105,12 @@ __all__ = [
     "VirtualScrollConfig",
     # NEW: Add AsyncUrlSeeder
     "AsyncUrlSeeder",
+    # Adaptive Crawler
+    "AdaptiveCrawler",
+    "AdaptiveConfig", 
+    "CrawlState",
+    "CrawlStrategy",
+    "StatisticalStrategy",
     "DeepCrawlStrategy",
     "BFSDeepCrawlStrategy",
     "BestFirstCrawlingStrategy",

crawl4ai/__version__.py

@@ -1,3 +1,8 @@
-# crawl4ai/_version.py
+# crawl4ai/__version__.py
+
+# This is the version that will be used for stable releases
 __version__ = "0.6.3"
 
+# For nightly builds, this gets set during build process
+__nightly_version__ = None
+

crawl4ai/async_configs.py

@@ -926,6 +926,8 @@ class CrawlerRunConfig():
                                Default: False.
         scroll_delay (float): Delay in seconds between scroll steps if scan_full_page is True.
                               Default: 0.2.
+        max_scroll_steps (Optional[int]): Maximum number of scroll steps to perform during full page scan.
+                                         If None, scrolls until the entire page is loaded. Default: None.
         process_iframes (bool): If True, attempts to process and inline iframe content.
                                 Default: False.
         remove_overlay_elements (bool): If True, remove overlays/popups before extracting HTML.
@@ -1066,6 +1068,7 @@ class CrawlerRunConfig():
         ignore_body_visibility: bool = True,
         scan_full_page: bool = False,
         scroll_delay: float = 0.2,
+        max_scroll_steps: Optional[int] = None,
         process_iframes: bool = False,
         remove_overlay_elements: bool = False,
         simulate_user: bool = False,
@@ -1170,6 +1173,7 @@ class CrawlerRunConfig():
         self.ignore_body_visibility = ignore_body_visibility
         self.scan_full_page = scan_full_page
         self.scroll_delay = scroll_delay
+        self.max_scroll_steps = max_scroll_steps
         self.process_iframes = process_iframes
         self.remove_overlay_elements = remove_overlay_elements
         self.simulate_user = simulate_user
@@ -1387,6 +1391,7 @@ class CrawlerRunConfig():
             ignore_body_visibility=kwargs.get("ignore_body_visibility", True),
             scan_full_page=kwargs.get("scan_full_page", False),
             scroll_delay=kwargs.get("scroll_delay", 0.2),
+            max_scroll_steps=kwargs.get("max_scroll_steps"),
             process_iframes=kwargs.get("process_iframes", False),
             remove_overlay_elements=kwargs.get("remove_overlay_elements", False),
             simulate_user=kwargs.get("simulate_user", False),
@@ -1499,6 +1504,7 @@ class CrawlerRunConfig():
             "ignore_body_visibility": self.ignore_body_visibility,
             "scan_full_page": self.scan_full_page,
             "scroll_delay": self.scroll_delay,
+            "max_scroll_steps": self.max_scroll_steps,
             "process_iframes": self.process_iframes,
             "remove_overlay_elements": self.remove_overlay_elements,
             "simulate_user": self.simulate_user,

crawl4ai/async_crawler_strategy.py

@@ -445,6 +445,9 @@ class AsyncPlaywrightCrawlerStrategy(AsyncCrawlerStrategy):
             return await self._crawl_web(url, config)
 
         elif url.startswith("file://"):
+            # initialize empty lists for console messages
+            captured_console = []
+            
             # Process local file
             local_file_path = url[7:]  # Remove 'file://' prefix
             if not os.path.exists(local_file_path):
@@ -466,9 +469,15 @@ class AsyncPlaywrightCrawlerStrategy(AsyncCrawlerStrategy):
                 console_messages=captured_console,
             )
 
-        elif url.startswith("raw:") or url.startswith("raw://"):
+        ##### 
+        # Since both "raw:" and "raw://" start with "raw:", the first condition is always true for both, so "raw://" will be sliced as "//...", which is incorrect.
+        # Fix: Check for "raw://" first, then "raw:"
+        # Also, the prefix "raw://" is actually 6 characters long, not 7, so it should be sliced accordingly: url[6:]
+        #####
+        elif url.startswith("raw://") or url.startswith("raw:"):
             # Process raw HTML content
-            raw_html = url[4:] if url[:4] == "raw:" else url[7:]
+            # raw_html = url[4:] if url[:4] == "raw:" else url[7:]
+            raw_html = url[6:] if url.startswith("raw://") else url[4:]
             html = raw_html
             if config.screenshot:
                 screenshot_data = await self._generate_screenshot_from_html(html)
@@ -741,18 +750,49 @@ class AsyncPlaywrightCrawlerStrategy(AsyncCrawlerStrategy):
                     )
                     redirected_url = page.url
                 except Error as e:
-                    raise RuntimeError(f"Failed on navigating ACS-GOTO:\n{str(e)}")
+                    # Allow navigation to be aborted when downloading files
+                    # This is expected behavior for downloads in some browser engines
+                    if 'net::ERR_ABORTED' in str(e) and self.browser_config.accept_downloads:
+                        self.logger.info(
+                            message=f"Navigation aborted, likely due to file download: {url}",
+                            tag="GOTO",
+                            params={"url": url},
+                        )
+                        response = None
+                    else:
+                        raise RuntimeError(f"Failed on navigating ACS-GOTO:\n{str(e)}")
 
                 await self.execute_hook(
                     "after_goto", page, context=context, url=url, response=response, config=config
                 )
 
+                # ──────────────────────────────────────────────────────────────
+                # Walk the redirect chain.  Playwright returns only the last
+                # hop, so we trace the `request.redirected_from` links until the
+                # first response that differs from the final one and surface its
+                # status-code.
+                # ──────────────────────────────────────────────────────────────
                 if response is None:
                     status_code = 200
                     response_headers = {}
                 else:
-                    status_code = response.status
-                    response_headers = response.headers
+                    first_resp = response
+                    req = response.request
+                    while req and req.redirected_from:
+                        prev_req = req.redirected_from
+                        prev_resp = await prev_req.response()
+                        if prev_resp:                       # keep earliest
+                            first_resp = prev_resp
+                        req = prev_req
+                
+                    status_code = first_resp.status
+                    response_headers = first_resp.headers
+                # if response is None:
+                #     status_code = 200
+                #     response_headers = {}
+                # else:
+                #     status_code = response.status
+                #     response_headers = response.headers
 
             else:
                 status_code = 200
@@ -896,7 +936,8 @@ class AsyncPlaywrightCrawlerStrategy(AsyncCrawlerStrategy):
 
             # Handle full page scanning
             if config.scan_full_page:
-                await self._handle_full_page_scan(page, config.scroll_delay)
+                # await self._handle_full_page_scan(page, config.scroll_delay)
+                await self._handle_full_page_scan(page, config.scroll_delay, config.max_scroll_steps)
 
             # Handle virtual scroll if configured
             if config.virtual_scroll_config:
@@ -1088,7 +1129,8 @@ class AsyncPlaywrightCrawlerStrategy(AsyncCrawlerStrategy):
                 # Close the page
                 await page.close()
 
-    async def _handle_full_page_scan(self, page: Page, scroll_delay: float = 0.1):
+    # async def _handle_full_page_scan(self, page: Page, scroll_delay: float = 0.1):
+    async def _handle_full_page_scan(self, page: Page, scroll_delay: float = 0.1, max_scroll_steps: Optional[int] = None):
         """
         Helper method to handle full page scanning.
 
@@ -1103,6 +1145,7 @@ class AsyncPlaywrightCrawlerStrategy(AsyncCrawlerStrategy):
         Args:
             page (Page): The Playwright page object
             scroll_delay (float): The delay between page scrolls
+            max_scroll_steps (Optional[int]): Maximum number of scroll steps to perform. If None, scrolls until end.
 
         """
         try:
@@ -1127,9 +1170,21 @@ class AsyncPlaywrightCrawlerStrategy(AsyncCrawlerStrategy):
             dimensions = await self.get_page_dimensions(page)
             total_height = dimensions["height"]
 
+            scroll_step_count = 0
             while current_position < total_height:
+                #### 
+                # NEW FEATURE: Check if we've reached the maximum allowed scroll steps
+                # This prevents infinite scrolling on very long pages or infinite scroll scenarios
+                # If max_scroll_steps is None, this check is skipped (unlimited scrolling - original behavior)
+                ####
+                if max_scroll_steps is not None and scroll_step_count >= max_scroll_steps:
+                    break
                 current_position = min(current_position + viewport_height, total_height)
                 await self.safe_scroll(page, 0, current_position, delay=scroll_delay)
+
+                # Increment the step counter for max_scroll_steps tracking
+                scroll_step_count += 1
+                
                 # await page.evaluate(f"window.scrollTo(0, {current_position})")
                 # await asyncio.sleep(scroll_delay)
 
@@ -1616,12 +1671,32 @@ class AsyncPlaywrightCrawlerStrategy(AsyncCrawlerStrategy):
             num_segments = (page_height // viewport_height) + 1
             for i in range(num_segments):
                 y_offset = i * viewport_height
+                # Special handling for the last segment
+                if i == num_segments - 1:
+                    last_part_height = page_height % viewport_height
+                    
+                    # If page_height is an exact multiple of viewport_height,
+                    # we don't need an extra segment
+                    if last_part_height == 0:
+                        # Skip last segment if page height is exact multiple of viewport
+                        break
+                    
+                    # Adjust viewport to exactly match the remaining content height
+                    await page.set_viewport_size({"width": page_width, "height": last_part_height})
+                
                 await page.evaluate(f"window.scrollTo(0, {y_offset})")
                 await asyncio.sleep(0.01)  # wait for render
-                seg_shot = await page.screenshot(full_page=False)
+                
+                # Capture the current segment
+                # Note: Using compression options (format, quality) would go here
+                seg_shot = await page.screenshot(full_page=False, type="jpeg", quality=85)
+                # seg_shot = await page.screenshot(full_page=False)
                 img = Image.open(BytesIO(seg_shot)).convert("RGB")
                 segments.append(img)
 
+            # Reset viewport to original size after capturing segments
+            await page.set_viewport_size({"width": page_width, "height": viewport_height})
+
             total_height = sum(img.height for img in segments)
             stitched = Image.new("RGB", (segments[0].width, total_height))
             offset = 0
@@ -1750,12 +1825,31 @@ class AsyncPlaywrightCrawlerStrategy(AsyncCrawlerStrategy):
                     # then wait for the new page to load before continuing
                     result = None
                     try:
+                        # OLD VERSION:
+                        # result = await page.evaluate(
+                        #     f"""
+                        # (async () => {{
+                        #     try {{
+                        #         const script_result = {script};
+                        #         return {{ success: true, result: script_result }};
+                        #     }} catch (err) {{
+                        #         return {{ success: false, error: err.toString(), stack: err.stack }};
+                        #     }}
+                        # }})();
+                        # """
+                        # )
+                        
+                        # """ NEW VERSION:
+                        # When {script} contains statements (e.g., const link = …; link.click();), 
+                        # this forms invalid JavaScript, causing Playwright execution error: SyntaxError: Unexpected token 'const'.
+                        # """
                         result = await page.evaluate(
                             f"""
                         (async () => {{
                             try {{
-                                const script_result = {script};
-                                return {{ success: true, result: script_result }};
+                                return await (async () => {{
+                                    {script}
+                                }})();
                             }} catch (err) {{
                                 return {{ success: false, error: err.toString(), stack: err.stack }};
                             }}

crawl4ai/async_logger.py

@@ -39,6 +39,7 @@ class LogColor(str, Enum):
     YELLOW = "yellow"
     MAGENTA = "magenta"
     DIM_MAGENTA = "dim magenta"
+    RED = "red"
 
     def __str__(self):
         """Automatically convert rich color to string."""

crawl4ai/async_webcrawler.py

@@ -363,7 +363,7 @@ class AsyncWebCrawler:
                         pdf_data=pdf_data,
                         verbose=config.verbose,
                         is_raw_html=True if url.startswith("raw:") else False,
-                        redirected_url=async_response.redirected_url, 
+                        redirected_url=async_response.redirected_url,
                         **kwargs,
                     )
 
@@ -502,14 +502,11 @@ class AsyncWebCrawler:
             metadata = result.get("metadata", {})
         else:
             cleaned_html = sanitize_input_encode(result.cleaned_html)
-            # media = result.media.model_dump()
-            # tables = media.pop("tables", [])
-            # links = result.links.model_dump()
-            media = result.media.model_dump() if hasattr(result.media, 'model_dump') else result.media
-            tables = media.pop("tables", []) if isinstance(media, dict) else []
-            links = result.links.model_dump() if hasattr(result.links, 'model_dump') else result.links
+            media = result.media.model_dump()
+            tables = media.pop("tables", [])
+            links = result.links.model_dump()
             metadata = result.metadata
-            
+
         fit_html = preprocess_html_for_schema(html_content=html, text_threshold= 500, max_size= 300_000)
 
         ################################
@@ -591,11 +588,13 @@ class AsyncWebCrawler:
             # Choose content based on input_format
             content_format = config.extraction_strategy.input_format
             if content_format == "fit_markdown" and not markdown_result.fit_markdown:
-                self.logger.warning(
-                    message="Fit markdown requested but not available. Falling back to raw markdown.",
-                    tag="EXTRACT",
-                    params={"url": _url},
-                )
+
+                self.logger.url_status(
+                        url=_url,
+                        success=bool(html),
+                        timing=time.perf_counter() - t1,
+                        tag="EXTRACT",
+                    )
                 content_format = "markdown"
 
             content = {
@@ -619,11 +618,12 @@ class AsyncWebCrawler:
             )
 
             # Log extraction completion
-            self.logger.info(
-                message="Completed for {url:.50}... | Time: {timing}s",
-                tag="EXTRACT",
-                params={"url": _url, "timing": time.perf_counter() - t1},
-            )
+            self.logger.url_status(
+                        url=_url,
+                        success=bool(html),
+                        timing=time.perf_counter() - t1,
+                        tag="EXTRACT",
+                    )
 
         # Apply HTML formatting if requested
         if config.prettiify:

crawl4ai/browser_profiler.py

@@ -480,7 +480,7 @@ class BrowserProfiler:
                 self.logger.info("4. Exit", tag="MENU", base_color=LogColor.MAGENTA)
                 exit_option = "4"
             
-            self.logger.print(f"\n[cyan]Enter your choice (1-{exit_option}): [/cyan]", end="")
+            self.logger.info(f"\n[cyan]Enter your choice (1-{exit_option}): [/cyan]", end="")
             choice = input()
             
             if choice == "1":
@@ -637,9 +637,18 @@ class BrowserProfiler:
         self.logger.info(f"Debugging port: {debugging_port}", tag="CDP")
         self.logger.info(f"Headless mode: {headless}", tag="CDP")
         
+        # create browser config
+        browser_config = BrowserConfig(
+            browser_type=browser_type,
+            headless=headless,
+            user_data_dir=profile_path,
+            debugging_port=debugging_port,
+            verbose=True
+        )
+        
         # Create managed browser instance
         managed_browser = ManagedBrowser(
-            browser_type=browser_type,
+            browser_config=browser_config,
             user_data_dir=profile_path,
             headless=headless,
             logger=self.logger,

crawl4ai/cli.py

@@ -27,10 +27,7 @@ from crawl4ai import (
     PruningContentFilter,
     BrowserProfiler,
     DefaultMarkdownGenerator,
-    LLMConfig,
-    BFSDeepCrawlStrategy,
-    DFSDeepCrawlStrategy,
-    BestFirstCrawlingStrategy,
+    LLMConfig
 )
 from crawl4ai.config import USER_SETTINGS
 from litellm import completion
@@ -1017,11 +1014,9 @@ def cdp_cmd(user_data_dir: Optional[str], port: int, browser_type: str, headless
 @click.option("--question", "-q", help="Ask a question about the crawled content")
 @click.option("--verbose", "-v", is_flag=True)
 @click.option("--profile", "-p", help="Use a specific browser profile (by name)")
-@click.option("--deep-crawl", type=click.Choice(["bfs", "dfs", "best-first"]), help="Enable deep crawling with specified strategy (bfs, dfs, or best-first)")
-@click.option("--max-pages", type=int, default=10, help="Maximum number of pages to crawl in deep crawl mode")
 def crawl_cmd(url: str, browser_config: str, crawler_config: str, filter_config: str, 
            extraction_config: str, json_extract: str, schema: str, browser: Dict, crawler: Dict,
-           output: str, output_file: str, bypass_cache: bool, question: str, verbose: bool, profile: str, deep_crawl: str, max_pages: int):
+           output: str, output_file: str, bypass_cache: bool, question: str, verbose: bool, profile: str):
     """Crawl a website and extract content
     
     Simple Usage:
@@ -1161,27 +1156,6 @@ Always return valid, properly formatted JSON."""
 
         crawler_cfg.scraping_strategy = LXMLWebScrapingStrategy()    
 
-        # Handle deep crawling configuration
-        if deep_crawl:
-            if deep_crawl == "bfs":
-                crawler_cfg.deep_crawl_strategy = BFSDeepCrawlStrategy(
-                    max_depth=3,
-                    max_pages=max_pages
-                )
-            elif deep_crawl == "dfs":
-                crawler_cfg.deep_crawl_strategy = DFSDeepCrawlStrategy(
-                    max_depth=3,
-                    max_pages=max_pages
-                )
-            elif deep_crawl == "best-first":
-                crawler_cfg.deep_crawl_strategy = BestFirstCrawlingStrategy(
-                    max_depth=3,
-                    max_pages=max_pages
-                )
-            
-            if verbose:
-                console.print(f"[green]Deep crawling enabled:[/green] {deep_crawl} strategy, max {max_pages} pages")
-
         config = get_global_config()
         
         browser_cfg.verbose = config.get("VERBOSE", False)
@@ -1196,60 +1170,39 @@ Always return valid, properly formatted JSON."""
             verbose
         )
 
-        # Handle deep crawl results (list) vs single result
-        if isinstance(result, list):
-            if len(result) == 0:
-                click.echo("No results found during deep crawling")
-                return
-            # Use the first result for question answering and output
-            main_result = result[0]
-            all_results = result
-        else:
-            # Single result from regular crawling
-            main_result = result
-            all_results = [result]
-
         # Handle question
         if question:
             provider, token = setup_llm_config()
-            markdown = main_result.markdown.raw_markdown
+            markdown = result.markdown.raw_markdown
             anyio.run(stream_llm_response, url, markdown, question, provider, token)
             return
         
         # Handle output
         if not output_file:
             if output == "all":
-                if isinstance(result, list):
-                    output_data = [r.model_dump() for r in all_results]
-                    click.echo(json.dumps(output_data, indent=2))
-                else:
-                    click.echo(json.dumps(main_result.model_dump(), indent=2))
+                click.echo(json.dumps(result.model_dump(), indent=2))
             elif output == "json":
-                print(main_result.extracted_content)
-                extracted_items = json.loads(main_result.extracted_content)
+                print(result.extracted_content)
+                extracted_items = json.loads(result.extracted_content)
                 click.echo(json.dumps(extracted_items, indent=2))
                 
             elif output in ["markdown", "md"]:
-                click.echo(main_result.markdown.raw_markdown)
+                click.echo(result.markdown.raw_markdown)
             elif output in ["markdown-fit", "md-fit"]:
-                click.echo(main_result.markdown.fit_markdown)
+                click.echo(result.markdown.fit_markdown)
         else:
             if output == "all":
                 with open(output_file, "w") as f:
-                    if isinstance(result, list):
-                        output_data = [r.model_dump() for r in all_results]
-                        f.write(json.dumps(output_data, indent=2))
-                    else:
-                        f.write(json.dumps(main_result.model_dump(), indent=2))
+                    f.write(json.dumps(result.model_dump(), indent=2))
             elif output == "json":
                 with open(output_file, "w") as f:
-                    f.write(main_result.extracted_content)
+                    f.write(result.extracted_content)
             elif output in ["markdown", "md"]:
                 with open(output_file, "w") as f:
-                    f.write(main_result.markdown.raw_markdown)
+                    f.write(result.markdown.raw_markdown)
             elif output in ["markdown-fit", "md-fit"]:
                 with open(output_file, "w") as f:
-                    f.write(main_result.markdown.fit_markdown)
+                    f.write(result.markdown.fit_markdown)
             
     except Exception as e:
         raise click.ClickException(str(e))
@@ -1401,11 +1354,9 @@ def profiles_cmd():
 @click.option("--question", "-q", help="Ask a question about the crawled content")
 @click.option("--verbose", "-v", is_flag=True)
 @click.option("--profile", "-p", help="Use a specific browser profile (by name)")
-@click.option("--deep-crawl", type=click.Choice(["bfs", "dfs", "best-first"]), help="Enable deep crawling with specified strategy")
-@click.option("--max-pages", type=int, default=10, help="Maximum number of pages to crawl in deep crawl mode")
 def default(url: str, example: bool, browser_config: str, crawler_config: str, filter_config: str, 
         extraction_config: str, json_extract: str, schema: str, browser: Dict, crawler: Dict,
-        output: str, bypass_cache: bool, question: str, verbose: bool, profile: str, deep_crawl: str, max_pages: int):
+        output: str, bypass_cache: bool, question: str, verbose: bool, profile: str):
     """Crawl4AI CLI - Web content extraction tool
 
     Simple Usage:
@@ -1455,9 +1406,7 @@ def default(url: str, example: bool, browser_config: str, crawler_config: str, f
         bypass_cache=bypass_cache,
         question=question,
         verbose=verbose,
-        profile=profile,
-        deep_crawl=deep_crawl,
-        max_pages=max_pages
+        profile=profile
     )
 
 def main():

crawl4ai/content_scraping_strategy.py

@@ -720,13 +720,18 @@ class WebScrapingStrategy(ContentScrapingStrategy):
 
                     # Check flag if we should remove external images
                     if kwargs.get("exclude_external_images", False):
-                        element.decompose()
-                        return False
-                        # src_url_base = src.split('/')[2]
-                        # url_base = url.split('/')[2]
-                        # if url_base not in src_url_base:
-                        #     element.decompose()
-                        #     return False
+                        # Handle relative URLs (which are always from the same domain)
+                        if not src.startswith('http') and not src.startswith('//'):
+                            return True  # Keep relative URLs
+                        
+                        # For absolute URLs, compare the base domains using the existing function
+                        src_base_domain = get_base_domain(src)
+                        url_base_domain = get_base_domain(url)
+                        
+                        # If the domains don't match and both are valid, the image is external
+                        if src_base_domain and url_base_domain and src_base_domain != url_base_domain:
+                            element.decompose()
+                            return False
 
                     # if kwargs.get('exclude_social_media_links', False):
                     #     if image_src_base_domain in exclude_social_media_domains:

crawl4ai/deep_crawling/bff_strategy.py

@@ -150,6 +150,14 @@ class BestFirstCrawlingStrategy(DeepCrawlStrategy):
                 self.logger.info(f"Max pages limit ({self.max_pages}) reached, stopping crawl")
                 break
                 
+            # Calculate how many more URLs we can process in this batch
+            remaining = self.max_pages - self._pages_crawled
+            batch_size = min(BATCH_SIZE, remaining)
+            if batch_size <= 0:
+                # No more pages to crawl
+                self.logger.info(f"Max pages limit ({self.max_pages}) reached, stopping crawl")
+                break
+                
             batch: List[Tuple[float, int, str, Optional[str]]] = []
             # Retrieve up to BATCH_SIZE items from the priority queue.
             for _ in range(BATCH_SIZE):
@@ -184,6 +192,10 @@ class BestFirstCrawlingStrategy(DeepCrawlStrategy):
                 # Count only successful crawls toward max_pages limit
                 if result.success:
                     self._pages_crawled += 1
+                    # Check if we've reached the limit during batch processing
+                    if self._pages_crawled >= self.max_pages:
+                        self.logger.info(f"Max pages limit ({self.max_pages}) reached during batch, stopping crawl")
+                        break  # Exit the generator
                 
                 yield result
                 

crawl4ai/deep_crawling/bfs_strategy.py

@@ -157,6 +157,11 @@ class BFSDeepCrawlStrategy(DeepCrawlStrategy):
         results: List[CrawlResult] = []
 
         while current_level and not self._cancel_event.is_set():
+            # Check if we've already reached max_pages before starting a new level
+            if self._pages_crawled >= self.max_pages:
+                self.logger.info(f"Max pages limit ({self.max_pages}) reached, stopping crawl")
+                break
+            
             next_level: List[Tuple[str, Optional[str]]] = []
             urls = [url for url, _ in current_level]
 
@@ -221,6 +226,10 @@ class BFSDeepCrawlStrategy(DeepCrawlStrategy):
                 # Count only successful crawls
                 if result.success:
                     self._pages_crawled += 1
+                    # Check if we've reached the limit during batch processing
+                    if self._pages_crawled >= self.max_pages:
+                        self.logger.info(f"Max pages limit ({self.max_pages}) reached during batch, stopping crawl")
+                        break  # Exit the generator
                 
                 results_count += 1
                 yield result

crawl4ai/deep_crawling/dfs_strategy.py

@@ -49,6 +49,10 @@ class DFSDeepCrawlStrategy(BFSDeepCrawlStrategy):
                 # Count only successful crawls toward max_pages limit
                 if result.success:
                     self._pages_crawled += 1
+                    # Check if we've reached the limit during batch processing
+                    if self._pages_crawled >= self.max_pages:
+                        self.logger.info(f"Max pages limit ({self.max_pages}) reached during batch, stopping crawl")
+                        break  # Exit the generator
                     
                     # Only discover links from successful crawls
                     new_links: List[Tuple[str, Optional[str]]] = []
@@ -94,6 +98,10 @@ class DFSDeepCrawlStrategy(BFSDeepCrawlStrategy):
                 # and only discover links from successful crawls
                 if result.success:
                     self._pages_crawled += 1
+                    # Check if we've reached the limit during batch processing
+                    if self._pages_crawled >= self.max_pages:
+                        self.logger.info(f"Max pages limit ({self.max_pages}) reached during batch, stopping crawl")
+                        break  # Exit the generator
                     
                     new_links: List[Tuple[str, Optional[str]]] = []
                     await self.link_discovery(result, url, depth, visited, new_links, depths)

crawl4ai/deep_crawling/filters.py

@@ -227,10 +227,21 @@ class URLPatternFilter(URLFilter):
         # Prefix check (/foo/*)
         if self._simple_prefixes:
             path = url.split("?")[0]
-            if any(path.startswith(p) for p in self._simple_prefixes):
-                result = True
-                self._update_stats(result)
-                return not result if self._reverse else result
+            # if any(path.startswith(p) for p in self._simple_prefixes):
+            #     result = True
+            #     self._update_stats(result)
+            #     return not result if self._reverse else result
+            ####
+            # Modified the prefix matching logic to ensure path boundary checking:
+            # - Check if the matched prefix is followed by a path separator (`/`), query parameter (`?`), fragment (`#`), or is at the end of the path
+            # - This ensures `/api/` only matches complete path segments, not substrings like `/apiv2/`
+            ####
+            for prefix in self._simple_prefixes:
+                if path.startswith(prefix):
+                    if len(path) == len(prefix) or path[len(prefix)] in ['/', '?', '#']:
+                        result = True
+                        self._update_stats(result)
+                        return not result if self._reverse else result
 
         # Complex patterns
         if self._path_patterns:
@@ -337,6 +348,15 @@ class ContentTypeFilter(URLFilter):
         "sqlite": "application/vnd.sqlite3",
         # Placeholder
         "unknown": "application/octet-stream",  # Fallback for unknown file types
+        # php
+        "php": "application/x-httpd-php",
+        "php3": "application/x-httpd-php",
+        "php4": "application/x-httpd-php",
+        "php5": "application/x-httpd-php",
+        "php7": "application/x-httpd-php",
+        "phtml": "application/x-httpd-php",
+        "phps": "application/x-httpd-php-source",
+
     }
 
     @staticmethod

crawl4ai/docker_client.py

@@ -73,6 +73,8 @@ class Crawl4aiDockerClient:
     def _prepare_request(self, urls: List[str], browser_config: Optional[BrowserConfig] = None, 
                        crawler_config: Optional[CrawlerRunConfig] = None) -> Dict[str, Any]:
         """Prepare request data from configs."""
+        if self._token:
+            self._http_client.headers["Authorization"] = f"Bearer {self._token}"
         return {
             "urls": urls,
             "browser_config": browser_config.dump() if browser_config else {},
@@ -103,8 +105,6 @@ class Crawl4aiDockerClient:
         crawler_config: Optional[CrawlerRunConfig] = None
     ) -> Union[CrawlResult, List[CrawlResult], AsyncGenerator[CrawlResult, None]]:
         """Execute a crawl operation."""
-        if not self._token:
-            raise Crawl4aiClientError("Authentication required. Call authenticate() first.")
         await self._check_server()
         
         data = self._prepare_request(urls, browser_config, crawler_config)
@@ -140,8 +140,6 @@ class Crawl4aiDockerClient:
 
     async def get_schema(self) -> Dict[str, Any]:
         """Retrieve configuration schemas."""
-        if not self._token:
-            raise Crawl4aiClientError("Authentication required. Call authenticate() first.")
         response = await self._request("GET", "/schema")
         return response.json()
 
@@ -167,4 +165,4 @@ async def main():
         print(schema)
 
 if __name__ == "__main__":
-    asyncio.run(main())
+    asyncio.run(main())

crawl4ai/extraction_strategy.py

@@ -656,11 +656,11 @@ class LLMExtractionStrategy(ExtractionStrategy):
             self.total_usage.total_tokens += usage.total_tokens
 
             try:
-                response = response.choices[0].message.content
+                content = response.choices[0].message.content
                 blocks = None
 
                 if self.force_json_response:
-                    blocks = json.loads(response)
+                    blocks = json.loads(content)
                     if isinstance(blocks, dict):
                         # If it has only one key which calue is list then assign that to blocks, exampled: {"news": [..]}
                         if len(blocks) == 1 and isinstance(list(blocks.values())[0], list):
@@ -673,7 +673,7 @@ class LLMExtractionStrategy(ExtractionStrategy):
                         blocks = blocks
                 else: 
                     # blocks = extract_xml_data(["blocks"], response.choices[0].message.content)["blocks"]
-                    blocks = extract_xml_data(["blocks"], response)["blocks"]
+                    blocks = extract_xml_data(["blocks"], content)["blocks"]
                     blocks = json.loads(blocks)
 
                 for block in blocks:

crawl4ai/utils.py

@@ -32,7 +32,6 @@ import hashlib
 
 from urllib.robotparser import RobotFileParser
 import aiohttp
-from urllib.parse import urlparse, urlunparse
 from functools import lru_cache
 
 from packaging import version
@@ -43,6 +42,37 @@ from itertools import chain
 from collections import deque
 from typing import  Generator, Iterable
 
+import numpy as np
+
+from urllib.parse import (
+    urljoin, urlparse, urlunparse,
+    parse_qsl, urlencode, quote, unquote
+)
+
+
+# Monkey patch to fix wildcard handling in urllib.robotparser
+from urllib.robotparser import RuleLine
+import re
+
+original_applies_to = RuleLine.applies_to
+
+def patched_applies_to(self, filename):
+   # Handle wildcards in paths
+   if '*' in self.path or '%2A' in self.path or self.path in ("*", "%2A"):
+       pattern = self.path.replace('%2A', '*')
+       pattern = re.escape(pattern).replace('\\*', '.*')
+       pattern = '^' + pattern
+       if pattern.endswith('\\$'):
+           pattern = pattern[:-2] + '$'
+       try:
+           return bool(re.match(pattern, filename))
+       except re.error:
+           return original_applies_to(self, filename)
+   return original_applies_to(self, filename)
+
+RuleLine.applies_to = patched_applies_to
+# Monkey patch ends
+
 def chunk_documents(
     documents: Iterable[str],
     chunk_token_threshold: int,
@@ -311,7 +341,7 @@ class RobotsParser:
                 robots_url = f"{scheme}://{domain}/robots.txt"
                 
                 async with aiohttp.ClientSession() as session:
-                    async with session.get(robots_url, timeout=2) as response:
+                    async with session.get(robots_url, timeout=2, ssl=False) as response:
                         if response.status == 200:
                             rules = await response.text()
                             self._cache_rules(domain, rules)
@@ -1517,6 +1547,14 @@ def extract_metadata_using_lxml(html, doc=None):
         content = tag.get("content", "").strip()
         if property_name and content:
             metadata[property_name] = content
+   
+   # Article metadata
+    article_tags = head.xpath('.//meta[starts-with(@property, "article:")]')
+    for tag in article_tags:
+        property_name = tag.get("property", "").strip()
+        content = tag.get("content", "").strip()
+        if property_name and content:
+            metadata[property_name] = content
 
     return metadata
 
@@ -1592,7 +1630,15 @@ def extract_metadata(html, soup=None):
         content = tag.get("content", "").strip()
         if property_name and content:
             metadata[property_name] = content
-
+    
+    # Article metadata
+    article_tags = head.find_all("meta", attrs={"property": re.compile(r"^article:")})
+    for tag in article_tags:
+        property_name = tag.get("property", "").strip()
+        content = tag.get("content", "").strip()
+        if property_name and content:
+            metadata[property_name] = content
+    
     return metadata
 
 
@@ -2061,13 +2107,101 @@ def normalize_url(href, base_url):
     parsed_base = urlparse(base_url)
     if not parsed_base.scheme or not parsed_base.netloc:
         raise ValueError(f"Invalid base URL format: {base_url}")
-
-    # Ensure base_url ends with a trailing slash if it's a directory path
-    if not base_url.endswith('/'):
-        base_url = base_url + '/'
+    
+    if  parsed_base.scheme.lower() not in ["http", "https"]:
+        # Handle special protocols
+        raise ValueError(f"Invalid base URL format: {base_url}")
+    cleaned_href = href.strip()
 
     # Use urljoin to handle all cases
-    normalized = urljoin(base_url, href.strip())
+    return urljoin(base_url, cleaned_href)
+
+
+
+
+def normalize_url(
+    href: str,
+    base_url: str,
+    *,
+    drop_query_tracking=True,
+    sort_query=True,
+    keep_fragment=False,
+    extra_drop_params=None
+):
+    """
+    Extended URL normalizer
+
+    Parameters
+    ----------
+    href : str
+        The raw link extracted from a page.
+    base_url : str
+        The page’s canonical URL (used to resolve relative links).
+    drop_query_tracking : bool (default True)
+        Remove common tracking query parameters.
+    sort_query : bool (default True)
+        Alphabetically sort query keys for deterministic output.
+    keep_fragment : bool (default False)
+        Preserve the hash fragment (#section) if you need in-page links.
+    extra_drop_params : Iterable[str] | None
+        Additional query keys to strip (case-insensitive).
+
+    Returns
+    -------
+    str | None
+        A clean, canonical URL or None if href is empty/None.
+    """
+    if not href:
+        return None
+
+    # Resolve relative paths first
+    full_url = urljoin(base_url, href.strip())
+
+    # Parse once, edit parts, then rebuild
+    parsed = urlparse(full_url)
+
+    # ── netloc ──
+    netloc = parsed.netloc.lower()
+
+    # ── path ──
+    # Strip duplicate slashes and trailing “/” (except root)
+    path = quote(unquote(parsed.path))
+    if path.endswith('/') and path != '/':
+        path = path.rstrip('/')
+
+    # ── query ──
+    query = parsed.query
+    if query:
+        # explode, mutate, then rebuild
+        params = [(k.lower(), v) for k, v in parse_qsl(query, keep_blank_values=True)]
+
+        if drop_query_tracking:
+            default_tracking = {
+                'utm_source', 'utm_medium', 'utm_campaign', 'utm_term',
+                'utm_content', 'gclid', 'fbclid', 'ref', 'ref_src'
+            }
+            if extra_drop_params:
+                default_tracking |= {p.lower() for p in extra_drop_params}
+            params = [(k, v) for k, v in params if k not in default_tracking]
+
+        if sort_query:
+            params.sort(key=lambda kv: kv[0])
+
+        query = urlencode(params, doseq=True) if params else ''
+
+    # ── fragment ──
+    fragment = parsed.fragment if keep_fragment else ''
+
+    # Re-assemble
+    normalized = urlunparse((
+        parsed.scheme,
+        netloc,
+        path,
+        parsed.params,
+        query,
+        fragment
+    ))
+
     return normalized
 
 
@@ -3148,3 +3282,108 @@ def calculate_total_score(
     
     return max(0.0, min(total, 10.0))
 
+
+# Embedding utilities
+async def get_text_embeddings(
+    texts: List[str], 
+    llm_config: Optional[Dict] = None,
+    model_name: str = "sentence-transformers/all-MiniLM-L6-v2",
+    batch_size: int = 32
+) -> np.ndarray:
+    """
+    Compute embeddings for a list of texts using specified model.
+    
+    Args:
+        texts: List of texts to embed
+        llm_config: Optional LLM configuration for API-based embeddings
+        model_name: Model name (used when llm_config is None)
+        batch_size: Batch size for processing
+        
+    Returns:
+        numpy array of embeddings
+    """
+    import numpy as np
+    
+    if not texts:
+        return np.array([])
+    
+    # If LLMConfig provided, use litellm for embeddings
+    if llm_config is not None:
+        from litellm import aembedding
+        
+        # Get embedding model from config or use default
+        embedding_model = llm_config.get('provider', 'text-embedding-3-small')
+        api_base = llm_config.get('base_url', llm_config.get('api_base'))
+        
+        # Prepare kwargs
+        kwargs = {
+            'model': embedding_model,
+            'input': texts,
+            'api_key': llm_config.get('api_token', llm_config.get('api_key'))
+        }
+        
+        if api_base:
+            kwargs['api_base'] = api_base
+            
+        # Handle OpenAI-compatible endpoints
+        if api_base and 'openai/' not in embedding_model:
+            kwargs['model'] = f"openai/{embedding_model}"
+        
+        # Get embeddings
+        response = await aembedding(**kwargs)
+        
+        # Extract embeddings from response
+        embeddings = []
+        for item in response.data:
+            embeddings.append(item['embedding'])
+            
+        return np.array(embeddings)
+    
+    # Default: use sentence-transformers
+    else:
+        # Lazy load to avoid importing heavy libraries unless needed
+        from sentence_transformers import SentenceTransformer
+        
+        # Cache the model in function attribute to avoid reloading
+        if not hasattr(get_text_embeddings, '_models'):
+            get_text_embeddings._models = {}
+        
+        if model_name not in get_text_embeddings._models:
+            get_text_embeddings._models[model_name] = SentenceTransformer(model_name)
+        
+        encoder = get_text_embeddings._models[model_name]
+        
+        # Batch encode for efficiency
+        embeddings = encoder.encode(
+            texts,
+            batch_size=batch_size,
+            show_progress_bar=False,
+            convert_to_numpy=True
+        )
+        
+        return embeddings
+
+
+def get_text_embeddings_sync(
+    texts: List[str],
+    llm_config: Optional[Dict] = None,
+    model_name: str = "sentence-transformers/all-MiniLM-L6-v2",
+    batch_size: int = 32
+) -> np.ndarray:
+    """Synchronous wrapper for get_text_embeddings"""
+    import numpy as np
+    return asyncio.run(get_text_embeddings(texts, llm_config, model_name, batch_size))
+
+
+def cosine_similarity(vec1: np.ndarray, vec2: np.ndarray) -> float:
+    """Calculate cosine similarity between two vectors"""
+    import numpy as np
+    dot_product = np.dot(vec1, vec2)
+    norm_product = np.linalg.norm(vec1) * np.linalg.norm(vec2)
+    return float(dot_product / norm_product) if norm_product != 0 else 0.0
+
+
+def cosine_distance(vec1: np.ndarray, vec2: np.ndarray) -> float:
+    """Calculate cosine distance (1 - similarity) between two vectors"""
+    return 1 - cosine_similarity(vec1, vec2)
+

deploy/docker/api.py

@@ -459,7 +459,7 @@ async def handle_crawl_request(
             #      await crawler.close()
             #  except Exception as close_e:
             #       logger.error(f"Error closing crawler during exception handling: {close_e}")
-            logger.error(f"Error closing crawler during exception handling: {close_e}")
+            logger.error(f"Error closing crawler during exception handling: {str(e)}")
 
         # Measure memory even on error if possible
         end_mem_mb_error = _get_memory_mb()
@@ -518,7 +518,7 @@ async def handle_stream_crawl_request(
             #       await crawler.close()
             #  except Exception as close_e:
             #       logger.error(f"Error closing crawler during stream setup exception: {close_e}")
-            logger.error(f"Error closing crawler during stream setup exception: {close_e}")
+            logger.error(f"Error closing crawler during stream setup exception: {str(e)}")
         logger.error(f"Stream crawl error: {str(e)}", exc_info=True)
         # Raising HTTPException here will prevent streaming response
         raise HTTPException(

deploy/docker/c4ai-doc-context.md

@@ -332,7 +332,7 @@ The `clone()` method:
 ### Key fields to note
 
 1. **`provider`**:  
-- Which LLM provoder to use. 
+- Which LLM provider to use. 
 - Possible values are `"ollama/llama3","groq/llama3-70b-8192","groq/llama3-8b-8192", "openai/gpt-4o-mini" ,"openai/gpt-4o","openai/o1-mini","openai/o1-preview","openai/o3-mini","openai/o3-mini-high","anthropic/claude-3-haiku-20240307","anthropic/claude-3-opus-20240229","anthropic/claude-3-sonnet-20240229","anthropic/claude-3-5-sonnet-20240620","gemini/gemini-pro","gemini/gemini-1.5-pro","gemini/gemini-2.0-flash","gemini/gemini-2.0-flash-exp","gemini/gemini-2.0-flash-lite-preview-02-05","deepseek/deepseek-chat"`<br/>*(default: `"openai/gpt-4o-mini"`)*
 
 2. **`api_token`**:  
@@ -403,7 +403,7 @@ async def main():
 
     md_generator = DefaultMarkdownGenerator(
     content_filter=filter,
-    options={"ignore_links": True}
+    options={"ignore_links": True})
 
     # 4) Crawler run config: skip cache, use extraction
     run_conf = CrawlerRunConfig(
@@ -3760,11 +3760,11 @@ To crawl a live web page, provide the URL starting with `http://` or `https://`,
 
 ```python
 import asyncio
-from crawl4ai import AsyncWebCrawler
+from crawl4ai import AsyncWebCrawler, CacheMode
 from crawl4ai.async_configs import CrawlerRunConfig
 
 async def crawl_web():
-    config = CrawlerRunConfig(bypass_cache=True)
+    config = CrawlerRunConfig(cache_mode=CacheMode.BYPASS)
     async with AsyncWebCrawler() as crawler:
         result = await crawler.arun(
             url="https://en.wikipedia.org/wiki/apple", 
@@ -3785,13 +3785,13 @@ To crawl a local HTML file, prefix the file path with `file://`.
 
 ```python
 import asyncio
-from crawl4ai import AsyncWebCrawler
+from crawl4ai import AsyncWebCrawler, CacheMode
 from crawl4ai.async_configs import CrawlerRunConfig
 
 async def crawl_local_file():
     local_file_path = "/path/to/apple.html"  # Replace with your file path
     file_url = f"file://{local_file_path}"
-    config = CrawlerRunConfig(bypass_cache=True)
+    config = CrawlerRunConfig(cache_mode=CacheMode.BYPASS)
     
     async with AsyncWebCrawler() as crawler:
         result = await crawler.arun(url=file_url, config=config)
@@ -3810,13 +3810,13 @@ To crawl raw HTML content, prefix the HTML string with `raw:`.
 
 ```python
 import asyncio
-from crawl4ai import AsyncWebCrawler
+from crawl4ai import AsyncWebCrawler, CacheMode
 from crawl4ai.async_configs import CrawlerRunConfig
 
 async def crawl_raw_html():
     raw_html = "<html><body><h1>Hello, World!</h1></body></html>"
     raw_html_url = f"raw:{raw_html}"
-    config = CrawlerRunConfig(bypass_cache=True)
+    config = CrawlerRunConfig(cache_mode=CacheMode.BYPASS)
     
     async with AsyncWebCrawler() as crawler:
         result = await crawler.arun(url=raw_html_url, config=config)
@@ -3845,7 +3845,7 @@ import os
 import sys
 import asyncio
 from pathlib import Path
-from crawl4ai import AsyncWebCrawler
+from crawl4ai import AsyncWebCrawler, CacheMode
 from crawl4ai.async_configs import CrawlerRunConfig
 
 async def main():
@@ -3856,7 +3856,7 @@ async def main():
     async with AsyncWebCrawler() as crawler:
         # Step 1: Crawl the Web URL
         print("\n=== Step 1: Crawling the Wikipedia URL ===")
-        web_config = CrawlerRunConfig(bypass_cache=True)
+        web_config = CrawlerRunConfig(cache_mode=CacheMode.BYPASS)
         result = await crawler.arun(url=wikipedia_url, config=web_config)
 
         if not result.success:
@@ -3871,7 +3871,7 @@ async def main():
         # Step 2: Crawl from the Local HTML File
         print("=== Step 2: Crawling from the Local HTML File ===")
         file_url = f"file://{html_file_path.resolve()}"
-        file_config = CrawlerRunConfig(bypass_cache=True)
+        file_config = CrawlerRunConfig(cache_mode=CacheMode.BYPASS)
         local_result = await crawler.arun(url=file_url, config=file_config)
 
         if not local_result.success:
@@ -3887,7 +3887,7 @@ async def main():
         with open(html_file_path, 'r', encoding='utf-8') as f:
             raw_html_content = f.read()
         raw_html_url = f"raw:{raw_html_content}"
-        raw_config = CrawlerRunConfig(bypass_cache=True)
+        raw_config = CrawlerRunConfig(cache_mode=CacheMode.BYPASS)
         raw_result = await crawler.arun(url=raw_html_url, config=raw_config)
 
         if not raw_result.success:
@@ -4152,7 +4152,7 @@ prune_filter = PruningContentFilter(
 For intelligent content filtering and high-quality markdown generation, you can use the **LLMContentFilter**. This filter leverages LLMs to generate relevant markdown while preserving the original content's meaning and structure:
 
 ```python
-from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, LLMConfig
+from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, LLMConfig, DefaultMarkdownGenerator
 from crawl4ai.content_filter_strategy import LLMContentFilter
 
 async def main():
@@ -4175,8 +4175,13 @@ async def main():
         verbose=True
     )
 
+    md_generator = DefaultMarkdownGenerator(
+        content_filter=filter,
+        options={"ignore_links": True}
+    )
+
     config = CrawlerRunConfig(
-        content_filter=filter
+        markdown_generator=md_generator
     )
 
     async with AsyncWebCrawler() as crawler:
@@ -5428,29 +5433,38 @@ Sometimes you need a visual record of a page or a PDF “printout.” Crawl4AI c
 ```python
 import os, asyncio
 from base64 import b64decode
-from crawl4ai import AsyncWebCrawler, CacheMode
+from crawl4ai import AsyncWebCrawler, CacheMode, CrawlerRunConfig
 
 async def main():
+    run_config = CrawlerRunConfig(
+        cache_mode=CacheMode.BYPASS,
+        screenshot=True,
+        pdf=True
+    )
+
     async with AsyncWebCrawler() as crawler:
         result = await crawler.arun(
             url="https://en.wikipedia.org/wiki/List_of_common_misconceptions",
-            cache_mode=CacheMode.BYPASS,
-            pdf=True,
-            screenshot=True
+            config=run_config
         )
-        
         if result.success:
-            # Save screenshot
+            print(f"Screenshot data present: {result.screenshot is not None}")
+            print(f"PDF data present: {result.pdf is not None}")
+
             if result.screenshot:
+                print(f"[OK] Screenshot captured, size: {len(result.screenshot)} bytes")
                 with open("wikipedia_screenshot.png", "wb") as f:
                     f.write(b64decode(result.screenshot))
-            
-            # Save PDF
+            else:
+                print("[WARN] Screenshot data is None.")
+
             if result.pdf:
+                print(f"[OK] PDF captured, size: {len(result.pdf)} bytes")
                 with open("wikipedia_page.pdf", "wb") as f:
                     f.write(result.pdf)
-            
-            print("[OK] PDF & screenshot captured.")
+            else:
+                print("[WARN] PDF data is None.")
+
         else:
             print("[ERROR]", result.error_message)
 

deploy/docker/schemas.py

@@ -12,8 +12,7 @@ class CrawlRequest(BaseModel):
 class MarkdownRequest(BaseModel):
     """Request body for the /md endpoint."""
     url: str                    = Field(...,  description="Absolute http/https URL to fetch")
-    f:   FilterType             = Field(FilterType.FIT,
-                                        description="Content‑filter strategy: FIT, RAW, BM25, or LLM")
+    f:   FilterType             = Field(FilterType.FIT, description="Content‑filter strategy: fit, raw, bm25, or llm")
     q:   Optional[str] = Field(None,  description="Query string used by BM25/LLM filters")
     c:   Optional[str] = Field("0",   description="Cache‑bust / revision counter")
 

deploy/docker/static/playground/index.html

@@ -671,6 +671,16 @@
                         method: 'GET',
                         headers: { 'Accept': 'application/json' }
                     });
+                    responseData = await response.json();
+                    const time = Math.round(performance.now() - startTime);
+                    if (!response.ok) {
+                        updateStatus('error', time);
+                        throw new Error(responseData.error || 'Request failed');
+                    }
+                    updateStatus('success', time);
+                    document.querySelector('#response-content code').textContent = JSON.stringify(responseData, null, 2);
+                    document.querySelector('#response-content code').className = 'json hljs';
+                    forceHighlightElement(document.querySelector('#response-content code'));
                 } else if (endpoint === 'crawl_stream') {
                     // Stream processing
                     response = await fetch(api, {

docs/examples/adaptive_crawling/README.md

@@ -0,0 +1,85 @@
+# Adaptive Crawling Examples
+
+This directory contains examples demonstrating various aspects of Crawl4AI's Adaptive Crawling feature.
+
+## Examples Overview
+
+### 1. `basic_usage.py`
+- Simple introduction to adaptive crawling
+- Uses default statistical strategy
+- Shows how to get crawl statistics and relevant content
+
+### 2. `embedding_strategy.py` ⭐ NEW
+- Demonstrates the embedding-based strategy for semantic understanding
+- Shows query expansion and irrelevance detection
+- Includes configuration for both local and API-based embeddings
+
+### 3. `embedding_vs_statistical.py` ⭐ NEW
+- Direct comparison between statistical and embedding strategies
+- Helps you choose the right strategy for your use case
+- Shows performance and accuracy trade-offs
+
+### 4. `embedding_configuration.py` ⭐ NEW
+- Advanced configuration options for embedding strategy
+- Parameter tuning guide for different scenarios
+- Examples for research, exploration, and quality-focused crawling
+
+### 5. `advanced_configuration.py`
+- Shows various configuration options for both strategies
+- Demonstrates threshold tuning and performance optimization
+
+### 6. `custom_strategies.py`
+- How to implement your own crawling strategy
+- Extends the base CrawlStrategy class
+- Advanced use case for specialized requirements
+
+### 7. `export_import_kb.py`
+- Export crawled knowledge base to JSONL
+- Import and continue crawling from saved state
+- Useful for building persistent knowledge bases
+
+## Quick Start
+
+For your first adaptive crawling experience, run:
+
+```bash
+python basic_usage.py
+```
+
+To try the new embedding strategy with semantic understanding:
+
+```bash
+python embedding_strategy.py
+```
+
+To compare strategies and see which works best for your use case:
+
+```bash
+python embedding_vs_statistical.py
+```
+
+## Strategy Selection Guide
+
+### Use Statistical Strategy (Default) When:
+- Working with technical documentation
+- Queries contain specific terms or code
+- Speed is critical
+- No API access available
+
+### Use Embedding Strategy When:
+- Queries are conceptual or ambiguous
+- Need semantic understanding beyond exact matches
+- Want to detect irrelevant content
+- Working with diverse content sources
+
+## Requirements
+
+- Crawl4AI installed
+- For embedding strategy with local models: `sentence-transformers`
+- For embedding strategy with OpenAI: Set `OPENAI_API_KEY` environment variable
+
+## Learn More
+
+- [Adaptive Crawling Documentation](https://docs.crawl4ai.com/core/adaptive-crawling/)
+- [Mathematical Framework](https://github.com/unclecode/crawl4ai/blob/main/PROGRESSIVE_CRAWLING.md)
+- [Blog: The Adaptive Crawling Revolution](https://docs.crawl4ai.com/blog/adaptive-crawling-revolution/)

docs/examples/adaptive_crawling/advanced_configuration.py

@@ -0,0 +1,207 @@
+"""
+Advanced Adaptive Crawling Configuration
+
+This example demonstrates all configuration options available for adaptive crawling,
+including threshold tuning, persistence, and custom parameters.
+"""
+
+import asyncio
+from pathlib import Path
+from crawl4ai import AsyncWebCrawler, AdaptiveCrawler, AdaptiveConfig
+
+
+async def main():
+    """Demonstrate advanced configuration options"""
+    
+    # Example 1: Custom thresholds for different use cases
+    print("="*60)
+    print("EXAMPLE 1: Custom Confidence Thresholds")
+    print("="*60)
+    
+    # High-precision configuration (exhaustive crawling)
+    high_precision_config = AdaptiveConfig(
+        confidence_threshold=0.9,      # Very high confidence required
+        max_pages=50,                  # Allow more pages
+        top_k_links=5,                 # Follow more links per page
+        min_gain_threshold=0.02        # Lower threshold to continue
+    )
+    
+    # Balanced configuration (default use case)
+    balanced_config = AdaptiveConfig(
+        confidence_threshold=0.7,      # Moderate confidence
+        max_pages=20,                  # Reasonable limit
+        top_k_links=3,                 # Moderate branching
+        min_gain_threshold=0.05        # Standard gain threshold
+    )
+    
+    # Quick exploration configuration
+    quick_config = AdaptiveConfig(
+        confidence_threshold=0.5,      # Lower confidence acceptable
+        max_pages=10,                  # Strict limit
+        top_k_links=2,                 # Minimal branching
+        min_gain_threshold=0.1         # High gain required
+    )
+    
+    async with AsyncWebCrawler(verbose=False) as crawler:
+        # Test different configurations
+        for config_name, config in [
+            ("High Precision", high_precision_config),
+            ("Balanced", balanced_config),
+            ("Quick Exploration", quick_config)
+        ]:
+            print(f"\nTesting {config_name} configuration...")
+            adaptive = AdaptiveCrawler(crawler, config=config)
+            
+            result = await adaptive.digest(
+                start_url="https://httpbin.org",
+                query="http headers authentication"
+            )
+            
+            print(f"  - Pages crawled: {len(result.crawled_urls)}")
+            print(f"  - Confidence achieved: {adaptive.confidence:.2%}")
+            print(f"  - Coverage score: {adaptive.coverage_stats['coverage']:.2f}")
+    
+    # Example 2: Persistence and state management
+    print("\n" + "="*60)
+    print("EXAMPLE 2: State Persistence")
+    print("="*60)
+    
+    state_file = "crawl_state_demo.json"
+    
+    # Configuration with persistence
+    persistent_config = AdaptiveConfig(
+        confidence_threshold=0.8,
+        max_pages=30,
+        save_state=True,              # Enable auto-save
+        state_path=state_file         # Specify save location
+    )
+    
+    async with AsyncWebCrawler(verbose=False) as crawler:
+        # First crawl - will be interrupted
+        print("\nStarting initial crawl (will interrupt after 5 pages)...")
+        
+        interrupt_config = AdaptiveConfig(
+            confidence_threshold=0.8,
+            max_pages=5,              # Artificially low to simulate interruption
+            save_state=True,
+            state_path=state_file
+        )
+        
+        adaptive = AdaptiveCrawler(crawler, config=interrupt_config)
+        result1 = await adaptive.digest(
+            start_url="https://docs.python.org/3/",
+            query="exception handling try except finally"
+        )
+        
+        print(f"First crawl completed: {len(result1.crawled_urls)} pages")
+        print(f"Confidence reached: {adaptive.confidence:.2%}")
+        
+        # Resume crawl with higher page limit
+        print("\nResuming crawl from saved state...")
+        
+        resume_config = AdaptiveConfig(
+            confidence_threshold=0.8,
+            max_pages=20,             # Increase limit
+            save_state=True,
+            state_path=state_file
+        )
+        
+        adaptive2 = AdaptiveCrawler(crawler, config=resume_config)
+        result2 = await adaptive2.digest(
+            start_url="https://docs.python.org/3/",
+            query="exception handling try except finally",
+            resume_from=state_file
+        )
+        
+        print(f"Resumed crawl completed: {len(result2.crawled_urls)} total pages")
+        print(f"Final confidence: {adaptive2.confidence:.2%}")
+        
+        # Clean up
+        Path(state_file).unlink(missing_ok=True)
+    
+    # Example 3: Link selection strategies
+    print("\n" + "="*60)
+    print("EXAMPLE 3: Link Selection Strategies")
+    print("="*60)
+    
+    # Conservative link following
+    conservative_config = AdaptiveConfig(
+        confidence_threshold=0.7,
+        max_pages=15,
+        top_k_links=1,                # Only follow best link
+        min_gain_threshold=0.15       # High threshold
+    )
+    
+    # Aggressive link following
+    aggressive_config = AdaptiveConfig(
+        confidence_threshold=0.7,
+        max_pages=15,
+        top_k_links=10,               # Follow many links
+        min_gain_threshold=0.01       # Very low threshold
+    )
+    
+    async with AsyncWebCrawler(verbose=False) as crawler:
+        for strategy_name, config in [
+            ("Conservative", conservative_config),
+            ("Aggressive", aggressive_config)
+        ]:
+            print(f"\n{strategy_name} link selection:")
+            adaptive = AdaptiveCrawler(crawler, config=config)
+            
+            result = await adaptive.digest(
+                start_url="https://httpbin.org",
+                query="api endpoints"
+            )
+            
+            # Analyze crawl pattern
+            print(f"  - Total pages: {len(result.crawled_urls)}")
+            print(f"  - Unique domains: {len(set(url.split('/')[2] for url in result.crawled_urls))}")
+            print(f"  - Max depth reached: {max(url.count('/') for url in result.crawled_urls) - 2}")
+            
+            # Show saturation trend
+            if hasattr(result, 'new_terms_history') and result.new_terms_history:
+                print(f"  - New terms discovered: {result.new_terms_history[:5]}...")
+                print(f"  - Saturation trend: {'decreasing' if result.new_terms_history[-1] < result.new_terms_history[0] else 'increasing'}")
+    
+    # Example 4: Monitoring crawl progress
+    print("\n" + "="*60)
+    print("EXAMPLE 4: Progress Monitoring")
+    print("="*60)
+    
+    # Configuration with detailed monitoring
+    monitor_config = AdaptiveConfig(
+        confidence_threshold=0.75,
+        max_pages=10,
+        top_k_links=3
+    )
+    
+    async with AsyncWebCrawler(verbose=False) as crawler:
+        adaptive = AdaptiveCrawler(crawler, config=monitor_config)
+        
+        # Start crawl
+        print("\nMonitoring crawl progress...")
+        result = await adaptive.digest(
+            start_url="https://httpbin.org",
+            query="http methods headers"
+        )
+        
+        # Detailed statistics
+        print("\nDetailed crawl analysis:")
+        adaptive.print_stats(detailed=True)
+        
+        # Export for analysis
+        print("\nExporting knowledge base for external analysis...")
+        adaptive.export_knowledge_base("knowledge_export_demo.jsonl")
+        print("Knowledge base exported to: knowledge_export_demo.jsonl")
+        
+        # Show sample of exported data
+        with open("knowledge_export_demo.jsonl", 'r') as f:
+            first_line = f.readline()
+            print(f"Sample export: {first_line[:100]}...")
+        
+        # Clean up
+        Path("knowledge_export_demo.jsonl").unlink(missing_ok=True)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

docs/examples/adaptive_crawling/basic_usage.py

@@ -0,0 +1,76 @@
+"""
+Basic Adaptive Crawling Example
+
+This example demonstrates the simplest use case of adaptive crawling:
+finding information about a specific topic and knowing when to stop.
+"""
+
+import asyncio
+from crawl4ai import AsyncWebCrawler, AdaptiveCrawler
+
+
+async def main():
+    """Basic adaptive crawling example"""
+    
+    # Initialize the crawler
+    async with AsyncWebCrawler(verbose=True) as crawler:
+        # Create an adaptive crawler with default settings (statistical strategy)
+        adaptive = AdaptiveCrawler(crawler)
+        
+        # Note: You can also use embedding strategy for semantic understanding:
+        # from crawl4ai import AdaptiveConfig
+        # config = AdaptiveConfig(strategy="embedding")
+        # adaptive = AdaptiveCrawler(crawler, config)
+        
+        # Start adaptive crawling
+        print("Starting adaptive crawl for Python async programming information...")
+        result = await adaptive.digest(
+            start_url="https://docs.python.org/3/library/asyncio.html",
+            query="async await context managers coroutines"
+        )
+        
+        # Display crawl statistics
+        print("\n" + "="*50)
+        print("CRAWL STATISTICS")
+        print("="*50)
+        adaptive.print_stats(detailed=False)
+        
+        # Get the most relevant content found
+        print("\n" + "="*50)
+        print("MOST RELEVANT PAGES")
+        print("="*50)
+        
+        relevant_pages = adaptive.get_relevant_content(top_k=5)
+        for i, page in enumerate(relevant_pages, 1):
+            print(f"\n{i}. {page['url']}")
+            print(f"   Relevance Score: {page['score']:.2%}")
+            
+            # Show a snippet of the content
+            content = page['content'] or ""
+            if content:
+                snippet = content[:200].replace('\n', ' ')
+                if len(content) > 200:
+                    snippet += "..."
+                print(f"   Preview: {snippet}")
+        
+        # Show final confidence
+        print(f"\n{'='*50}")
+        print(f"Final Confidence: {adaptive.confidence:.2%}")
+        print(f"Total Pages Crawled: {len(result.crawled_urls)}")
+        print(f"Knowledge Base Size: {len(adaptive.state.knowledge_base)} documents")
+        
+        # Example: Check if we can answer specific questions
+        print(f"\n{'='*50}")
+        print("INFORMATION SUFFICIENCY CHECK")
+        print(f"{'='*50}")
+        
+        if adaptive.confidence >= 0.8:
+            print("✓ High confidence - can answer detailed questions about async Python")
+        elif adaptive.confidence >= 0.6:
+            print("~ Moderate confidence - can answer basic questions") 
+        else:
+            print("✗ Low confidence - need more information")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

docs/examples/adaptive_crawling/custom_strategies.py

@@ -0,0 +1,373 @@
+"""
+Custom Adaptive Crawling Strategies
+
+This example demonstrates how to implement custom scoring strategies
+for domain-specific crawling needs.
+"""
+
+import asyncio
+import re
+from typing import List, Dict, Set
+from crawl4ai import AsyncWebCrawler, AdaptiveCrawler, AdaptiveConfig
+from crawl4ai.adaptive_crawler import CrawlState, Link
+import math
+
+
+class APIDocumentationStrategy:
+    """
+    Custom strategy optimized for API documentation crawling.
+    Prioritizes endpoint references, code examples, and parameter descriptions.
+    """
+    
+    def __init__(self):
+        # Keywords that indicate high-value API documentation
+        self.api_keywords = {
+            'endpoint', 'request', 'response', 'parameter', 'authentication',
+            'header', 'body', 'query', 'path', 'method', 'get', 'post', 'put',
+            'delete', 'patch', 'status', 'code', 'example', 'curl', 'python'
+        }
+        
+        # URL patterns that typically contain API documentation
+        self.valuable_patterns = [
+            r'/api/',
+            r'/reference/',
+            r'/endpoints?/',
+            r'/methods?/',
+            r'/resources?/'
+        ]
+        
+        # Patterns to avoid
+        self.avoid_patterns = [
+            r'/blog/',
+            r'/news/',
+            r'/about/',
+            r'/contact/',
+            r'/legal/'
+        ]
+    
+    def score_link(self, link: Link, query: str, state: CrawlState) -> float:
+        """Custom link scoring for API documentation"""
+        score = 1.0
+        url = link.href.lower()
+        
+        # Boost API-related URLs
+        for pattern in self.valuable_patterns:
+            if re.search(pattern, url):
+                score *= 2.0
+                break
+        
+        # Reduce score for non-API content
+        for pattern in self.avoid_patterns:
+            if re.search(pattern, url):
+                score *= 0.1
+                break
+        
+        # Boost if preview contains API keywords
+        if link.text:
+            preview_lower = link.text.lower()
+            keyword_count = sum(1 for kw in self.api_keywords if kw in preview_lower)
+            score *= (1 + keyword_count * 0.2)
+        
+        # Prioritize shallow URLs (likely overview pages)
+        depth = url.count('/') - 2  # Subtract protocol slashes
+        if depth <= 3:
+            score *= 1.5
+        elif depth > 6:
+            score *= 0.5
+        
+        return score
+    
+    def calculate_api_coverage(self, state: CrawlState, query: str) -> Dict[str, float]:
+        """Calculate specialized coverage metrics for API documentation"""
+        metrics = {
+            'endpoint_coverage': 0.0,
+            'example_coverage': 0.0,
+            'parameter_coverage': 0.0
+        }
+        
+        # Analyze knowledge base for API-specific content
+        endpoint_patterns = [r'GET\s+/', r'POST\s+/', r'PUT\s+/', r'DELETE\s+/']
+        example_patterns = [r'```\w+', r'curl\s+-', r'import\s+requests']
+        param_patterns = [r'param(?:eter)?s?\s*:', r'required\s*:', r'optional\s*:']
+        
+        total_docs = len(state.knowledge_base)
+        if total_docs == 0:
+            return metrics
+        
+        docs_with_endpoints = 0
+        docs_with_examples = 0
+        docs_with_params = 0
+        
+        for doc in state.knowledge_base:
+            content = doc.markdown.raw_markdown if hasattr(doc, 'markdown') else str(doc)
+            
+            # Check for endpoints
+            if any(re.search(pattern, content, re.IGNORECASE) for pattern in endpoint_patterns):
+                docs_with_endpoints += 1
+            
+            # Check for examples
+            if any(re.search(pattern, content, re.IGNORECASE) for pattern in example_patterns):
+                docs_with_examples += 1
+            
+            # Check for parameters
+            if any(re.search(pattern, content, re.IGNORECASE) for pattern in param_patterns):
+                docs_with_params += 1
+        
+        metrics['endpoint_coverage'] = docs_with_endpoints / total_docs
+        metrics['example_coverage'] = docs_with_examples / total_docs
+        metrics['parameter_coverage'] = docs_with_params / total_docs
+        
+        return metrics
+
+
+class ResearchPaperStrategy:
+    """
+    Strategy optimized for crawling research papers and academic content.
+    Prioritizes citations, abstracts, and methodology sections.
+    """
+    
+    def __init__(self):
+        self.academic_keywords = {
+            'abstract', 'introduction', 'methodology', 'results', 'conclusion',
+            'references', 'citation', 'paper', 'study', 'research', 'analysis',
+            'hypothesis', 'experiment', 'findings', 'doi'
+        }
+        
+        self.citation_patterns = [
+            r'\[\d+\]',  # [1] style citations
+            r'\(\w+\s+\d{4}\)',  # (Author 2024) style
+            r'doi:\s*\S+',  # DOI references
+        ]
+    
+    def calculate_academic_relevance(self, content: str, query: str) -> float:
+        """Calculate relevance score for academic content"""
+        score = 0.0
+        content_lower = content.lower()
+        
+        # Check for academic keywords
+        keyword_matches = sum(1 for kw in self.academic_keywords if kw in content_lower)
+        score += keyword_matches * 0.1
+        
+        # Check for citations
+        citation_count = sum(
+            len(re.findall(pattern, content)) 
+            for pattern in self.citation_patterns
+        )
+        score += min(citation_count * 0.05, 1.0)  # Cap at 1.0
+        
+        # Check for query terms in academic context
+        query_terms = query.lower().split()
+        for term in query_terms:
+            # Boost if term appears near academic keywords
+            for keyword in ['abstract', 'conclusion', 'results']:
+                if keyword in content_lower:
+                    section = content_lower[content_lower.find(keyword):content_lower.find(keyword) + 500]
+                    if term in section:
+                        score += 0.2
+        
+        return min(score, 2.0)  # Cap total score
+
+
+async def demo_custom_strategies():
+    """Demonstrate custom strategy usage"""
+    
+    # Example 1: API Documentation Strategy
+    print("="*60)
+    print("EXAMPLE 1: Custom API Documentation Strategy")
+    print("="*60)
+    
+    api_strategy = APIDocumentationStrategy()
+    
+    async with AsyncWebCrawler() as crawler:
+        # Standard adaptive crawler
+        config = AdaptiveConfig(
+            confidence_threshold=0.8,
+            max_pages=15
+        )
+        
+        adaptive = AdaptiveCrawler(crawler, config)
+        
+        # Override link scoring with custom strategy
+        original_rank_links = adaptive._rank_links
+        
+        def custom_rank_links(links, query, state):
+            # Apply custom scoring
+            scored_links = []
+            for link in links:
+                base_score = api_strategy.score_link(link, query, state)
+                scored_links.append((link, base_score))
+            
+            # Sort by score
+            scored_links.sort(key=lambda x: x[1], reverse=True)
+            return [link for link, _ in scored_links[:config.top_k_links]]
+        
+        adaptive._rank_links = custom_rank_links
+        
+        # Crawl API documentation
+        print("\nCrawling API documentation with custom strategy...")
+        state = await adaptive.digest(
+            start_url="https://httpbin.org",
+            query="api endpoints authentication headers"
+        )
+        
+        # Calculate custom metrics
+        api_metrics = api_strategy.calculate_api_coverage(state, "api endpoints")
+        
+        print(f"\nResults:")
+        print(f"Pages crawled: {len(state.crawled_urls)}")
+        print(f"Confidence: {adaptive.confidence:.2%}")
+        print(f"\nAPI-Specific Metrics:")
+        print(f"  - Endpoint coverage: {api_metrics['endpoint_coverage']:.2%}")
+        print(f"  - Example coverage: {api_metrics['example_coverage']:.2%}")
+        print(f"  - Parameter coverage: {api_metrics['parameter_coverage']:.2%}")
+    
+    # Example 2: Combined Strategy
+    print("\n" + "="*60)
+    print("EXAMPLE 2: Hybrid Strategy Combining Multiple Approaches")
+    print("="*60)
+    
+    class HybridStrategy:
+        """Combines multiple strategies with weights"""
+        
+        def __init__(self):
+            self.api_strategy = APIDocumentationStrategy()
+            self.research_strategy = ResearchPaperStrategy()
+            self.weights = {
+                'api': 0.7,
+                'research': 0.3
+            }
+        
+        def score_content(self, content: str, query: str) -> float:
+            # Get scores from each strategy
+            api_score = self._calculate_api_score(content, query)
+            research_score = self.research_strategy.calculate_academic_relevance(content, query)
+            
+            # Weighted combination
+            total_score = (
+                api_score * self.weights['api'] +
+                research_score * self.weights['research']
+            )
+            
+            return total_score
+        
+        def _calculate_api_score(self, content: str, query: str) -> float:
+            # Simplified API scoring based on keyword presence
+            content_lower = content.lower()
+            api_keywords = self.api_strategy.api_keywords
+            
+            keyword_count = sum(1 for kw in api_keywords if kw in content_lower)
+            return min(keyword_count * 0.1, 2.0)
+    
+    hybrid_strategy = HybridStrategy()
+    
+    async with AsyncWebCrawler() as crawler:
+        adaptive = AdaptiveCrawler(crawler)
+        
+        # Crawl with hybrid scoring
+        print("\nTesting hybrid strategy on technical documentation...")
+        state = await adaptive.digest(
+            start_url="https://docs.python.org/3/library/asyncio.html",
+            query="async await coroutines api"
+        )
+        
+        # Analyze results with hybrid strategy
+        print(f"\nHybrid Strategy Analysis:")
+        total_score = 0
+        for doc in adaptive.get_relevant_content(top_k=5):
+            content = doc['content'] or ""
+            score = hybrid_strategy.score_content(content, "async await api")
+            total_score += score
+            print(f"  - {doc['url'][:50]}... Score: {score:.2f}")
+        
+        print(f"\nAverage hybrid score: {total_score/5:.2f}")
+
+
+async def demo_performance_optimization():
+    """Demonstrate performance optimization with custom strategies"""
+    
+    print("\n" + "="*60)
+    print("EXAMPLE 3: Performance-Optimized Strategy")
+    print("="*60)
+    
+    class PerformanceOptimizedStrategy:
+        """Strategy that balances thoroughness with speed"""
+        
+        def __init__(self):
+            self.url_cache: Set[str] = set()
+            self.domain_scores: Dict[str, float] = {}
+        
+        def should_crawl_domain(self, url: str) -> bool:
+            """Implement domain-level filtering"""
+            domain = url.split('/')[2] if url.startswith('http') else url
+            
+            # Skip if we've already crawled many pages from this domain
+            domain_count = sum(1 for cached in self.url_cache if domain in cached)
+            if domain_count > 5:
+                return False
+            
+            # Skip low-scoring domains
+            if domain in self.domain_scores and self.domain_scores[domain] < 0.3:
+                return False
+            
+            return True
+        
+        def update_domain_score(self, url: str, relevance: float):
+            """Track domain-level performance"""
+            domain = url.split('/')[2] if url.startswith('http') else url
+            
+            if domain not in self.domain_scores:
+                self.domain_scores[domain] = relevance
+            else:
+                # Moving average
+                self.domain_scores[domain] = (
+                    0.7 * self.domain_scores[domain] + 0.3 * relevance
+                )
+    
+    perf_strategy = PerformanceOptimizedStrategy()
+    
+    async with AsyncWebCrawler() as crawler:
+        config = AdaptiveConfig(
+            confidence_threshold=0.7,
+            max_pages=10,
+            top_k_links=2  # Fewer links for speed
+        )
+        
+        adaptive = AdaptiveCrawler(crawler, config)
+        
+        # Track performance
+        import time
+        start_time = time.time()
+        
+        state = await adaptive.digest(
+            start_url="https://httpbin.org",
+            query="http methods headers"
+        )
+        
+        elapsed = time.time() - start_time
+        
+        print(f"\nPerformance Results:")
+        print(f"  - Time elapsed: {elapsed:.2f} seconds")
+        print(f"  - Pages crawled: {len(state.crawled_urls)}")
+        print(f"  - Pages per second: {len(state.crawled_urls)/elapsed:.2f}")
+        print(f"  - Final confidence: {adaptive.confidence:.2%}")
+        print(f"  - Efficiency: {adaptive.confidence/len(state.crawled_urls):.2%} confidence per page")
+
+
+async def main():
+    """Run all demonstrations"""
+    try:
+        await demo_custom_strategies()
+        await demo_performance_optimization()
+        
+        print("\n" + "="*60)
+        print("All custom strategy examples completed!")
+        print("="*60)
+        
+    except Exception as e:
+        print(f"Error: {e}")
+        import traceback
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

docs/examples/adaptive_crawling/embedding_configuration.py

@@ -0,0 +1,206 @@
+"""
+Advanced Embedding Configuration Example
+
+This example demonstrates all configuration options available for the
+embedding strategy, including fine-tuning parameters for different use cases.
+"""
+
+import asyncio
+import os
+from crawl4ai import AsyncWebCrawler, AdaptiveCrawler, AdaptiveConfig
+
+
+async def test_configuration(name: str, config: AdaptiveConfig, url: str, query: str):
+    """Test a specific configuration"""
+    print(f"\n{'='*60}")
+    print(f"Configuration: {name}")
+    print(f"{'='*60}")
+    
+    async with AsyncWebCrawler(verbose=False) as crawler:
+        adaptive = AdaptiveCrawler(crawler, config)
+        result = await adaptive.digest(start_url=url, query=query)
+        
+        print(f"Pages crawled: {len(result.crawled_urls)}")
+        print(f"Final confidence: {adaptive.confidence:.1%}")
+        print(f"Stopped reason: {result.metrics.get('stopped_reason', 'max_pages')}")
+        
+        if result.metrics.get('is_irrelevant', False):
+            print("⚠️  Query detected as irrelevant!")
+        
+        return result
+
+
+async def main():
+    """Demonstrate various embedding configurations"""
+    
+    print("EMBEDDING STRATEGY CONFIGURATION EXAMPLES")
+    print("=" * 60)
+    
+    # Base URL and query for testing
+    test_url = "https://docs.python.org/3/library/asyncio.html"
+    
+    # 1. Default Configuration
+    config_default = AdaptiveConfig(
+        strategy="embedding",
+        max_pages=10
+    )
+    
+    await test_configuration(
+        "Default Settings",
+        config_default,
+        test_url,
+        "async programming patterns"
+    )
+    
+    # 2. Strict Coverage Requirements
+    config_strict = AdaptiveConfig(
+        strategy="embedding",
+        max_pages=20,
+        
+        # Stricter similarity requirements
+        embedding_k_exp=5.0,  # Default is 3.0, higher = stricter
+        embedding_coverage_radius=0.15,  # Default is 0.2, lower = stricter
+        
+        # Higher validation threshold
+        embedding_validation_min_score=0.6,  # Default is 0.3
+        
+        # More query variations for better coverage
+        n_query_variations=15  # Default is 10
+    )
+    
+    await test_configuration(
+        "Strict Coverage (Research/Academic)",
+        config_strict,
+        test_url,
+        "comprehensive guide async await"
+    )
+    
+    # 3. Fast Exploration
+    config_fast = AdaptiveConfig(
+        strategy="embedding",
+        max_pages=10,
+        top_k_links=5,  # Follow more links per page
+        
+        # Relaxed requirements for faster convergence
+        embedding_k_exp=1.0,  # Lower = more lenient
+        embedding_min_relative_improvement=0.05,  # Stop earlier
+        
+        # Lower quality thresholds
+        embedding_quality_min_confidence=0.5,  # Display lower confidence
+        embedding_quality_max_confidence=0.85,
+        
+        # Fewer query variations for speed
+        n_query_variations=5
+    )
+    
+    await test_configuration(
+        "Fast Exploration (Quick Overview)",
+        config_fast,
+        test_url,
+        "async basics"
+    )
+    
+    # 4. Irrelevance Detection Focus
+    config_irrelevance = AdaptiveConfig(
+        strategy="embedding",
+        max_pages=5,
+        
+        # Aggressive irrelevance detection
+        embedding_min_confidence_threshold=0.2,  # Higher threshold (default 0.1)
+        embedding_k_exp=5.0,  # Strict similarity
+        
+        # Quick stopping for irrelevant content
+        embedding_min_relative_improvement=0.15
+    )
+    
+    await test_configuration(
+        "Irrelevance Detection",
+        config_irrelevance,
+        test_url,
+        "recipe for chocolate cake"  # Irrelevant query
+    )
+    
+    # 5. High-Quality Knowledge Base
+    config_quality = AdaptiveConfig(
+        strategy="embedding",
+        max_pages=30,
+        
+        # Deduplication settings
+        embedding_overlap_threshold=0.75,  # More aggressive deduplication
+        
+        # Quality focus
+        embedding_validation_min_score=0.5,
+        embedding_quality_scale_factor=1.0,  # Linear quality mapping
+        
+        # Balanced parameters
+        embedding_k_exp=3.0,
+        embedding_nearest_weight=0.8,  # Focus on best matches
+        embedding_top_k_weight=0.2
+    )
+    
+    await test_configuration(
+        "High-Quality Knowledge Base",
+        config_quality,
+        test_url,
+        "asyncio advanced patterns best practices"
+    )
+    
+    # 6. Custom Embedding Provider
+    if os.getenv('OPENAI_API_KEY'):
+        config_openai = AdaptiveConfig(
+            strategy="embedding",
+            max_pages=10,
+            
+            # Use OpenAI embeddings
+            embedding_llm_config={
+                'provider': 'openai/text-embedding-3-small',
+                'api_token': os.getenv('OPENAI_API_KEY')
+            },
+            
+            # OpenAI embeddings are high quality, can be stricter
+            embedding_k_exp=4.0,
+            n_query_variations=12
+        )
+        
+        await test_configuration(
+            "OpenAI Embeddings",
+            config_openai,
+            test_url,
+            "event-driven architecture patterns"
+        )
+    
+    # Parameter Guide
+    print("\n" + "="*60)
+    print("PARAMETER TUNING GUIDE")
+    print("="*60)
+    
+    print("\n📊 Key Parameters and Their Effects:")
+    print("\n1. embedding_k_exp (default: 3.0)")
+    print("   - Lower (1-2): More lenient, faster convergence")
+    print("   - Higher (4-5): Stricter, better precision")
+    
+    print("\n2. embedding_coverage_radius (default: 0.2)")
+    print("   - Lower (0.1-0.15): Requires closer matches")
+    print("   - Higher (0.25-0.3): Accepts broader matches")
+    
+    print("\n3. n_query_variations (default: 10)")
+    print("   - Lower (5-7): Faster, less comprehensive")
+    print("   - Higher (15-20): Better coverage, slower")
+    
+    print("\n4. embedding_min_confidence_threshold (default: 0.1)")
+    print("   - Set to 0.15-0.2 for aggressive irrelevance detection")
+    print("   - Set to 0.05 to crawl even barely relevant content")
+    
+    print("\n5. embedding_validation_min_score (default: 0.3)")
+    print("   - Higher (0.5-0.6): Requires strong validation")
+    print("   - Lower (0.2): More permissive stopping")
+    
+    print("\n💡 Tips:")
+    print("- For research: High k_exp, more variations, strict validation")
+    print("- For exploration: Low k_exp, fewer variations, relaxed thresholds")
+    print("- For quality: Focus on overlap_threshold and validation scores")
+    print("- For speed: Reduce variations, increase min_relative_improvement")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

docs/examples/adaptive_crawling/embedding_strategy.py

@@ -0,0 +1,109 @@
+"""
+Embedding Strategy Example for Adaptive Crawling
+
+This example demonstrates how to use the embedding-based strategy
+for semantic understanding and intelligent crawling.
+"""
+
+import asyncio
+import os
+from crawl4ai import AsyncWebCrawler, AdaptiveCrawler, AdaptiveConfig
+
+
+async def main():
+    """Demonstrate embedding strategy for adaptive crawling"""
+    
+    # Configure embedding strategy
+    config = AdaptiveConfig(
+        strategy="embedding",  # Use embedding strategy
+        embedding_model="sentence-transformers/all-MiniLM-L6-v2",  # Default model
+        n_query_variations=10,  # Generate 10 semantic variations
+        max_pages=15,
+        top_k_links=3,
+        min_gain_threshold=0.05,
+        
+        # Embedding-specific parameters
+        embedding_k_exp=3.0,  # Higher = stricter similarity requirements
+        embedding_min_confidence_threshold=0.1,  # Stop if <10% relevant
+        embedding_validation_min_score=0.4  # Validation threshold
+    )
+    
+    # Optional: Use OpenAI embeddings instead
+    if os.getenv('OPENAI_API_KEY'):
+        config.embedding_llm_config = {
+            'provider': 'openai/text-embedding-3-small',
+            'api_token': os.getenv('OPENAI_API_KEY')
+        }
+        print("Using OpenAI embeddings")
+    else:
+        print("Using sentence-transformers (local embeddings)")
+    
+    async with AsyncWebCrawler(verbose=True) as crawler:
+        adaptive = AdaptiveCrawler(crawler, config)
+        
+        # Test 1: Relevant query with semantic understanding
+        print("\n" + "="*50)
+        print("TEST 1: Semantic Query Understanding")
+        print("="*50)
+        
+        result = await adaptive.digest(
+            start_url="https://docs.python.org/3/library/asyncio.html",
+            query="concurrent programming event-driven architecture"
+        )
+        
+        print("\nQuery Expansion:")
+        print(f"Original query expanded to {len(result.expanded_queries)} variations")
+        for i, q in enumerate(result.expanded_queries[:3], 1):
+            print(f"  {i}. {q}")
+        print("  ...")
+        
+        print("\nResults:")
+        adaptive.print_stats(detailed=False)
+        
+        # Test 2: Detecting irrelevant queries
+        print("\n" + "="*50)
+        print("TEST 2: Irrelevant Query Detection")
+        print("="*50)
+        
+        # Reset crawler for new query
+        adaptive = AdaptiveCrawler(crawler, config)
+        
+        result = await adaptive.digest(
+            start_url="https://docs.python.org/3/library/asyncio.html",
+            query="how to bake chocolate chip cookies"
+        )
+        
+        if result.metrics.get('is_irrelevant', False):
+            print("\n✅ Successfully detected irrelevant query!")
+            print(f"Stopped after just {len(result.crawled_urls)} pages")
+            print(f"Reason: {result.metrics.get('stopped_reason', 'unknown')}")
+        else:
+            print("\n❌ Failed to detect irrelevance")
+        
+        print(f"Final confidence: {adaptive.confidence:.1%}")
+        
+        # Test 3: Semantic gap analysis
+        print("\n" + "="*50)
+        print("TEST 3: Semantic Gap Analysis")
+        print("="*50)
+        
+        # Show how embedding strategy identifies gaps
+        adaptive = AdaptiveCrawler(crawler, config)
+        
+        result = await adaptive.digest(
+            start_url="https://realpython.com",
+            query="python decorators advanced patterns"
+        )
+        
+        print(f"\nSemantic gaps identified: {len(result.semantic_gaps)}")
+        print(f"Knowledge base embeddings shape: {result.kb_embeddings.shape if result.kb_embeddings is not None else 'None'}")
+        
+        # Show coverage metrics specific to embedding strategy
+        print("\nEmbedding-specific metrics:")
+        print(f"  Average best similarity: {result.metrics.get('avg_best_similarity', 0):.3f}")
+        print(f"  Coverage score: {result.metrics.get('coverage_score', 0):.3f}")
+        print(f"  Validation confidence: {result.metrics.get('validation_confidence', 0):.2%}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

docs/examples/adaptive_crawling/embedding_vs_statistical.py

@@ -0,0 +1,167 @@
+"""
+Comparison: Embedding vs Statistical Strategy
+
+This example demonstrates the differences between statistical and embedding
+strategies for adaptive crawling, showing when to use each approach.
+"""
+
+import asyncio
+import time
+import os
+from crawl4ai import AsyncWebCrawler, AdaptiveCrawler, AdaptiveConfig
+
+
+async def crawl_with_strategy(url: str, query: str, strategy: str, **kwargs):
+    """Helper function to crawl with a specific strategy"""
+    config = AdaptiveConfig(
+        strategy=strategy,
+        max_pages=20,
+        top_k_links=3,
+        min_gain_threshold=0.05,
+        **kwargs
+    )
+    
+    async with AsyncWebCrawler(verbose=False) as crawler:
+        adaptive = AdaptiveCrawler(crawler, config)
+        
+        start_time = time.time()
+        result = await adaptive.digest(start_url=url, query=query)
+        elapsed = time.time() - start_time
+        
+        return {
+            'result': result,
+            'crawler': adaptive,
+            'elapsed': elapsed,
+            'pages': len(result.crawled_urls),
+            'confidence': adaptive.confidence
+        }
+
+
+async def main():
+    """Compare embedding and statistical strategies"""
+    
+    # Test scenarios
+    test_cases = [
+        {
+            'name': 'Technical Documentation (Specific Terms)',
+            'url': 'https://docs.python.org/3/library/asyncio.html',
+            'query': 'asyncio.create_task event_loop.run_until_complete'
+        },
+        {
+            'name': 'Conceptual Query (Semantic Understanding)',
+            'url': 'https://docs.python.org/3/library/asyncio.html',
+            'query': 'concurrent programming patterns'
+        },
+        {
+            'name': 'Ambiguous Query',
+            'url': 'https://realpython.com',
+            'query': 'python performance optimization'
+        }
+    ]
+    
+    # Configure embedding strategy
+    embedding_config = {}
+    if os.getenv('OPENAI_API_KEY'):
+        embedding_config['embedding_llm_config'] = {
+            'provider': 'openai/text-embedding-3-small',
+            'api_token': os.getenv('OPENAI_API_KEY')
+        }
+    
+    for test in test_cases:
+        print("\n" + "="*70)
+        print(f"TEST: {test['name']}")
+        print(f"URL: {test['url']}")
+        print(f"Query: '{test['query']}'")
+        print("="*70)
+        
+        # Run statistical strategy
+        print("\n📊 Statistical Strategy:")
+        stat_result = await crawl_with_strategy(
+            test['url'], 
+            test['query'], 
+            'statistical'
+        )
+        
+        print(f"  Pages crawled: {stat_result['pages']}")
+        print(f"  Time taken: {stat_result['elapsed']:.2f}s")
+        print(f"  Confidence: {stat_result['confidence']:.1%}")
+        print(f"  Sufficient: {'Yes' if stat_result['crawler'].is_sufficient else 'No'}")
+        
+        # Show term coverage
+        if hasattr(stat_result['result'], 'term_frequencies'):
+            query_terms = test['query'].lower().split()
+            covered = sum(1 for term in query_terms 
+                         if term in stat_result['result'].term_frequencies)
+            print(f"  Term coverage: {covered}/{len(query_terms)} query terms found")
+        
+        # Run embedding strategy
+        print("\n🧠 Embedding Strategy:")
+        emb_result = await crawl_with_strategy(
+            test['url'], 
+            test['query'], 
+            'embedding',
+            **embedding_config
+        )
+        
+        print(f"  Pages crawled: {emb_result['pages']}")
+        print(f"  Time taken: {emb_result['elapsed']:.2f}s")
+        print(f"  Confidence: {emb_result['confidence']:.1%}")
+        print(f"  Sufficient: {'Yes' if emb_result['crawler'].is_sufficient else 'No'}")
+        
+        # Show semantic understanding
+        if emb_result['result'].expanded_queries:
+            print(f"  Query variations: {len(emb_result['result'].expanded_queries)}")
+            print(f"  Semantic gaps: {len(emb_result['result'].semantic_gaps)}")
+        
+        # Compare results
+        print("\n📈 Comparison:")
+        efficiency_diff = ((stat_result['pages'] - emb_result['pages']) / 
+                          stat_result['pages'] * 100) if stat_result['pages'] > 0 else 0
+        
+        print(f"  Efficiency: ", end="")
+        if efficiency_diff > 0:
+            print(f"Embedding used {efficiency_diff:.0f}% fewer pages")
+        else:
+            print(f"Statistical used {-efficiency_diff:.0f}% fewer pages")
+        
+        print(f"  Speed: ", end="")
+        if stat_result['elapsed'] < emb_result['elapsed']:
+            print(f"Statistical was {emb_result['elapsed']/stat_result['elapsed']:.1f}x faster")
+        else:
+            print(f"Embedding was {stat_result['elapsed']/emb_result['elapsed']:.1f}x faster")
+        
+        print(f"  Confidence difference: {abs(stat_result['confidence'] - emb_result['confidence'])*100:.0f} percentage points")
+        
+        # Recommendation
+        print("\n💡 Recommendation:")
+        if 'specific' in test['name'].lower() or all(len(term) > 5 for term in test['query'].split()):
+            print("  → Statistical strategy is likely better for this use case (specific terms)")
+        elif 'conceptual' in test['name'].lower() or 'semantic' in test['name'].lower():
+            print("  → Embedding strategy is likely better for this use case (semantic understanding)")
+        else:
+            if emb_result['confidence'] > stat_result['confidence'] + 0.1:
+                print("  → Embedding strategy achieved significantly better understanding")
+            elif stat_result['elapsed'] < emb_result['elapsed'] / 2:
+                print("  → Statistical strategy is much faster with similar results")
+            else:
+                print("  → Both strategies performed similarly; choose based on your priorities")
+    
+    # Summary recommendations
+    print("\n" + "="*70)
+    print("STRATEGY SELECTION GUIDE")
+    print("="*70)
+    print("\n✅ Use STATISTICAL strategy when:")
+    print("  - Queries contain specific technical terms")
+    print("  - Speed is critical")
+    print("  - No API access available")
+    print("  - Working with well-structured documentation")
+    
+    print("\n✅ Use EMBEDDING strategy when:")
+    print("  - Queries are conceptual or ambiguous")
+    print("  - Semantic understanding is important")
+    print("  - Need to detect irrelevant content")
+    print("  - Working with diverse content sources")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

docs/examples/adaptive_crawling/export_import_kb.py

@@ -0,0 +1,232 @@
+"""
+Knowledge Base Export and Import
+
+This example demonstrates how to export crawled knowledge bases and
+import them for reuse, sharing, or analysis.
+"""
+
+import asyncio
+import json
+from pathlib import Path
+from crawl4ai import AsyncWebCrawler, AdaptiveCrawler, AdaptiveConfig
+
+
+async def build_knowledge_base():
+    """Build a knowledge base about web technologies"""
+    print("="*60)
+    print("PHASE 1: Building Knowledge Base")
+    print("="*60)
+    
+    async with AsyncWebCrawler(verbose=False) as crawler:
+        adaptive = AdaptiveCrawler(crawler)
+        
+        # Crawl information about HTTP
+        print("\n1. Gathering HTTP protocol information...")
+        await adaptive.digest(
+            start_url="https://httpbin.org",
+            query="http methods headers status codes"
+        )
+        print(f"   - Pages crawled: {len(adaptive.state.crawled_urls)}")
+        print(f"   - Confidence: {adaptive.confidence:.2%}")
+        
+        # Add more information about APIs
+        print("\n2. Adding API documentation knowledge...")
+        await adaptive.digest(
+            start_url="https://httpbin.org/anything",
+            query="rest api json response request"
+        )
+        print(f"   - Total pages: {len(adaptive.state.crawled_urls)}")
+        print(f"   - Confidence: {adaptive.confidence:.2%}")
+        
+        # Export the knowledge base
+        export_path = "web_tech_knowledge.jsonl"
+        print(f"\n3. Exporting knowledge base to {export_path}")
+        adaptive.export_knowledge_base(export_path)
+        
+        # Show export statistics
+        export_size = Path(export_path).stat().st_size / 1024
+        with open(export_path, 'r') as f:
+            line_count = sum(1 for _ in f)
+        
+        print(f"   - Exported {line_count} documents")
+        print(f"   - File size: {export_size:.1f} KB")
+        
+        return export_path
+
+
+async def analyze_knowledge_base(kb_path):
+    """Analyze the exported knowledge base"""
+    print("\n" + "="*60)
+    print("PHASE 2: Analyzing Exported Knowledge Base")
+    print("="*60)
+    
+    # Read and analyze JSONL
+    documents = []
+    with open(kb_path, 'r') as f:
+        for line in f:
+            documents.append(json.loads(line))
+    
+    print(f"\nKnowledge base contains {len(documents)} documents:")
+    
+    # Analyze document properties
+    total_content_length = 0
+    urls_by_domain = {}
+    
+    for doc in documents:
+        # Content analysis
+        content_length = len(doc.get('content', ''))
+        total_content_length += content_length
+        
+        # URL analysis
+        url = doc.get('url', '')
+        domain = url.split('/')[2] if url.startswith('http') else 'unknown'
+        urls_by_domain[domain] = urls_by_domain.get(domain, 0) + 1
+        
+        # Show sample document
+        if documents.index(doc) == 0:
+            print(f"\nSample document structure:")
+            print(f"  - URL: {url}")
+            print(f"  - Content length: {content_length} chars")
+            print(f"  - Has metadata: {'metadata' in doc}")
+            print(f"  - Has links: {len(doc.get('links', []))} links")
+            print(f"  - Query: {doc.get('query', 'N/A')}")
+    
+    print(f"\nContent statistics:")
+    print(f"  - Total content: {total_content_length:,} characters")
+    print(f"  - Average per document: {total_content_length/len(documents):,.0f} chars")
+    
+    print(f"\nDomain distribution:")
+    for domain, count in urls_by_domain.items():
+        print(f"  - {domain}: {count} pages")
+
+
+async def import_and_continue():
+    """Import a knowledge base and continue crawling"""
+    print("\n" + "="*60)
+    print("PHASE 3: Importing and Extending Knowledge Base")
+    print("="*60)
+    
+    kb_path = "web_tech_knowledge.jsonl"
+    
+    async with AsyncWebCrawler(verbose=False) as crawler:
+        # Create new adaptive crawler
+        adaptive = AdaptiveCrawler(crawler)
+        
+        # Import existing knowledge base
+        print(f"\n1. Importing knowledge base from {kb_path}")
+        adaptive.import_knowledge_base(kb_path)
+        
+        print(f"   - Imported {len(adaptive.state.knowledge_base)} documents")
+        print(f"   - Existing URLs: {len(adaptive.state.crawled_urls)}")
+        
+        # Check current state
+        print("\n2. Checking imported knowledge state:")
+        adaptive.print_stats(detailed=False)
+        
+        # Continue crawling with new query
+        print("\n3. Extending knowledge with new query...")
+        await adaptive.digest(
+            start_url="https://httpbin.org/status/200",
+            query="error handling retry timeout"
+        )
+        
+        print("\n4. Final knowledge base state:")
+        adaptive.print_stats(detailed=False)
+        
+        # Export extended knowledge base
+        extended_path = "web_tech_knowledge_extended.jsonl"
+        adaptive.export_knowledge_base(extended_path)
+        print(f"\n5. Extended knowledge base exported to {extended_path}")
+
+
+async def share_knowledge_bases():
+    """Demonstrate sharing knowledge bases between projects"""
+    print("\n" + "="*60)
+    print("PHASE 4: Sharing Knowledge Between Projects")
+    print("="*60)
+    
+    # Simulate two different projects
+    project_a_kb = "project_a_knowledge.jsonl"
+    project_b_kb = "project_b_knowledge.jsonl"
+    
+    async with AsyncWebCrawler(verbose=False) as crawler:
+        # Project A: Security documentation
+        print("\n1. Project A: Building security knowledge...")
+        crawler_a = AdaptiveCrawler(crawler)
+        await crawler_a.digest(
+            start_url="https://httpbin.org/basic-auth/user/pass",
+            query="authentication security headers"
+        )
+        crawler_a.export_knowledge_base(project_a_kb)
+        print(f"   - Exported {len(crawler_a.state.knowledge_base)} documents")
+        
+        # Project B: API testing
+        print("\n2. Project B: Building testing knowledge...")
+        crawler_b = AdaptiveCrawler(crawler)
+        await crawler_b.digest(
+            start_url="https://httpbin.org/anything",
+            query="testing endpoints mocking"
+        )
+        crawler_b.export_knowledge_base(project_b_kb)
+        print(f"   - Exported {len(crawler_b.state.knowledge_base)} documents")
+        
+        # Merge knowledge bases
+        print("\n3. Merging knowledge bases...")
+        merged_crawler = AdaptiveCrawler(crawler)
+        
+        # Import both knowledge bases
+        merged_crawler.import_knowledge_base(project_a_kb)
+        initial_size = len(merged_crawler.state.knowledge_base)
+        
+        merged_crawler.import_knowledge_base(project_b_kb)
+        final_size = len(merged_crawler.state.knowledge_base)
+        
+        print(f"   - Project A documents: {initial_size}")
+        print(f"   - Additional from Project B: {final_size - initial_size}")
+        print(f"   - Total merged documents: {final_size}")
+        
+        # Export merged knowledge
+        merged_kb = "merged_knowledge.jsonl"
+        merged_crawler.export_knowledge_base(merged_kb)
+        print(f"\n4. Merged knowledge base exported to {merged_kb}")
+        
+        # Show combined coverage
+        print("\n5. Combined knowledge coverage:")
+        merged_crawler.print_stats(detailed=False)
+
+
+async def main():
+    """Run all examples"""
+    try:
+        # Build initial knowledge base
+        kb_path = await build_knowledge_base()
+        
+        # Analyze the export
+        await analyze_knowledge_base(kb_path)
+        
+        # Import and extend
+        await import_and_continue()
+        
+        # Demonstrate sharing
+        await share_knowledge_bases()
+        
+        print("\n" + "="*60)
+        print("All examples completed successfully!")
+        print("="*60)
+        
+    finally:
+        # Clean up generated files
+        print("\nCleaning up generated files...")
+        for file in [
+            "web_tech_knowledge.jsonl",
+            "web_tech_knowledge_extended.jsonl", 
+            "project_a_knowledge.jsonl",
+            "project_b_knowledge.jsonl",
+            "merged_knowledge.jsonl"
+        ]:
+            Path(file).unlink(missing_ok=True)
+        print("Cleanup complete.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

docs/examples/llm_extraction_openai_pricing.py

@@ -1,43 +1,55 @@
-from crawl4ai import LLMConfig
-from crawl4ai import AsyncWebCrawler, LLMExtractionStrategy
 import asyncio
-import os
-import json
 from pydantic import BaseModel, Field
-
-url = "https://openai.com/api/pricing/"
+from crawl4ai import AsyncWebCrawler, CrawlerRunConfig, LLMConfig, BrowserConfig, CacheMode
+from crawl4ai.extraction_strategy import LLMExtractionStrategy
+from typing import Dict
+import os
 
 
 class OpenAIModelFee(BaseModel):
     model_name: str = Field(..., description="Name of the OpenAI model.")
     input_fee: str = Field(..., description="Fee for input token for the OpenAI model.")
-    output_fee: str = Field(
-        ..., description="Fee for output token for the OpenAI model."
+    output_fee: str = Field(..., description="Fee for output token for the OpenAI model.")
+
+
+async def extract_structured_data_using_llm(provider: str, api_token: str = None, extra_headers: Dict[str, str] = None):
+    print(f"\n--- Extracting Structured Data with {provider} ---")
+
+    if api_token is None and provider != "ollama":
+        print(f"API token is required for {provider}. Skipping this example.")
+        return
+
+    browser_config = BrowserConfig(headless=True)
+
+    extra_args = {"temperature": 0, "top_p": 0.9, "max_tokens": 2000}
+    if extra_headers:
+        extra_args["extra_headers"] = extra_headers
+
+    crawler_config = CrawlerRunConfig(
+        cache_mode=CacheMode.BYPASS,
+        word_count_threshold=1,
+        page_timeout=80000,
+        extraction_strategy=LLMExtractionStrategy(
+            llm_config=LLMConfig(provider=provider, api_token=api_token),
+            schema=OpenAIModelFee.model_json_schema(),
+            extraction_type="schema",
+            instruction="""From the crawled content, extract all mentioned model names along with their fees for input and output tokens. 
+            Do not miss any models in the entire content.""",
+            extra_args=extra_args,
+        ),
     )
 
-async def main():
-    # Use AsyncWebCrawler
-    async with AsyncWebCrawler() as crawler:
+    async with AsyncWebCrawler(config=browser_config) as crawler:
         result = await crawler.arun(
-            url=url,
-            word_count_threshold=1,
-            extraction_strategy=LLMExtractionStrategy(
-                # provider= "openai/gpt-4o", api_token = os.getenv('OPENAI_API_KEY'),
-                llm_config=LLMConfig(provider="groq/llama-3.1-70b-versatile", api_token=os.getenv("GROQ_API_KEY")),
-                schema=OpenAIModelFee.model_json_schema(),
-                extraction_type="schema",
-                instruction="From the crawled content, extract all mentioned model names along with their "
-                "fees for input and output tokens. Make sure not to miss anything in the entire content. "
-                "One extracted model JSON format should look like this: "
-                '{ "model_name": "GPT-4", "input_fee": "US$10.00 / 1M tokens", "output_fee": "US$30.00 / 1M tokens" }',
-            ),
+            url="https://openai.com/api/pricing/", 
+            config=crawler_config
         )
-        print("Success:", result.success)
-        model_fees = json.loads(result.extracted_content)
-        print(len(model_fees))
-
-        with open(".data/data.json", "w", encoding="utf-8") as f:
-            f.write(result.extracted_content)
+        print(result.extracted_content)
 
 
-asyncio.run(main())
+if __name__ == "__main__":
+    asyncio.run(
+        extract_structured_data_using_llm(
+            provider="openai/gpt-4o", api_token=os.getenv("OPENAI_API_KEY")
+        )
+    )

docs/md_v2/advanced/adaptive-strategies.md

@@ -0,0 +1,432 @@
+# Advanced Adaptive Strategies
+
+## Overview
+
+While the default adaptive crawling configuration works well for most use cases, understanding the underlying strategies and scoring mechanisms allows you to fine-tune the crawler for specific domains and requirements.
+
+## The Three-Layer Scoring System
+
+### 1. Coverage Score
+
+Coverage measures how comprehensively your knowledge base covers the query terms and related concepts.
+
+#### Mathematical Foundation
+
+```python
+Coverage(K, Q) = Σ(t ∈ Q) score(t, K) / |Q|
+
+where score(t, K) = doc_coverage(t) × (1 + freq_boost(t))
+```
+
+#### Components
+
+- **Document Coverage**: Percentage of documents containing the term
+- **Frequency Boost**: Logarithmic bonus for term frequency
+- **Query Decomposition**: Handles multi-word queries intelligently
+
+#### Tuning Coverage
+
+```python
+# For technical documentation with specific terminology
+config = AdaptiveConfig(
+    confidence_threshold=0.85,  # Require high coverage
+    top_k_links=5              # Cast wider net
+)
+
+# For general topics with synonyms
+config = AdaptiveConfig(
+    confidence_threshold=0.6,   # Lower threshold
+    top_k_links=2              # More focused
+)
+```
+
+### 2. Consistency Score
+
+Consistency evaluates whether the information across pages is coherent and non-contradictory.
+
+#### How It Works
+
+1. Extracts key statements from each document
+2. Compares statements across documents
+3. Measures agreement vs. contradiction
+4. Returns normalized score (0-1)
+
+#### Practical Impact
+
+- **High consistency (>0.8)**: Information is reliable and coherent
+- **Medium consistency (0.5-0.8)**: Some variation, but generally aligned
+- **Low consistency (<0.5)**: Conflicting information, need more sources
+
+### 3. Saturation Score
+
+Saturation detects when new pages stop providing novel information.
+
+#### Detection Algorithm
+
+```python
+# Tracks new unique terms per page
+new_terms_page_1 = 50
+new_terms_page_2 = 30  # 60% of first
+new_terms_page_3 = 15  # 50% of second
+new_terms_page_4 = 5   # 33% of third
+# Saturation detected: rapidly diminishing returns
+```
+
+#### Configuration
+
+```python
+config = AdaptiveConfig(
+    min_gain_threshold=0.1  # Stop if <10% new information
+)
+```
+
+## Link Ranking Algorithm
+
+### Expected Information Gain
+
+Each uncrawled link is scored based on:
+
+```python
+ExpectedGain(link) = Relevance × Novelty × Authority
+```
+
+#### 1. Relevance Scoring
+
+Uses BM25 algorithm on link preview text:
+
+```python
+relevance = BM25(link.preview_text, query)
+```
+
+Factors:
+- Term frequency in preview
+- Inverse document frequency
+- Preview length normalization
+
+#### 2. Novelty Estimation
+
+Measures how different the link appears from already-crawled content:
+
+```python
+novelty = 1 - max_similarity(preview, knowledge_base)
+```
+
+Prevents crawling duplicate or highly similar pages.
+
+#### 3. Authority Calculation
+
+URL structure and domain analysis:
+
+```python
+authority = f(domain_rank, url_depth, url_structure)
+```
+
+Factors:
+- Domain reputation
+- URL depth (fewer slashes = higher authority)
+- Clean URL structure
+
+### Custom Link Scoring
+
+```python
+class CustomLinkScorer:
+    def score(self, link: Link, query: str, state: CrawlState) -> float:
+        # Prioritize specific URL patterns
+        if "/api/reference/" in link.href:
+            return 2.0  # Double the score
+        
+        # Deprioritize certain sections
+        if "/archive/" in link.href:
+            return 0.1  # Reduce score by 90%
+        
+        # Default scoring
+        return 1.0
+
+# Use with adaptive crawler
+adaptive = AdaptiveCrawler(
+    crawler,
+    config=config,
+    link_scorer=CustomLinkScorer()
+)
+```
+
+## Domain-Specific Configurations
+
+### Technical Documentation
+
+```python
+tech_doc_config = AdaptiveConfig(
+    confidence_threshold=0.85,
+    max_pages=30,
+    top_k_links=3,
+    min_gain_threshold=0.05  # Keep crawling for small gains
+)
+```
+
+Rationale:
+- High threshold ensures comprehensive coverage
+- Lower gain threshold captures edge cases
+- Moderate link following for depth
+
+### News & Articles
+
+```python
+news_config = AdaptiveConfig(
+    confidence_threshold=0.6,
+    max_pages=10,
+    top_k_links=5,
+    min_gain_threshold=0.15  # Stop quickly on repetition
+)
+```
+
+Rationale:
+- Lower threshold (articles often repeat information)
+- Higher gain threshold (avoid duplicate stories)
+- More links per page (explore different perspectives)
+
+### E-commerce
+
+```python
+ecommerce_config = AdaptiveConfig(
+    confidence_threshold=0.7,
+    max_pages=20,
+    top_k_links=2,
+    min_gain_threshold=0.1
+)
+```
+
+Rationale:
+- Balanced threshold for product variations
+- Focused link following (avoid infinite products)
+- Standard gain threshold
+
+### Research & Academic
+
+```python
+research_config = AdaptiveConfig(
+    confidence_threshold=0.9,
+    max_pages=50,
+    top_k_links=4,
+    min_gain_threshold=0.02  # Very low - capture citations
+)
+```
+
+Rationale:
+- Very high threshold for completeness
+- Many pages allowed for thorough research
+- Very low gain threshold to capture references
+
+## Performance Optimization
+
+### Memory Management
+
+```python
+# For large crawls, use streaming
+config = AdaptiveConfig(
+    max_pages=100,
+    save_state=True,
+    state_path="large_crawl.json"
+)
+
+# Periodically clean state
+if len(state.knowledge_base) > 1000:
+    # Keep only most relevant
+    state.knowledge_base = get_top_relevant(state.knowledge_base, 500)
+```
+
+### Parallel Processing
+
+```python
+# Use multiple start points
+start_urls = [
+    "https://docs.example.com/intro",
+    "https://docs.example.com/api",
+    "https://docs.example.com/guides"
+]
+
+# Crawl in parallel
+tasks = [
+    adaptive.digest(url, query)
+    for url in start_urls
+]
+results = await asyncio.gather(*tasks)
+```
+
+### Caching Strategy
+
+```python
+# Enable caching for repeated crawls
+async with AsyncWebCrawler(
+    config=BrowserConfig(
+        cache_mode=CacheMode.ENABLED
+    )
+) as crawler:
+    adaptive = AdaptiveCrawler(crawler, config)
+```
+
+## Debugging & Analysis
+
+### Enable Verbose Logging
+
+```python
+import logging
+
+logging.basicConfig(level=logging.DEBUG)
+adaptive = AdaptiveCrawler(crawler, config, verbose=True)
+```
+
+### Analyze Crawl Patterns
+
+```python
+# After crawling
+state = await adaptive.digest(start_url, query)
+
+# Analyze link selection
+print("Link selection order:")
+for i, url in enumerate(state.crawl_order):
+    print(f"{i+1}. {url}")
+
+# Analyze term discovery
+print("\nTerm discovery rate:")
+for i, new_terms in enumerate(state.new_terms_history):
+    print(f"Page {i+1}: {new_terms} new terms")
+
+# Analyze score progression
+print("\nScore progression:")
+print(f"Coverage: {state.metrics['coverage_history']}")
+print(f"Saturation: {state.metrics['saturation_history']}")
+```
+
+### Export for Analysis
+
+```python
+# Export detailed metrics
+import json
+
+metrics = {
+    "query": query,
+    "total_pages": len(state.crawled_urls),
+    "confidence": adaptive.confidence,
+    "coverage_stats": adaptive.coverage_stats,
+    "crawl_order": state.crawl_order,
+    "term_frequencies": dict(state.term_frequencies),
+    "new_terms_history": state.new_terms_history
+}
+
+with open("crawl_analysis.json", "w") as f:
+    json.dump(metrics, f, indent=2)
+```
+
+## Custom Strategies
+
+### Implementing a Custom Strategy
+
+```python
+from crawl4ai.adaptive_crawler import BaseStrategy
+
+class DomainSpecificStrategy(BaseStrategy):
+    def calculate_coverage(self, state: CrawlState) -> float:
+        # Custom coverage calculation
+        # e.g., weight certain terms more heavily
+        pass
+    
+    def calculate_consistency(self, state: CrawlState) -> float:
+        # Custom consistency logic
+        # e.g., domain-specific validation
+        pass
+    
+    def rank_links(self, links: List[Link], state: CrawlState) -> List[Link]:
+        # Custom link ranking
+        # e.g., prioritize specific URL patterns
+        pass
+
+# Use custom strategy
+adaptive = AdaptiveCrawler(
+    crawler,
+    config=config,
+    strategy=DomainSpecificStrategy()
+)
+```
+
+### Combining Strategies
+
+```python
+class HybridStrategy(BaseStrategy):
+    def __init__(self):
+        self.strategies = [
+            TechnicalDocStrategy(),
+            SemanticSimilarityStrategy(),
+            URLPatternStrategy()
+        ]
+    
+    def calculate_confidence(self, state: CrawlState) -> float:
+        # Weighted combination of strategies
+        scores = [s.calculate_confidence(state) for s in self.strategies]
+        weights = [0.5, 0.3, 0.2]
+        return sum(s * w for s, w in zip(scores, weights))
+```
+
+## Best Practices
+
+### 1. Start Conservative
+
+Begin with default settings and adjust based on results:
+
+```python
+# Start with defaults
+result = await adaptive.digest(url, query)
+
+# Analyze and adjust
+if adaptive.confidence < 0.7:
+    config.max_pages += 10
+    config.confidence_threshold -= 0.1
+```
+
+### 2. Monitor Resource Usage
+
+```python
+import psutil
+
+# Check memory before large crawls
+memory_percent = psutil.virtual_memory().percent
+if memory_percent > 80:
+    config.max_pages = min(config.max_pages, 20)
+```
+
+### 3. Use Domain Knowledge
+
+```python
+# For API documentation
+if "api" in start_url:
+    config.top_k_links = 2  # APIs have clear structure
+    
+# For blogs
+if "blog" in start_url:
+    config.min_gain_threshold = 0.2  # Avoid similar posts
+```
+
+### 4. Validate Results
+
+```python
+# Always validate the knowledge base
+relevant_content = adaptive.get_relevant_content(top_k=10)
+
+# Check coverage
+query_terms = set(query.lower().split())
+covered_terms = set()
+
+for doc in relevant_content:
+    content_lower = doc['content'].lower()
+    for term in query_terms:
+        if term in content_lower:
+            covered_terms.add(term)
+
+coverage_ratio = len(covered_terms) / len(query_terms)
+print(f"Query term coverage: {coverage_ratio:.0%}")
+```
+
+## Next Steps
+
+- Explore [Custom Strategy Implementation](../tutorials/custom-adaptive-strategies.md)
+- Learn about [Knowledge Base Management](../tutorials/knowledge-base-management.md)
+- See [Performance Benchmarks](../benchmarks/adaptive-performance.md)

docs/md_v2/advanced/advanced-features.md

@@ -66,29 +66,38 @@ Sometimes you need a visual record of a page or a PDF “printout.” Crawl4AI c
 ```python
 import os, asyncio
 from base64 import b64decode
-from crawl4ai import AsyncWebCrawler, CacheMode
+from crawl4ai import AsyncWebCrawler, CacheMode, CrawlerRunConfig
 
 async def main():
+    run_config = CrawlerRunConfig(
+        cache_mode=CacheMode.BYPASS,
+        screenshot=True,
+        pdf=True
+    )
+
     async with AsyncWebCrawler() as crawler:
         result = await crawler.arun(
             url="https://en.wikipedia.org/wiki/List_of_common_misconceptions",
-            cache_mode=CacheMode.BYPASS,
-            pdf=True,
-            screenshot=True
+            config=run_config
         )
-        
         if result.success:
-            # Save screenshot
+            print(f"Screenshot data present: {result.screenshot is not None}")
+            print(f"PDF data present: {result.pdf is not None}")
+
             if result.screenshot:
+                print(f"[OK] Screenshot captured, size: {len(result.screenshot)} bytes")
                 with open("wikipedia_screenshot.png", "wb") as f:
                     f.write(b64decode(result.screenshot))
-            
-            # Save PDF
+            else:
+                print("[WARN] Screenshot data is None.")
+
             if result.pdf:
+                print(f"[OK] PDF captured, size: {len(result.pdf)} bytes")
                 with open("wikipedia_page.pdf", "wb") as f:
                     f.write(result.pdf)
-            
-            print("[OK] PDF & screenshot captured.")
+            else:
+                print("[WARN] PDF data is None.")
+
         else:
             print("[ERROR]", result.error_message)
 

docs/md_v2/advanced/pdf-parsing.md

@@ -0,0 +1,201 @@
+# PDF Processing Strategies
+
+Crawl4AI provides specialized strategies for handling and extracting content from PDF files. These strategies allow you to seamlessly integrate PDF processing into your crawling workflows, whether the PDFs are hosted online or stored locally.
+
+## `PDFCrawlerStrategy`
+
+### Overview
+`PDFCrawlerStrategy` is an implementation of `AsyncCrawlerStrategy` designed specifically for PDF documents. Instead of interpreting the input URL as an HTML webpage, this strategy treats it as a pointer to a PDF file. It doesn't perform deep crawling or HTML parsing itself but rather prepares the PDF source for a dedicated PDF scraping strategy. Its primary role is to identify the PDF source (web URL or local file) and pass it along the processing pipeline in a way that `AsyncWebCrawler` can handle.
+
+### When to Use
+Use `PDFCrawlerStrategy` when you need to:
+- Process PDF files using the `AsyncWebCrawler`.
+- Handle PDFs from both web URLs (e.g., `https://example.com/document.pdf`) and local file paths (e.g., `file:///path/to/your/document.pdf`).
+- Integrate PDF content extraction into a unified `CrawlResult` object, allowing consistent handling of PDF data alongside web page data.
+
+### Key Methods and Their Behavior
+-   **`__init__(self, logger: AsyncLogger = None)`**:
+    -   Initializes the strategy.
+    -   `logger`: An optional `AsyncLogger` instance (from `crawl4ai.async_logger`) for logging purposes.
+-   **`async crawl(self, url: str, **kwargs) -> AsyncCrawlResponse`**:
+    -   This method is called by the `AsyncWebCrawler` during the `arun` process.
+    -   It takes the `url` (which should point to a PDF) and creates a minimal `AsyncCrawlResponse`.
+    -   The `html` attribute of this response is typically empty or a placeholder, as the actual PDF content processing is deferred to the `PDFContentScrapingStrategy` (or a similar PDF-aware scraping strategy).
+    -   It sets `response_headers` to indicate "application/pdf" and `status_code` to 200.
+-   **`async close(self)`**:
+    -   A method for cleaning up any resources used by the strategy. For `PDFCrawlerStrategy`, this is usually minimal.
+-   **`async __aenter__(self)` / `async __aexit__(self, exc_type, exc_val, exc_tb)`**:
+    -   Enables asynchronous context management for the strategy, allowing it to be used with `async with`.
+
+### Example Usage
+```python
+import asyncio
+from crawl4ai import AsyncWebCrawler, CrawlerRunConfig
+from crawl4ai.processors.pdf import PDFCrawlerStrategy, PDFContentScrapingStrategy
+
+async def main():
+    # Initialize the PDF crawler strategy
+    pdf_crawler_strategy = PDFCrawlerStrategy()
+
+    # PDFCrawlerStrategy is typically used in conjunction with PDFContentScrapingStrategy
+    # The scraping strategy handles the actual PDF content extraction
+    pdf_scraping_strategy = PDFContentScrapingStrategy()
+    run_config = CrawlerRunConfig(scraping_strategy=pdf_scraping_strategy)
+
+    async with AsyncWebCrawler(crawler_strategy=pdf_crawler_strategy) as crawler:
+        # Example with a remote PDF URL
+        pdf_url = "https://arxiv.org/pdf/2310.06825.pdf" # A public PDF from arXiv
+        
+        print(f"Attempting to process PDF: {pdf_url}")
+        result = await crawler.arun(url=pdf_url, config=run_config)
+
+        if result.success:
+            print(f"Successfully processed PDF: {result.url}")
+            print(f"Metadata Title: {result.metadata.get('title', 'N/A')}")
+            # Further processing of result.markdown, result.media, etc.
+            # would be done here, based on what PDFContentScrapingStrategy extracts.
+            if result.markdown and hasattr(result.markdown, 'raw_markdown'):
+                print(f"Extracted text (first 200 chars): {result.markdown.raw_markdown[:200]}...")
+            else:
+                print("No markdown (text) content extracted.")
+        else:
+            print(f"Failed to process PDF: {result.error_message}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Pros and Cons
+**Pros:**
+-   Enables `AsyncWebCrawler` to handle PDF sources directly using familiar `arun` calls.
+-   Provides a consistent interface for specifying PDF sources (URLs or local paths).
+-   Abstracts the source handling, allowing a separate scraping strategy to focus on PDF content parsing.
+
+**Cons:**
+-   Does not perform any PDF data extraction itself; it strictly relies on a compatible scraping strategy (like `PDFContentScrapingStrategy`) to process the PDF.
+-   Has limited utility on its own; most of its value comes from being paired with a PDF-specific content scraping strategy.
+
+---
+
+## `PDFContentScrapingStrategy`
+
+### Overview
+`PDFContentScrapingStrategy` is an implementation of `ContentScrapingStrategy` designed to extract text, metadata, and optionally images from PDF documents. It is intended to be used in conjunction with a crawler strategy that can provide it with a PDF source, such as `PDFCrawlerStrategy`. This strategy uses the `NaivePDFProcessorStrategy` internally to perform the low-level PDF parsing.
+
+### When to Use
+Use `PDFContentScrapingStrategy` when your `AsyncWebCrawler` (often configured with `PDFCrawlerStrategy`) needs to:
+-   Extract textual content page by page from a PDF document.
+-   Retrieve standard metadata embedded within the PDF (e.g., title, author, subject, creation date, page count).
+-   Optionally, extract images contained within the PDF pages. These images can be saved to a local directory or made available for further processing.
+-   Produce a `ScrapingResult` that can be converted into a `CrawlResult`, making PDF content accessible in a manner similar to HTML web content (e.g., text in `result.markdown`, metadata in `result.metadata`).
+
+### Key Configuration Attributes
+When initializing `PDFContentScrapingStrategy`, you can configure its behavior using the following attributes:
+-   **`extract_images: bool = False`**: If `True`, the strategy will attempt to extract images from the PDF.
+-   **`save_images_locally: bool = False`**: If `True` (and `extract_images` is also `True`), extracted images will be saved to disk in the `image_save_dir`. If `False`, image data might be available in another form (e.g., base64, depending on the underlying processor) but not saved as separate files by this strategy.
+-   **`image_save_dir: str = None`**: Specifies the directory where extracted images should be saved if `save_images_locally` is `True`. If `None`, a default or temporary directory might be used.
+-   **`batch_size: int = 4`**: Defines how many PDF pages are processed in a single batch. This can be useful for managing memory when dealing with very large PDF documents.
+-   **`logger: AsyncLogger = None`**: An optional `AsyncLogger` instance for logging.
+
+### Key Methods and Their Behavior
+-   **`__init__(self, save_images_locally: bool = False, extract_images: bool = False, image_save_dir: str = None, batch_size: int = 4, logger: AsyncLogger = None)`**:
+    -   Initializes the strategy with configurations for image handling, batch processing, and logging. It sets up an internal `NaivePDFProcessorStrategy` instance which performs the actual PDF parsing.
+-   **`scrap(self, url: str, html: str, **params) -> ScrapingResult`**:
+    -   This is the primary synchronous method called by the crawler (via `ascrap`) to process the PDF.
+    -   `url`: The path or URL to the PDF file (provided by `PDFCrawlerStrategy` or similar).
+    -   `html`: Typically an empty string when used with `PDFCrawlerStrategy`, as the content is a PDF, not HTML.
+    -   It first ensures the PDF is accessible locally (downloads it to a temporary file if `url` is remote).
+    -   It then uses its internal PDF processor to extract text, metadata, and images (if configured).
+    -   The extracted information is compiled into a `ScrapingResult` object:
+        -   `cleaned_html`: Contains an HTML-like representation of the PDF, where each page's content is often wrapped in a `<div>` with page number information.
+        -   `media`: A dictionary where `media["images"]` will contain information about extracted images if `extract_images` was `True`.
+        -   `links`: A dictionary where `links["urls"]` can contain URLs found within the PDF content.
+        -   `metadata`: A dictionary holding PDF metadata (e.g., title, author, num_pages).
+-   **`async ascrap(self, url: str, html: str, **kwargs) -> ScrapingResult`**:
+    -   The asynchronous version of `scrap`. Under the hood, it typically runs the synchronous `scrap` method in a separate thread using `asyncio.to_thread` to avoid blocking the event loop.
+-   **`_get_pdf_path(self, url: str) -> str`**:
+    -   A private helper method to manage PDF file access. If the `url` is remote (http/https), it downloads the PDF to a temporary local file and returns its path. If `url` indicates a local file (`file://` or a direct path), it resolves and returns the local path.
+
+### Example Usage
+```python
+import asyncio
+from crawl4ai import AsyncWebCrawler, CrawlerRunConfig
+from crawl4ai.processors.pdf import PDFCrawlerStrategy, PDFContentScrapingStrategy
+import os # For creating image directory
+
+async def main():
+    # Define the directory for saving extracted images
+    image_output_dir = "./my_pdf_images"
+    os.makedirs(image_output_dir, exist_ok=True)
+
+    # Configure the PDF content scraping strategy
+    # Enable image extraction and specify where to save them
+    pdf_scraping_cfg = PDFContentScrapingStrategy(
+        extract_images=True,
+        save_images_locally=True,
+        image_save_dir=image_output_dir,
+        batch_size=2 # Process 2 pages at a time for demonstration
+    )
+
+    # The PDFCrawlerStrategy is needed to tell AsyncWebCrawler how to "crawl" a PDF
+    pdf_crawler_cfg = PDFCrawlerStrategy()
+
+    # Configure the overall crawl run
+    run_cfg = CrawlerRunConfig(
+        scraping_strategy=pdf_scraping_cfg # Use our PDF scraping strategy
+    )
+
+    # Initialize the crawler with the PDF-specific crawler strategy
+    async with AsyncWebCrawler(crawler_strategy=pdf_crawler_cfg) as crawler:
+        pdf_url = "https://arxiv.org/pdf/2310.06825.pdf" # Example PDF
+        
+        print(f"Starting PDF processing for: {pdf_url}")
+        result = await crawler.arun(url=pdf_url, config=run_cfg)
+
+        if result.success:
+            print("\n--- PDF Processing Successful ---")
+            print(f"Processed URL: {result.url}")
+            
+            print("\n--- Metadata ---")
+            for key, value in result.metadata.items():
+                print(f"  {key.replace('_', ' ').title()}: {value}")
+
+            if result.markdown and hasattr(result.markdown, 'raw_markdown'):
+                print(f"\n--- Extracted Text (Markdown Snippet) ---")
+                print(result.markdown.raw_markdown[:500].strip() + "...")
+            else:
+                print("\nNo text (markdown) content extracted.")
+
+            if result.media and result.media.get("images"):
+                print(f"\n--- Image Extraction ---")
+                print(f"Extracted {len(result.media['images'])} image(s).")
+                for i, img_info in enumerate(result.media["images"][:2]): # Show info for first 2 images
+                    print(f"  Image {i+1}:")
+                    print(f"    Page: {img_info.get('page')}")
+                    print(f"    Format: {img_info.get('format', 'N/A')}")
+                    if img_info.get('path'):
+                        print(f"    Saved at: {img_info.get('path')}")
+            else:
+                print("\nNo images were extracted (or extract_images was False).")
+        else:
+            print(f"\n--- PDF Processing Failed ---")
+            print(f"Error: {result.error_message}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Pros and Cons
+
+**Pros:**
+-   Provides a comprehensive way to extract text, metadata, and (optionally) images from PDF documents.
+-   Handles both remote PDFs (via URL) and local PDF files.
+-   Configurable image extraction allows saving images to disk or accessing their data.
+-   Integrates smoothly with the `CrawlResult` object structure, making PDF-derived data accessible in a way consistent with web-scraped data.
+-   The `batch_size` parameter can help in managing memory consumption when processing large or numerous PDF pages.
+
+**Cons:**
+-   Extraction quality and performance can vary significantly depending on the PDF's complexity, encoding, and whether it's image-based (scanned) or text-based.
+-   Image extraction can be resource-intensive (both CPU and disk space if `save_images_locally` is true).
+-   Relies on `NaivePDFProcessorStrategy` internally, which might have limitations with very complex layouts, encrypted PDFs, or forms compared to more sophisticated PDF parsing libraries. Scanned PDFs will not yield text unless an OCR step is performed (which is not part of this strategy by default).
+-   Link extraction from PDFs can be basic and depends on how hyperlinks are embedded in the document.

docs/md_v2/advanced/proxy-security.md

@@ -25,44 +25,70 @@ Use an authenticated proxy with `BrowserConfig`:
 ```python
 from crawl4ai.async_configs import BrowserConfig
 
-proxy_config = {
-    "server": "http://proxy.example.com:8080",
-    "username": "user",
-    "password": "pass"
-}
-
-browser_config = BrowserConfig(proxy_config=proxy_config)
+browser_config = BrowserConfig(proxy="http://[username]:[password]@[host]:[port]")
 async with AsyncWebCrawler(config=browser_config) as crawler:
     result = await crawler.arun(url="https://example.com")
 ```
 
-Here's the corrected documentation:
 
 ## Rotating Proxies 
 
 Example using a proxy rotation service dynamically:
 
 ```python
-from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig
-
-async def get_next_proxy():
-    # Your proxy rotation logic here
-    return {"server": "http://next.proxy.com:8080"}
-
+import re
+from crawl4ai import (
+    AsyncWebCrawler,
+    BrowserConfig,
+    CrawlerRunConfig,
+    CacheMode,
+    RoundRobinProxyStrategy,
+)
+import asyncio
+from crawl4ai import ProxyConfig
 async def main():
-    browser_config = BrowserConfig()
-    run_config = CrawlerRunConfig()
-    
-    async with AsyncWebCrawler(config=browser_config) as crawler:
-        # For each URL, create a new run config with different proxy
-        for url in urls:
-            proxy = await get_next_proxy()
-            # Clone the config and update proxy - this creates a new browser context
-            current_config = run_config.clone(proxy_config=proxy)
-            result = await crawler.arun(url=url, config=current_config)
+    # Load proxies and create rotation strategy
+    proxies = ProxyConfig.from_env()
+    #eg: export PROXIES="ip1:port1:username1:password1,ip2:port2:username2:password2"
+    if not proxies:
+        print("No proxies found in environment. Set PROXIES env variable!")
+        return
+
+    proxy_strategy = RoundRobinProxyStrategy(proxies)
+
+    # Create configs
+    browser_config = BrowserConfig(headless=True, verbose=False)
+    run_config = CrawlerRunConfig(
+        cache_mode=CacheMode.BYPASS,
+        proxy_rotation_strategy=proxy_strategy
+    )
+
+    async with AsyncWebCrawler(config=browser_config) as crawler:
+        urls = ["https://httpbin.org/ip"] * (len(proxies) * 2)  # Test each proxy twice
+
+        print("\n📈 Initializing crawler with proxy rotation...")
+        async with AsyncWebCrawler(config=browser_config) as crawler:
+            print("\n🚀 Starting batch crawl with proxy rotation...")
+            results = await crawler.arun_many(
+                urls=urls,
+                config=run_config
+            )
+            for result in results:
+                if result.success:
+                    ip_match = re.search(r'(?:[0-9]{1,3}\.){3}[0-9]{1,3}', result.html)
+                    current_proxy = run_config.proxy_config if run_config.proxy_config else None
+
+                    if current_proxy and ip_match:
+                        print(f"URL {result.url}")
+                        print(f"Proxy {current_proxy.server} -> Response IP: {ip_match.group(0)}")
+                        verified = ip_match.group(0) == current_proxy.ip
+                        if verified:
+                            print(f"✅ Proxy working! IP matches: {current_proxy.ip}")
+                        else:
+                            print("❌ Proxy failed or IP mismatch!")
+                    print("---")
+
+asyncio.run(main())
 
-if __name__ == "__main__":
-    import asyncio
-    asyncio.run(main())
 ```
 

docs/md_v2/api/adaptive-crawler.md

@@ -0,0 +1,244 @@
+# AdaptiveCrawler
+
+The `AdaptiveCrawler` class implements intelligent web crawling that automatically determines when sufficient information has been gathered to answer a query. It uses a three-layer scoring system to evaluate coverage, consistency, and saturation.
+
+## Constructor
+
+```python
+AdaptiveCrawler(
+    crawler: AsyncWebCrawler,
+    config: Optional[AdaptiveConfig] = None
+)
+```
+
+### Parameters
+
+- **crawler** (`AsyncWebCrawler`): The underlying web crawler instance to use for fetching pages
+- **config** (`Optional[AdaptiveConfig]`): Configuration settings for adaptive crawling behavior. If not provided, uses default settings.
+
+## Primary Method
+
+### digest()
+
+The main method that performs adaptive crawling starting from a URL with a specific query.
+
+```python
+async def digest(
+    start_url: str,
+    query: str,
+    resume_from: Optional[Union[str, Path]] = None
+) -> CrawlState
+```
+
+#### Parameters
+
+- **start_url** (`str`): The starting URL for crawling
+- **query** (`str`): The search query that guides the crawling process
+- **resume_from** (`Optional[Union[str, Path]]`): Path to a saved state file to resume from
+
+#### Returns
+
+- **CrawlState**: The final crawl state containing all crawled URLs, knowledge base, and metrics
+
+#### Example
+
+```python
+async with AsyncWebCrawler() as crawler:
+    adaptive = AdaptiveCrawler(crawler)
+    state = await adaptive.digest(
+        start_url="https://docs.python.org",
+        query="async context managers"
+    )
+```
+
+## Properties
+
+### confidence
+
+Current confidence score (0-1) indicating information sufficiency.
+
+```python
+@property
+def confidence(self) -> float
+```
+
+### coverage_stats
+
+Dictionary containing detailed coverage statistics.
+
+```python
+@property  
+def coverage_stats(self) -> Dict[str, float]
+```
+
+Returns:
+- **coverage**: Query term coverage score
+- **consistency**: Information consistency score  
+- **saturation**: Content saturation score
+- **confidence**: Overall confidence score
+
+### is_sufficient
+
+Boolean indicating whether sufficient information has been gathered.
+
+```python
+@property
+def is_sufficient(self) -> bool
+```
+
+### state
+
+Access to the current crawl state.
+
+```python
+@property
+def state(self) -> CrawlState
+```
+
+## Methods
+
+### get_relevant_content()
+
+Retrieve the most relevant content from the knowledge base.
+
+```python
+def get_relevant_content(
+    self,
+    top_k: int = 5
+) -> List[Dict[str, Any]]
+```
+
+#### Parameters
+
+- **top_k** (`int`): Number of top relevant documents to return (default: 5)
+
+#### Returns
+
+List of dictionaries containing:
+- **url**: The URL of the page
+- **content**: The page content
+- **score**: Relevance score
+- **metadata**: Additional page metadata
+
+### print_stats()
+
+Display crawl statistics in formatted output.
+
+```python
+def print_stats(
+    self,
+    detailed: bool = False
+) -> None
+```
+
+#### Parameters
+
+- **detailed** (`bool`): If True, shows detailed metrics with colors. If False, shows summary table.
+
+### export_knowledge_base()
+
+Export the collected knowledge base to a JSONL file.
+
+```python
+def export_knowledge_base(
+    self,
+    path: Union[str, Path]
+) -> None
+```
+
+#### Parameters
+
+- **path** (`Union[str, Path]`): Output file path for JSONL export
+
+#### Example
+
+```python
+adaptive.export_knowledge_base("my_knowledge.jsonl")
+```
+
+### import_knowledge_base()
+
+Import a previously exported knowledge base.
+
+```python
+def import_knowledge_base(
+    self,
+    path: Union[str, Path]
+) -> None
+```
+
+#### Parameters
+
+- **path** (`Union[str, Path]`): Path to JSONL file to import
+
+## Configuration
+
+The `AdaptiveConfig` class controls the behavior of adaptive crawling:
+
+```python
+@dataclass
+class AdaptiveConfig:
+    confidence_threshold: float = 0.8      # Stop when confidence reaches this
+    max_pages: int = 50                    # Maximum pages to crawl
+    top_k_links: int = 5                   # Links to follow per page
+    min_gain_threshold: float = 0.1        # Minimum expected gain to continue
+    save_state: bool = False               # Auto-save crawl state
+    state_path: Optional[str] = None       # Path for state persistence
+```
+
+### Example with Custom Config
+
+```python
+config = AdaptiveConfig(
+    confidence_threshold=0.7,
+    max_pages=20,
+    top_k_links=3
+)
+
+adaptive = AdaptiveCrawler(crawler, config=config)
+```
+
+## Complete Example
+
+```python
+import asyncio
+from crawl4ai import AsyncWebCrawler, AdaptiveCrawler, AdaptiveConfig
+
+async def main():
+    # Configure adaptive crawling
+    config = AdaptiveConfig(
+        confidence_threshold=0.75,
+        max_pages=15,
+        save_state=True,
+        state_path="my_crawl.json"
+    )
+    
+    async with AsyncWebCrawler() as crawler:
+        adaptive = AdaptiveCrawler(crawler, config)
+        
+        # Start crawling
+        state = await adaptive.digest(
+            start_url="https://example.com/docs",
+            query="authentication oauth2 jwt"
+        )
+        
+        # Check results
+        print(f"Confidence achieved: {adaptive.confidence:.0%}")
+        adaptive.print_stats()
+        
+        # Get most relevant pages
+        for page in adaptive.get_relevant_content(top_k=3):
+            print(f"- {page['url']} (score: {page['score']:.2f})")
+        
+        # Export for later use
+        adaptive.export_knowledge_base("auth_knowledge.jsonl")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## See Also
+
+- [digest() Method Reference](digest.md)
+- [Adaptive Crawling Guide](../core/adaptive-crawling.md)
+- [Advanced Adaptive Strategies](../advanced/adaptive-strategies.md)

docs/md_v2/api/digest.md

@@ -0,0 +1,181 @@
+# digest()
+
+The `digest()` method is the primary interface for adaptive web crawling. It intelligently crawls websites starting from a given URL, guided by a query, and automatically determines when sufficient information has been gathered.
+
+## Method Signature
+
+```python
+async def digest(
+    start_url: str,
+    query: str,
+    resume_from: Optional[Union[str, Path]] = None
+) -> CrawlState
+```
+
+## Parameters
+
+### start_url
+- **Type**: `str`
+- **Required**: Yes
+- **Description**: The starting URL for the crawl. This should be a valid HTTP/HTTPS URL that serves as the entry point for information gathering.
+
+### query
+- **Type**: `str`  
+- **Required**: Yes
+- **Description**: The search query that guides the crawling process. This should contain key terms related to the information you're seeking. The crawler uses this to evaluate relevance and determine which links to follow.
+
+### resume_from
+- **Type**: `Optional[Union[str, Path]]`
+- **Default**: `None`
+- **Description**: Path to a previously saved crawl state file. When provided, the crawler resumes from the saved state instead of starting fresh.
+
+## Return Value
+
+Returns a `CrawlState` object containing:
+
+- **crawled_urls** (`Set[str]`): All URLs that have been crawled
+- **knowledge_base** (`List[CrawlResult]`): Collection of crawled pages with content
+- **pending_links** (`List[Link]`): Links discovered but not yet crawled
+- **metrics** (`Dict[str, float]`): Performance and quality metrics
+- **query** (`str`): The original query
+- Additional statistical information for scoring
+
+## How It Works
+
+The `digest()` method implements an intelligent crawling algorithm:
+
+1. **Initial Crawl**: Starts from the provided URL
+2. **Link Analysis**: Evaluates all discovered links for relevance
+3. **Scoring**: Uses three metrics to assess information sufficiency:
+   - **Coverage**: How well the query terms are covered
+   - **Consistency**: Information coherence across pages
+   - **Saturation**: Diminishing returns detection
+4. **Adaptive Selection**: Chooses the most promising links to follow
+5. **Stopping Decision**: Automatically stops when confidence threshold is reached
+
+## Examples
+
+### Basic Usage
+
+```python
+async with AsyncWebCrawler() as crawler:
+    adaptive = AdaptiveCrawler(crawler)
+    
+    state = await adaptive.digest(
+        start_url="https://docs.python.org/3/",
+        query="async await context managers"
+    )
+    
+    print(f"Crawled {len(state.crawled_urls)} pages")
+    print(f"Confidence: {adaptive.confidence:.0%}")
+```
+
+### With Configuration
+
+```python
+config = AdaptiveConfig(
+    confidence_threshold=0.9,  # Require high confidence
+    max_pages=30,             # Allow more pages
+    top_k_links=3             # Follow top 3 links per page
+)
+
+adaptive = AdaptiveCrawler(crawler, config=config)
+
+state = await adaptive.digest(
+    start_url="https://api.example.com/docs",
+    query="authentication endpoints rate limits"
+)
+```
+
+### Resuming a Previous Crawl
+
+```python
+# First crawl - may be interrupted
+state1 = await adaptive.digest(
+    start_url="https://example.com",
+    query="machine learning algorithms"
+)
+
+# Save state (if not auto-saved)
+state1.save("ml_crawl_state.json")
+
+# Later, resume from saved state
+state2 = await adaptive.digest(
+    start_url="https://example.com",
+    query="machine learning algorithms",
+    resume_from="ml_crawl_state.json"
+)
+```
+
+### With Progress Monitoring
+
+```python
+state = await adaptive.digest(
+    start_url="https://docs.example.com",
+    query="api reference"
+)
+
+# Monitor progress
+print(f"Pages crawled: {len(state.crawled_urls)}")
+print(f"New terms discovered: {state.new_terms_history}")
+print(f"Final confidence: {adaptive.confidence:.2%}")
+
+# View detailed statistics
+adaptive.print_stats(detailed=True)
+```
+
+## Query Best Practices
+
+1. **Be Specific**: Use descriptive terms that appear in target content
+   ```python
+   # Good
+   query = "python async context managers implementation"
+   
+   # Too broad
+   query = "python programming"
+   ```
+
+2. **Include Key Terms**: Add technical terms you expect to find
+   ```python
+   query = "oauth2 jwt refresh tokens authorization"
+   ```
+
+3. **Multiple Concepts**: Combine related concepts for comprehensive coverage
+   ```python
+   query = "rest api pagination sorting filtering"
+   ```
+
+## Performance Considerations
+
+- **Initial URL**: Choose a page with good navigation (e.g., documentation index)
+- **Query Length**: 3-8 terms typically work best
+- **Link Density**: Sites with clear navigation crawl more efficiently
+- **Caching**: Enable caching for repeated crawls of the same domain
+
+## Error Handling
+
+```python
+try:
+    state = await adaptive.digest(
+        start_url="https://example.com",
+        query="search terms"
+    )
+except Exception as e:
+    print(f"Crawl failed: {e}")
+    # State is auto-saved if save_state=True in config
+```
+
+## Stopping Conditions
+
+The crawl stops when any of these conditions are met:
+
+1. **Confidence Threshold**: Reached the configured confidence level
+2. **Page Limit**: Crawled the maximum number of pages
+3. **Diminishing Returns**: Expected information gain below threshold
+4. **No Relevant Links**: No promising links remain to follow
+
+## See Also
+
+- [AdaptiveCrawler Class](adaptive-crawler.md)
+- [Adaptive Crawling Guide](../core/adaptive-crawling.md)
+- [Configuration Options](../core/adaptive-crawling.md#configuration-options)

docs/md_v2/api/parameters.md

@@ -298,7 +298,7 @@ LLMConfig is useful to pass LLM provider config to strategies and functions that
 ## 3.1 Parameters
 | **Parameter**         | **Type / Default**                     | **What It Does**                                                                                                                     |
 |-----------------------|----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
-| **`provider`**    | `"ollama/llama3","groq/llama3-70b-8192","groq/llama3-8b-8192", "openai/gpt-4o-mini" ,"openai/gpt-4o","openai/o1-mini","openai/o1-preview","openai/o3-mini","openai/o3-mini-high","anthropic/claude-3-haiku-20240307","anthropic/claude-3-opus-20240229","anthropic/claude-3-sonnet-20240229","anthropic/claude-3-5-sonnet-20240620","gemini/gemini-pro","gemini/gemini-1.5-pro","gemini/gemini-2.0-flash","gemini/gemini-2.0-flash-exp","gemini/gemini-2.0-flash-lite-preview-02-05","deepseek/deepseek-chat"`<br/>*(default: `"openai/gpt-4o-mini"`)* | Which LLM provoder to use. 
+| **`provider`**    | `"ollama/llama3","groq/llama3-70b-8192","groq/llama3-8b-8192", "openai/gpt-4o-mini" ,"openai/gpt-4o","openai/o1-mini","openai/o1-preview","openai/o3-mini","openai/o3-mini-high","anthropic/claude-3-haiku-20240307","anthropic/claude-3-opus-20240229","anthropic/claude-3-sonnet-20240229","anthropic/claude-3-5-sonnet-20240620","gemini/gemini-pro","gemini/gemini-1.5-pro","gemini/gemini-2.0-flash","gemini/gemini-2.0-flash-exp","gemini/gemini-2.0-flash-lite-preview-02-05","deepseek/deepseek-chat"`<br/>*(default: `"openai/gpt-4o-mini"`)* | Which LLM provider to use. 
 | **`api_token`**         |1.Optional. When not provided explicitly, api_token will be read from environment variables based on provider. For example: If a gemini model is passed as provider then,`"GEMINI_API_KEY"` will be read from environment variables  <br/> 2. API token of LLM provider <br/> eg: `api_token = "gsk_1ClHGGJ7Lpn4WGybR7vNWGdyb3FY7zXEw3SCiy0BAVM9lL8CQv"` <br/> 3. Environment variable - use with prefix "env:" <br/> eg:`api_token = "env: GROQ_API_KEY"`              | API token to use for the given provider 
 | **`base_url`**         |Optional. Custom API endpoint | If your provider has a custom endpoint
 

docs/md_v2/blog/articles/adaptive-crawling-revolution.md

@@ -0,0 +1,369 @@
+# Adaptive Crawling: Building Dynamic Knowledge That Grows on Demand
+
+*Published on January 29, 2025 • 8 min read*
+
+*By [unclecode](https://x.com/unclecode) • Follow me on [X/Twitter](https://x.com/unclecode) for more web scraping insights*
+
+---
+
+## The Knowledge Capacitor
+
+Imagine a capacitor that stores energy, releasing it precisely when needed. Now imagine that for information. That's Adaptive Crawling—a term I coined to describe a fundamentally different approach to web crawling. Instead of the brute force of traditional deep crawling, we build knowledge dynamically, growing it based on queries and circumstances, like a living organism responding to its environment.
+
+This isn't just another crawling optimization. It's a paradigm shift from "crawl everything, hope for the best" to "crawl intelligently, know when to stop."
+
+## Why I Built This
+
+I've watched too many startups burn through resources with a dangerous misconception: that LLMs make everything efficient. They don't. They make things *possible*, not necessarily *smart*. When you combine brute-force crawling with LLM processing, you're not just wasting time—you're hemorrhaging money on tokens, compute, and opportunity cost.
+
+Consider this reality:
+- **Traditional deep crawling**: 500 pages → 50 useful → $15 in LLM tokens → 2 hours wasted
+- **Adaptive crawling**: 15 pages → 14 useful → $2 in tokens → 10 minutes → **7.5x cost reduction**
+
+But it's not about crawling less. It's about crawling *right*.
+
+## The Information Theory Foundation
+
+<div style="background-color: #1a1a1c; border: 1px solid #3f3f44; padding: 20px; margin: 20px 0;">
+
+### 🧮 **Pure Statistics, No Magic**
+
+My first principle was crucial: start with classic statistical approaches. No embeddings. No LLMs. Just pure information theory:
+
+```python
+# Information gain calculation - the heart of adaptive crawling
+def calculate_information_gain(new_page, knowledge_base):
+    new_terms = extract_terms(new_page) - existing_terms(knowledge_base)
+    overlap = calculate_overlap(new_page, knowledge_base)
+    
+    # High gain = many new terms + low overlap
+    gain = len(new_terms) / (1 + overlap)
+    return gain
+```
+
+This isn't regression to older methods—it's recognition that we've forgotten powerful, efficient solutions in our rush to apply LLMs everywhere.
+
+</div>
+
+## The A* of Web Crawling
+
+Adaptive crawling implements what I call "information scenting"—like A* pathfinding but for knowledge acquisition. Each link is evaluated not randomly, but by its probability of contributing meaningful information toward answering current and future queries.
+
+<div style="display: flex; align-items: center; background-color: #3f3f44; padding: 20px; margin: 20px 0; border-left: 4px solid #09b5a5;">
+<div style="font-size: 48px; margin-right: 20px;">🎯</div>
+<div>
+<strong>The Scenting Algorithm:</strong><br>
+From available links, we select those with highest information gain. It's not about following every path—it's about following the <em>right</em> paths. Like a bloodhound following the strongest scent to its target.
+</div>
+</div>
+
+## The Three Pillars of Intelligence
+
+### 1. Coverage: The Breadth Sensor
+Measures how well your knowledge spans the query space. Not just "do we have pages?" but "do we have the RIGHT pages?"
+
+### 2. Consistency: The Coherence Detector  
+Information from multiple sources should align. When pages agree, confidence rises. When they conflict, we need more data.
+
+### 3. Saturation: The Efficiency Guardian
+The most crucial metric. When new pages stop adding information, we stop crawling. Simple. Powerful. Ignored by everyone else.
+
+## Real Impact: Time, Money, and Sanity
+
+Let me show you what this means for your bottom line:
+
+### Building a Customer Support Knowledge Base
+
+**Traditional Approach:**
+```python
+# Crawl entire documentation site
+results = await crawler.crawl_bfs("https://docs.company.com", max_depth=5)
+# Result: 1,200 pages, 18 hours, $150 in API costs
+# Useful content: ~100 pages scattered throughout
+```
+
+**Adaptive Approach:**
+```python
+# Grow knowledge based on actual support queries
+knowledge = await adaptive.digest(
+    start_url="https://docs.company.com",
+    query="payment processing errors refund policies"
+)
+# Result: 45 pages, 12 minutes, $8 in API costs
+# Useful content: 42 pages, all relevant
+```
+
+**Savings: 93% time reduction, 95% cost reduction, 100% more sanity**
+
+## The Dynamic Growth Pattern
+
+<div style="text-align: center; padding: 40px; background-color: #1a1a1c; border: 1px dashed #3f3f44; margin: 30px 0;">
+<div style="font-size: 24px; color: #09b5a5; margin-bottom: 10px;">
+Knowledge grows like crystals in a supersaturated solution
+</div>
+<div style="color: #a3abba;">
+Add a query (seed), and relevant information crystallizes around it.<br>
+Change the query, and the knowledge structure adapts.
+</div>
+</div>
+
+This is the beauty of adaptive crawling: your knowledge base becomes a living entity that grows based on actual needs, not hypothetical completeness.
+
+## Why "Adaptive"? 
+
+I specifically chose "Adaptive" because it captures the essence: the system adapts to what it finds. Dense technical documentation might need 20 pages for confidence. A simple FAQ might need just 5. The crawler doesn't follow a recipe—it reads the room and adjusts.
+
+This is my term, my concept, and I have extensive plans for its evolution.
+
+## The Progressive Roadmap
+
+This is just the beginning. My roadmap for Adaptive Crawling:
+
+### Phase 1 (Current): Statistical Foundation
+- Pure information theory approach
+- No dependencies on expensive models
+- Proven efficiency gains
+
+### Phase 2 (Now Available): Embedding Enhancement
+- Semantic understanding layered onto statistical base
+- Still efficient, now even smarter
+- Optional, not required
+
+### Phase 3 (Future): LLM Integration
+- LLMs for complex reasoning tasks only
+- Used surgically, not wastefully
+- Always with statistical foundation underneath
+
+## The Efficiency Revolution
+
+<div style="background-color: #1a1a1c; border: 1px solid #3f3f44; padding: 20px; margin: 20px 0;">
+
+### 💰 **The Economics of Intelligence**
+
+For a typical SaaS documentation crawl:
+
+**Traditional Deep Crawling:**
+- Pages crawled: 1,000
+- Useful pages: 80
+- Time spent: 3 hours
+- LLM tokens used: 2.5M
+- Cost: $75
+- Efficiency: 8%
+
+**Adaptive Crawling:**
+- Pages crawled: 95
+- Useful pages: 88
+- Time spent: 15 minutes
+- LLM tokens used: 200K
+- Cost: $6
+- Efficiency: 93%
+
+**That's not optimization. That's transformation.**
+
+</div>
+
+## Missing the Forest for the Trees
+
+The startup world has a dangerous blind spot. We're so enamored with LLMs that we forget: just because you CAN process everything with an LLM doesn't mean you SHOULD. 
+
+Classic NLP and statistical methods can:
+- Filter irrelevant content before it reaches LLMs
+- Identify patterns without expensive inference
+- Make intelligent decisions in microseconds
+- Scale without breaking the bank
+
+Adaptive crawling proves this. It uses battle-tested information theory to make smart decisions BEFORE expensive processing.
+
+## Your Knowledge, On Demand
+
+```python
+# Monday: Customer asks about authentication
+auth_knowledge = await adaptive.digest(
+    "https://docs.api.com",
+    "oauth jwt authentication"
+)
+
+# Tuesday: They ask about rate limiting
+# The crawler adapts, builds on existing knowledge
+rate_limit_knowledge = await adaptive.digest(
+    "https://docs.api.com", 
+    "rate limiting throttling quotas"
+)
+
+# Your knowledge base grows intelligently, not indiscriminately
+```
+
+## The Competitive Edge
+
+Companies using adaptive crawling will have:
+- **90% lower crawling costs**
+- **Knowledge bases that actually answer questions**
+- **Update cycles in minutes, not days**
+- **Happy customers who find answers fast**
+- **Engineers who sleep at night**
+
+Those still using brute force? They'll wonder why their infrastructure costs keep rising while their customers keep complaining.
+
+## The Embedding Evolution (Now Available!)
+
+<div style="background-color: #1a1a1c; border: 1px solid #3f3f44; padding: 20px; margin: 20px 0;">
+
+### 🧠 **Semantic Understanding Without the Cost**
+
+The embedding strategy brings semantic intelligence while maintaining efficiency:
+
+```python
+# Statistical strategy - great for exact terms
+config_statistical = AdaptiveConfig(
+    strategy="statistical"  # Default
+)
+
+# Embedding strategy - understands concepts
+config_embedding = AdaptiveConfig(
+    strategy="embedding",
+    embedding_model="sentence-transformers/all-MiniLM-L6-v2",
+    n_query_variations=10
+)
+```
+
+**The magic**: It automatically expands your query into semantic variations, maps the coverage space, and identifies gaps to fill intelligently.
+
+</div>
+
+### Real-World Comparison
+
+<div style="display: flex; gap: 20px; margin: 20px 0;">
+<div style="flex: 1; background-color: #1a1a1c; border: 1px solid #3f3f44; padding: 20px;">
+
+**Query**: "authentication oauth"
+
+**Statistical Strategy**:
+- Searches for exact terms
+- 12 pages crawled
+- 78% confidence
+- Fast but literal
+
+</div>
+<div style="flex: 1; background-color: #1a1a1c; border: 1px solid #09b5a5; padding: 20px;">
+
+**Embedding Strategy**:
+- Understands "auth", "login", "SSO"
+- 8 pages crawled
+- 92% confidence
+- Semantic comprehension
+
+</div>
+</div>
+
+### Detecting Irrelevance
+
+One killer feature: the embedding strategy knows when to give up:
+
+```python
+# Crawling Python docs with a cooking query
+result = await adaptive.digest(
+    start_url="https://docs.python.org/3/",
+    query="how to make spaghetti carbonara"
+)
+
+# System detects irrelevance and stops
+# Confidence: 5% (below threshold)
+# Pages crawled: 2
+# Stopped reason: "below_minimum_relevance_threshold"
+```
+
+No more crawling hundreds of pages hoping to find something that doesn't exist!
+
+## Try It Yourself
+
+```python
+from crawl4ai import AsyncWebCrawler, AdaptiveCrawler, AdaptiveConfig
+
+async with AsyncWebCrawler() as crawler:
+    # Choose your strategy
+    config = AdaptiveConfig(
+        strategy="embedding",  # or "statistical"
+        embedding_min_confidence_threshold=0.1  # Stop if irrelevant
+    )
+    
+    adaptive = AdaptiveCrawler(crawler, config)
+    
+    # Watch intelligence at work
+    result = await adaptive.digest(
+        start_url="https://your-docs.com",
+        query="your users' actual questions"
+    )
+    
+    # See the efficiency
+    adaptive.print_stats()
+    print(f"Found {adaptive.confidence:.0%} of needed information")
+    print(f"In just {len(result.crawled_urls)} pages")
+    print(f"Saving you {1000 - len(result.crawled_urls)} unnecessary crawls")
+```
+
+## A Personal Note
+
+I created Adaptive Crawling because I was tired of watching smart people make inefficient choices. We have incredibly powerful statistical tools that we've forgotten in our rush toward LLMs. This is my attempt to bring balance back to the Force.
+
+This is not just a feature. It's a philosophy: **Grow knowledge on demand. Stop when you have enough. Save time, money, and computational resources for what really matters.**
+
+## The Future is Adaptive
+
+<div style="text-align: center; padding: 40px; background-color: #1a1a1c; border: 1px dashed #3f3f44; margin: 30px 0;">
+<div style="font-size: 24px; color: #09b5a5; margin-bottom: 10px;">
+Traditional Crawling: Drinking from a firehose<br>
+Adaptive Crawling: Sipping exactly what you need
+</div>
+<div style="color: #a3abba;">
+The future of web crawling isn't about processing more data.<br>
+It's about processing the <em>right</em> data.
+</div>
+</div>
+
+Join me in making web crawling intelligent, efficient, and actually useful. Because in the age of information overload, the winners won't be those who collect the most data—they'll be those who collect the *right* data.
+
+---
+
+*Adaptive Crawling is now part of Crawl4AI. [Get started with the documentation](/core/adaptive-crawling/) or [dive into the mathematical framework](https://github.com/unclecode/crawl4ai/blob/main/PROGRESSIVE_CRAWLING.md). For updates on my work in information theory and efficient AI, follow me on [X/Twitter](https://x.com/unclecode).*
+
+<style>
+/* Custom styles for this article */
+.markdown-body pre {
+    background-color: #1e1e1e !important;
+    border: 1px solid #3f3f44;
+}
+
+.markdown-body code {
+    background-color: #3f3f44;
+    color: #50ffff;
+    padding: 2px 6px;
+    border-radius: 3px;
+}
+
+.markdown-body pre code {
+    background-color: transparent;
+    color: #e8e9ed;
+    padding: 0;
+}
+
+.markdown-body blockquote {
+    border-left: 4px solid #09b5a5;
+    background-color: #1a1a1c;
+    padding: 15px 20px;
+    margin: 20px 0;
+}
+
+.markdown-body h2 {
+    color: #50ffff;
+    border-bottom: 1px dashed #3f3f44;
+    padding-bottom: 10px;
+}
+
+.markdown-body h3 {
+    color: #09b5a5;
+}
+
+.markdown-body strong {
+    color: #50ffff;
+}
+</style>

docs/md_v2/blog/index.md

@@ -2,6 +2,22 @@
 
 Welcome to the Crawl4AI blog! Here you'll find detailed release notes, technical insights, and updates about the project. Whether you're looking for the latest improvements or want to dive deep into web crawling techniques, this is the place.
 
+## Featured Articles
+
+### [When to Stop Crawling: The Art of Knowing "Enough"](articles/adaptive-crawling-revolution.md)
+*January 29, 2025*
+
+Traditional crawlers are like tourists with unlimited time—they'll visit every street, every alley, every dead end. But what if your crawler could think like a researcher with a deadline? Discover how Adaptive Crawling revolutionizes web scraping by knowing when to stop. Learn about the three-layer intelligence system that evaluates coverage, consistency, and saturation to build focused knowledge bases instead of endless page collections.
+
+[Read the full article →](articles/adaptive-crawling-revolution.md)
+
+### [The LLM Context Protocol: Why Your AI Assistant Needs Memory, Reasoning, and Examples](articles/llm-context-revolution.md)
+*January 24, 2025*
+
+Ever wondered why your AI coding assistant struggles with your library despite comprehensive documentation? This article introduces the three-dimensional context protocol that transforms how AI understands code. Learn why memory, reasoning, and examples together create wisdom—not just information.
+
+[Read the full article →](articles/llm-context-revolution.md)
+
 ## Latest Release
 
 Here’s the blog index entry for **v0.6.0**, written to match the exact tone and structure of your previous entries:

docs/md_v2/core/adaptive-crawling.md

@@ -0,0 +1,347 @@
+# Adaptive Web Crawling
+
+## Introduction
+
+Traditional web crawlers follow predetermined patterns, crawling pages blindly without knowing when they've gathered enough information. **Adaptive Crawling** changes this paradigm by introducing intelligence into the crawling process.
+
+Think of it like research: when you're looking for information, you don't read every book in the library. You stop when you've found sufficient information to answer your question. That's exactly what Adaptive Crawling does for web scraping.
+
+## Key Concepts
+
+### The Problem It Solves
+
+When crawling websites for specific information, you face two challenges:
+1. **Under-crawling**: Stopping too early and missing crucial information
+2. **Over-crawling**: Wasting resources by crawling irrelevant pages
+
+Adaptive Crawling solves both by using a three-layer scoring system that determines when you have "enough" information.
+
+### How It Works
+
+The AdaptiveCrawler uses three metrics to measure information sufficiency:
+
+- **Coverage**: How well your collected pages cover the query terms
+- **Consistency**: Whether the information is coherent across pages  
+- **Saturation**: Detecting when new pages aren't adding new information
+
+When these metrics indicate sufficient information has been gathered, crawling stops automatically.
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from crawl4ai import AsyncWebCrawler, AdaptiveCrawler
+
+async def main():
+    async with AsyncWebCrawler() as crawler:
+        # Create an adaptive crawler
+        adaptive = AdaptiveCrawler(crawler)
+        
+        # Start crawling with a query
+        result = await adaptive.digest(
+            start_url="https://docs.python.org/3/",
+            query="async context managers"
+        )
+        
+        # View statistics
+        adaptive.print_stats()
+        
+        # Get the most relevant content
+        relevant_pages = adaptive.get_relevant_content(top_k=5)
+        for page in relevant_pages:
+            print(f"- {page['url']} (score: {page['score']:.2f})")
+```
+
+### Configuration Options
+
+```python
+from crawl4ai import AdaptiveConfig
+
+config = AdaptiveConfig(
+    confidence_threshold=0.7,    # Stop when 70% confident (default: 0.8)
+    max_pages=20,               # Maximum pages to crawl (default: 50)
+    top_k_links=3,              # Links to follow per page (default: 5)
+    min_gain_threshold=0.05     # Minimum expected gain to continue (default: 0.1)
+)
+
+adaptive = AdaptiveCrawler(crawler, config=config)
+```
+
+## Crawling Strategies
+
+Adaptive Crawling supports two distinct strategies for determining information sufficiency:
+
+### Statistical Strategy (Default)
+
+The statistical strategy uses pure information theory and term-based analysis:
+
+- **Fast and efficient** - No API calls or model loading
+- **Term-based coverage** - Analyzes query term presence and distribution
+- **No external dependencies** - Works offline
+- **Best for**: Well-defined queries with specific terminology
+
+```python
+# Default configuration uses statistical strategy
+config = AdaptiveConfig(
+    strategy="statistical",  # This is the default
+    confidence_threshold=0.8
+)
+```
+
+### Embedding Strategy
+
+The embedding strategy uses semantic embeddings for deeper understanding:
+
+- **Semantic understanding** - Captures meaning beyond exact term matches
+- **Query expansion** - Automatically generates query variations
+- **Gap-driven selection** - Identifies semantic gaps in knowledge
+- **Validation-based stopping** - Uses held-out queries to validate coverage
+- **Best for**: Complex queries, ambiguous topics, conceptual understanding
+
+```python
+# Configure embedding strategy
+config = AdaptiveConfig(
+    strategy="embedding",
+    embedding_model="sentence-transformers/all-MiniLM-L6-v2",  # Default
+    n_query_variations=10,  # Generate 10 query variations
+    embedding_min_confidence_threshold=0.1  # Stop if completely irrelevant
+)
+
+# With custom embedding provider (e.g., OpenAI)
+config = AdaptiveConfig(
+    strategy="embedding",
+    embedding_llm_config={
+        'provider': 'openai/text-embedding-3-small',
+        'api_token': 'your-api-key'
+    }
+)
+```
+
+### Strategy Comparison
+
+| Feature | Statistical | Embedding |
+|---------|------------|-----------|
+| **Speed** | Very fast | Moderate (API calls) |
+| **Cost** | Free | Depends on provider |
+| **Accuracy** | Good for exact terms | Excellent for concepts |
+| **Dependencies** | None | Embedding model/API |
+| **Query Understanding** | Literal | Semantic |
+| **Best Use Case** | Technical docs, specific terms | Research, broad topics |
+
+### Embedding Strategy Configuration
+
+The embedding strategy offers fine-tuned control through several parameters:
+
+```python
+config = AdaptiveConfig(
+    strategy="embedding",
+    
+    # Model configuration
+    embedding_model="sentence-transformers/all-MiniLM-L6-v2",
+    embedding_llm_config=None,  # Use for API-based embeddings
+    
+    # Query expansion
+    n_query_variations=10,  # Number of query variations to generate
+    
+    # Coverage parameters
+    embedding_coverage_radius=0.2,  # Distance threshold for coverage
+    embedding_k_exp=3.0,  # Exponential decay factor (higher = stricter)
+    
+    # Stopping criteria
+    embedding_min_relative_improvement=0.1,  # Min improvement to continue
+    embedding_validation_min_score=0.3,  # Min validation score
+    embedding_min_confidence_threshold=0.1,  # Below this = irrelevant
+    
+    # Link selection
+    embedding_overlap_threshold=0.85,  # Similarity for deduplication
+    
+    # Display confidence mapping
+    embedding_quality_min_confidence=0.7,  # Min displayed confidence
+    embedding_quality_max_confidence=0.95  # Max displayed confidence
+)
+```
+
+### Handling Irrelevant Queries
+
+The embedding strategy can detect when a query is completely unrelated to the content:
+
+```python
+# This will stop quickly with low confidence
+result = await adaptive.digest(
+    start_url="https://docs.python.org/3/",
+    query="how to cook pasta"  # Irrelevant to Python docs
+)
+
+# Check if query was irrelevant
+if result.metrics.get('is_irrelevant', False):
+    print("Query is unrelated to the content!")
+```
+
+## When to Use Adaptive Crawling
+
+### Perfect For:
+- **Research Tasks**: Finding comprehensive information about a topic
+- **Question Answering**: Gathering sufficient context to answer specific queries
+- **Knowledge Base Building**: Creating focused datasets for AI/ML applications
+- **Competitive Intelligence**: Collecting complete information about specific products/features
+
+### Not Recommended For:
+- **Full Site Archiving**: When you need every page regardless of content
+- **Structured Data Extraction**: When targeting specific, known page patterns
+- **Real-time Monitoring**: When you need continuous updates
+
+## Understanding the Output
+
+### Confidence Score
+
+The confidence score (0-1) indicates how sufficient the gathered information is:
+- **0.0-0.3**: Insufficient information, needs more crawling
+- **0.3-0.6**: Partial information, may answer basic queries
+- **0.6-0.8**: Good coverage, can answer most queries
+- **0.8-1.0**: Excellent coverage, comprehensive information
+
+### Statistics Display
+
+```python
+adaptive.print_stats(detailed=False)  # Summary table
+adaptive.print_stats(detailed=True)   # Detailed metrics
+```
+
+The summary shows:
+- Pages crawled vs. confidence achieved
+- Coverage, consistency, and saturation scores
+- Crawling efficiency metrics
+
+## Persistence and Resumption
+
+### Saving Progress
+
+```python
+config = AdaptiveConfig(
+    save_state=True,
+    state_path="my_crawl_state.json"
+)
+
+# Crawl will auto-save progress
+result = await adaptive.digest(start_url, query)
+```
+
+### Resuming a Crawl
+
+```python
+# Resume from saved state
+result = await adaptive.digest(
+    start_url,
+    query,
+    resume_from="my_crawl_state.json"
+)
+```
+
+### Exporting Knowledge Base
+
+```python
+# Export collected pages to JSONL
+adaptive.export_knowledge_base("knowledge_base.jsonl")
+
+# Import into another session
+new_adaptive = AdaptiveCrawler(crawler)
+new_adaptive.import_knowledge_base("knowledge_base.jsonl")
+```
+
+## Best Practices
+
+### 1. Query Formulation
+- Use specific, descriptive queries
+- Include key terms you expect to find
+- Avoid overly broad queries
+
+### 2. Threshold Tuning
+- Start with default (0.8) for general use
+- Lower to 0.6-0.7 for exploratory crawling
+- Raise to 0.9+ for exhaustive coverage
+
+### 3. Performance Optimization
+- Use appropriate `max_pages` limits
+- Adjust `top_k_links` based on site structure
+- Enable caching for repeat crawls
+
+### 4. Link Selection
+- The crawler prioritizes links based on:
+  - Relevance to query
+  - Expected information gain
+  - URL structure and depth
+
+## Examples
+
+### Research Assistant
+
+```python
+# Gather information about a programming concept
+result = await adaptive.digest(
+    start_url="https://realpython.com",
+    query="python decorators implementation patterns"
+)
+
+# Get the most relevant excerpts
+for doc in adaptive.get_relevant_content(top_k=3):
+    print(f"\nFrom: {doc['url']}")
+    print(f"Relevance: {doc['score']:.2%}")
+    print(doc['content'][:500] + "...")
+```
+
+### Knowledge Base Builder
+
+```python
+# Build a focused knowledge base about machine learning
+queries = [
+    "supervised learning algorithms",
+    "neural network architectures", 
+    "model evaluation metrics"
+]
+
+for query in queries:
+    await adaptive.digest(
+        start_url="https://scikit-learn.org/stable/",
+        query=query
+    )
+    
+# Export combined knowledge base
+adaptive.export_knowledge_base("ml_knowledge.jsonl")
+```
+
+### API Documentation Crawler
+
+```python
+# Intelligently crawl API documentation
+config = AdaptiveConfig(
+    confidence_threshold=0.85,  # Higher threshold for completeness
+    max_pages=30
+)
+
+adaptive = AdaptiveCrawler(crawler, config)
+result = await adaptive.digest(
+    start_url="https://api.example.com/docs",
+    query="authentication endpoints rate limits"
+)
+```
+
+## Next Steps
+
+- Learn about [Advanced Adaptive Strategies](../advanced/adaptive-strategies.md)
+- Explore the [AdaptiveCrawler API Reference](../api/adaptive-crawler.md)
+- See more [Examples](https://github.com/unclecode/crawl4ai/tree/main/docs/examples/adaptive_crawling)
+
+## FAQ
+
+**Q: How is this different from traditional crawling?**
+A: Traditional crawling follows fixed patterns (BFS/DFS). Adaptive crawling makes intelligent decisions about which links to follow and when to stop based on information gain.
+
+**Q: Can I use this with JavaScript-heavy sites?**
+A: Yes! AdaptiveCrawler inherits all capabilities from AsyncWebCrawler, including JavaScript execution.
+
+**Q: How does it handle large websites?**
+A: The algorithm naturally limits crawling to relevant sections. Use `max_pages` as a safety limit.
+
+**Q: Can I customize the scoring algorithms?**
+A: Advanced users can implement custom strategies. See [Adaptive Strategies](../advanced/adaptive-strategies.md).

docs/md_v2/core/browser-crawler-config.md

@@ -252,7 +252,7 @@ The `clone()` method:
 ### Key fields to note
 
 1. **`provider`**:  
-- Which LLM provoder to use. 
+- Which LLM provider to use. 
 - Possible values are `"ollama/llama3","groq/llama3-70b-8192","groq/llama3-8b-8192", "openai/gpt-4o-mini" ,"openai/gpt-4o","openai/o1-mini","openai/o1-preview","openai/o3-mini","openai/o3-mini-high","anthropic/claude-3-haiku-20240307","anthropic/claude-3-opus-20240229","anthropic/claude-3-sonnet-20240229","anthropic/claude-3-5-sonnet-20240620","gemini/gemini-pro","gemini/gemini-1.5-pro","gemini/gemini-2.0-flash","gemini/gemini-2.0-flash-exp","gemini/gemini-2.0-flash-lite-preview-02-05","deepseek/deepseek-chat"`<br/>*(default: `"openai/gpt-4o-mini"`)*
 
 2. **`api_token`**:  
@@ -273,7 +273,7 @@ In a typical scenario, you define **one** `BrowserConfig` for your crawler sessi
 
 ```python
 import asyncio
-from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode, LLMConfig
+from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode, LLMConfig, LLMContentFilter, DefaultMarkdownGenerator
 from crawl4ai import JsonCssExtractionStrategy
 
 async def main():
@@ -298,7 +298,7 @@ async def main():
     # 3) Example LLM content filtering
 
     gemini_config = LLMConfig(
-        provider="gemini/gemini-1.5-pro" 
+        provider="gemini/gemini-1.5-pro", 
         api_token = "env:GEMINI_API_TOKEN"
     )
 
@@ -322,8 +322,9 @@ async def main():
     )
 
     md_generator = DefaultMarkdownGenerator(
-    content_filter=filter,
-    options={"ignore_links": True}
+        content_filter=filter,
+        options={"ignore_links": True}
+    )
 
     # 4) Crawler run config: skip cache, use extraction
     run_conf = CrawlerRunConfig(

docs/md_v2/core/cli.md

@@ -17,6 +17,9 @@
 - [Configuration Reference](#configuration-reference)
 - [Best Practices & Tips](#best-practices--tips)
 
+## Installation
+The Crawl4AI CLI will be installed automatically when you install the library.
+
 ## Basic Usage
 
 The Crawl4AI CLI (`crwl`) provides a simple interface to the Crawl4AI library:

docs/md_v2/core/examples.md

@@ -28,7 +28,11 @@ This page provides a comprehensive list of example scripts that demonstrate vari
 | Example | Description | Link |
 |---------|-------------|------|
 | Deep Crawling | An extensive tutorial on deep crawling capabilities, demonstrating BFS and BestFirst strategies, stream vs. non-stream execution, filters, scorers, and advanced configurations. | [View Code](https://github.com/unclecode/crawl4ai/blob/main/docs/examples/deepcrawl_example.py) |
+<<<<<<< HEAD
 | Virtual Scroll | Comprehensive examples for handling virtualized scrolling on sites like Twitter, Instagram. Demonstrates different scrolling scenarios with local test server. | [View Code](https://github.com/unclecode/crawl4ai/blob/main/docs/examples/virtual_scroll_example.py) |
+=======
+| Adaptive Crawling | Demonstrates intelligent crawling that automatically determines when sufficient information has been gathered. | [View Code](https://github.com/unclecode/crawl4ai/blob/main/docs/examples/adaptive_crawling/) |
+>>>>>>> feature/progressive-crawling
 | Dispatcher | Shows how to use the crawl dispatcher for advanced workload management. | [View Code](https://github.com/unclecode/crawl4ai/blob/main/docs/examples/dispatcher_example.py) |
 | Storage State | Tutorial on managing browser storage state for persistence. | [View Guide](https://github.com/unclecode/crawl4ai/blob/main/docs/examples/storage_state_tutorial.md) |
 | Network Console Capture | Demonstrates how to capture and analyze network requests and console logs. | [View Code](https://github.com/unclecode/crawl4ai/blob/main/docs/examples/network_console_capture_example.py) |

docs/md_v2/core/local-files.md

@@ -8,11 +8,10 @@ To crawl a live web page, provide the URL starting with `http://` or `https://`,
 
 ```python
 import asyncio
-from crawl4ai import AsyncWebCrawler
-from crawl4ai.async_configs import CrawlerRunConfig
+from crawl4ai import AsyncWebCrawler, CacheMode, CrawlerRunConfig
 
 async def crawl_web():
-    config = CrawlerRunConfig(bypass_cache=True)
+    config = CrawlerRunConfig(cache_mode=CacheMode.BYPASS)
     async with AsyncWebCrawler() as crawler:
         result = await crawler.arun(
             url="https://en.wikipedia.org/wiki/apple", 
@@ -33,13 +32,12 @@ To crawl a local HTML file, prefix the file path with `file://`.
 
 ```python
 import asyncio
-from crawl4ai import AsyncWebCrawler
-from crawl4ai.async_configs import CrawlerRunConfig
+from crawl4ai import AsyncWebCrawler, CacheMode, CrawlerRunConfig
 
 async def crawl_local_file():
     local_file_path = "/path/to/apple.html"  # Replace with your file path
     file_url = f"file://{local_file_path}"
-    config = CrawlerRunConfig(bypass_cache=True)
+    config = CrawlerRunConfig(cache_mode=CacheMode.BYPASS)
     
     async with AsyncWebCrawler() as crawler:
         result = await crawler.arun(url=file_url, config=config)
@@ -93,8 +91,7 @@ import os
 import sys
 import asyncio
 from pathlib import Path
-from crawl4ai import AsyncWebCrawler
-from crawl4ai.async_configs import CrawlerRunConfig
+from crawl4ai import AsyncWebCrawler, CacheMode, CrawlerRunConfig
 
 async def main():
     wikipedia_url = "https://en.wikipedia.org/wiki/apple"
@@ -104,7 +101,7 @@ async def main():
     async with AsyncWebCrawler() as crawler:
         # Step 1: Crawl the Web URL
         print("\n=== Step 1: Crawling the Wikipedia URL ===")
-        web_config = CrawlerRunConfig(bypass_cache=True)
+        web_config = CrawlerRunConfig(cache_mode=CacheMode.BYPASS)
         result = await crawler.arun(url=wikipedia_url, config=web_config)
 
         if not result.success:
@@ -119,7 +116,7 @@ async def main():
         # Step 2: Crawl from the Local HTML File
         print("=== Step 2: Crawling from the Local HTML File ===")
         file_url = f"file://{html_file_path.resolve()}"
-        file_config = CrawlerRunConfig(bypass_cache=True)
+        file_config = CrawlerRunConfig(cache_mode=CacheMode.BYPASS)
         local_result = await crawler.arun(url=file_url, config=file_config)
 
         if not local_result.success:
@@ -135,7 +132,7 @@ async def main():
         with open(html_file_path, 'r', encoding='utf-8') as f:
             raw_html_content = f.read()
         raw_html_url = f"raw:{raw_html_content}"
-        raw_config = CrawlerRunConfig(bypass_cache=True)
+        raw_config = CrawlerRunConfig(cache_mode=CacheMode.BYPASS)
         raw_result = await crawler.arun(url=raw_html_url, config=raw_config)
 
         if not raw_result.success:

docs/md_v2/core/markdown-generation.md

@@ -200,7 +200,8 @@ config = CrawlerRunConfig(markdown_generator=md_generator)
 
 - **`user_query`**: The term you want to focus on. BM25 tries to keep only content blocks relevant to that query.  
 - **`bm25_threshold`**: Raise it to keep fewer blocks; lower it to keep more.  
-- **`use_stemming`** *(default `True`)*: If enabled, variations of words match (e.g., “learn,” “learning,” “learnt”).
+- **`use_stemming`** *(default `True`)*: Whether to apply stemming to the query and content.
+- **`language (str)`**: Language for stemming (default: 'english').
 
 **No query provided?** BM25 tries to glean a context from page metadata, or you can simply treat it as a scorched-earth approach that discards text with low generic score. Realistically, you want to supply a query for best results.
 
@@ -233,7 +234,7 @@ prune_filter = PruningContentFilter(
 For intelligent content filtering and high-quality markdown generation, you can use the **LLMContentFilter**. This filter leverages LLMs to generate relevant markdown while preserving the original content's meaning and structure:
 
 ```python
-from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, LLMConfig
+from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, LLMConfig, DefaultMarkdownGenerator
 from crawl4ai.content_filter_strategy import LLMContentFilter
 
 async def main():
@@ -255,9 +256,12 @@ async def main():
         chunk_token_threshold=4096,  # Adjust based on your needs
         verbose=True
     )
-
+    md_generator = DefaultMarkdownGenerator(
+        content_filter=filter,
+        options={"ignore_links": True}
+    )
     config = CrawlerRunConfig(
-        content_filter=filter
+        markdown_generator=md_generator,
     )
 
     async with AsyncWebCrawler() as crawler:

docs/md_v2/core/quickstart.md

@@ -272,7 +272,43 @@ if __name__ == "__main__":
 
 ---
 
-## 7. Multi-URL Concurrency (Preview)
+## 7. Adaptive Crawling (New!)
+
+Crawl4AI now includes intelligent adaptive crawling that automatically determines when sufficient information has been gathered. Here's a quick example:
+
+```python
+import asyncio
+from crawl4ai import AsyncWebCrawler, AdaptiveCrawler
+
+async def adaptive_example():
+    async with AsyncWebCrawler() as crawler:
+        adaptive = AdaptiveCrawler(crawler)
+        
+        # Start adaptive crawling
+        result = await adaptive.digest(
+            start_url="https://docs.python.org/3/",
+            query="async context managers"
+        )
+        
+        # View results
+        adaptive.print_stats()
+        print(f"Crawled {len(result.crawled_urls)} pages")
+        print(f"Achieved {adaptive.confidence:.0%} confidence")
+
+if __name__ == "__main__":
+    asyncio.run(adaptive_example())
+```
+
+**What's special about adaptive crawling?**
+- **Automatic stopping**: Stops when sufficient information is gathered
+- **Intelligent link selection**: Follows only relevant links
+- **Confidence scoring**: Know how complete your information is
+
+[Learn more about Adaptive Crawling →](adaptive-crawling.md)
+
+---
+
+## 8. Multi-URL Concurrency (Preview)
 
 If you need to crawl multiple URLs in **parallel**, you can use `arun_many()`. By default, Crawl4AI employs a **MemoryAdaptiveDispatcher**, automatically adjusting concurrency based on system resources. Here’s a quick glimpse:
 

docs/md_v2/extraction/llm-strategies.md

@@ -218,7 +218,7 @@ import json
 import asyncio
 from typing import List
 from pydantic import BaseModel, Field
-from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode
+from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode, LLMConfig
 from crawl4ai import LLMExtractionStrategy
 
 class Entity(BaseModel):
@@ -238,8 +238,8 @@ class KnowledgeGraph(BaseModel):
 async def main():
     # LLM extraction strategy
     llm_strat = LLMExtractionStrategy(
-        llmConfig = LlmConfig(provider="openai/gpt-4", api_token=os.getenv('OPENAI_API_KEY')),
-        schema=KnowledgeGraph.schema_json(),
+        llmConfig = LLMConfig(provider="openai/gpt-4", api_token=os.getenv('OPENAI_API_KEY')),
+        schema=KnowledgeGraph.model_json_schema(),
         extraction_type="schema",
         instruction="Extract entities and relationships from the content. Return valid JSON.",
         chunk_token_threshold=1400,
@@ -258,6 +258,10 @@ async def main():
         url = "https://www.nbcnews.com/business"
         result = await crawler.arun(url=url, config=crawl_config)
 
+        print("--- LLM RAW RESPONSE ---")
+        print(result.extracted_content)
+        print("--- END LLM RAW RESPONSE ---")
+
         if result.success:
             with open("kb_result.json", "w", encoding="utf-8") as f:
                 f.write(result.extracted_content)

docs/md_v2/index.md

@@ -41,6 +41,17 @@
            alt="License"/>
     </a>
   </p>
+  <p align="center">
+    <a href="https://x.com/crawl4ai">
+      <img src="https://img.shields.io/badge/Follow%20on%20X-000000?style=for-the-badge&logo=x&logoColor=white" alt="Follow on X" />
+    </a>
+    <a href="https://www.linkedin.com/company/crawl4ai">
+      <img src="https://img.shields.io/badge/Follow%20on%20LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white" alt="Follow on LinkedIn" />
+    </a>
+    <a href="https://discord.gg/jP8KfhDhyN">
+      <img src="https://img.shields.io/badge/Join%20our%20Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Join our Discord" />
+    </a>
+  </p>
   
 </div>
 
@@ -48,6 +59,12 @@ Crawl4AI is the #1 trending GitHub repository, actively maintained by a vibrant
 
 > **Note**: If you're looking for the old documentation, you can access it [here](https://old.docs.crawl4ai.com).
 
+## 🎯 New: Adaptive Web Crawling
+
+Crawl4AI now features intelligent adaptive crawling that knows when to stop! Using advanced information foraging algorithms, it determines when sufficient information has been gathered to answer your query.
+
+[Learn more about Adaptive Crawling →](core/adaptive-crawling.md)
+
 
 ## Quick Start
 

mkdocs.yml

@@ -48,6 +48,7 @@ nav:
     - "Identity Based Crawling": "advanced/identity-based-crawling.md"
     - "SSL Certificate": "advanced/ssl-certificate.md"
     - "Network & Console Capture": "advanced/network-console-capture.md"
+    - "PDF Parsing": "advanced/pdf-parsing.md"
   - Extraction:
     - "LLM-Free Strategies": "extraction/no-llm-strategies.md"
     - "LLM Strategies": "extraction/llm-strategies.md"

pyproject.toml

@@ -17,7 +17,7 @@ dependencies = [
     "lxml~=5.3",
     "litellm>=1.53.1",
     "numpy>=1.26.0,<3",
-    "pillow~=10.4",
+    "pillow>=10.4",
     "playwright>=1.49.0",
     "python-dotenv~=1.0",
     "requests~=2.26",
@@ -32,7 +32,6 @@ dependencies = [
     "psutil>=6.1.1",
     "nltk>=3.9.1",
     "playwright",
-    "aiofiles",
     "rich>=13.9.4",
     "cssselect>=1.2.0",
     "httpx>=0.27.2",
@@ -44,7 +43,10 @@ dependencies = [
     "aiohttp>=3.11.11",
     "brotli>=1.1.0",
     "humanize>=4.10.0",
-    "lark>=1.2.2"
+    "lark>=1.2.2",
+    "sentence-transformers>=2.2.0",
+    "alphashape>=1.3.1",
+    "shapely>=2.0.0"
 ]
 classifiers = [
     "Development Status :: 4 - Beta",

requirements.txt

@@ -4,7 +4,7 @@ aiosqlite~=0.20
 lxml~=5.3
 litellm>=1.53.1
 numpy>=1.26.0,<3
-pillow~=10.4
+pillow>=10.4
 playwright>=1.49.0
 python-dotenv~=1.0
 requests~=2.26
@@ -24,3 +24,10 @@ cssselect>=1.2.0
 chardet>=5.2.0
 brotli>=1.1.0
 httpx[http2]>=0.27.2
+sentence-transformers>=2.2.0
+alphashape>=1.3.1
+shapely>=2.0.0
+
+fake-useragent>=2.2.0
+pdf2image>=1.17.0
+PyPDF2>=3.0.1

tests/adaptive/compare_performance.py

@@ -0,0 +1,98 @@
+"""
+Compare performance before and after optimizations
+"""
+
+def read_baseline():
+    """Read baseline performance metrics"""
+    with open('performance_baseline.txt', 'r') as f:
+        content = f.read()
+    
+    # Extract key metrics
+    metrics = {}
+    lines = content.split('\n')
+    for i, line in enumerate(lines):
+        if 'Total Time:' in line:
+            metrics['total_time'] = float(line.split(':')[1].strip().split()[0])
+        elif 'Memory Used:' in line:
+            metrics['memory_mb'] = float(line.split(':')[1].strip().split()[0])
+        elif 'validate_coverage:' in line and i+1 < len(lines) and 'Avg Time:' in lines[i+2]:
+            metrics['validate_coverage_ms'] = float(lines[i+2].split(':')[1].strip().split()[0])
+        elif 'select_links:' in line and i+1 < len(lines) and 'Avg Time:' in lines[i+2]:
+            metrics['select_links_ms'] = float(lines[i+2].split(':')[1].strip().split()[0])
+        elif 'calculate_confidence:' in line and i+1 < len(lines) and 'Avg Time:' in lines[i+2]:
+            metrics['calculate_confidence_ms'] = float(lines[i+2].split(':')[1].strip().split()[0])
+            
+    return metrics
+
+
+def print_comparison(before_metrics, after_metrics):
+    """Print performance comparison"""
+    print("\n" + "="*80)
+    print("PERFORMANCE COMPARISON: BEFORE vs AFTER OPTIMIZATIONS")
+    print("="*80)
+    
+    # Total time
+    time_improvement = (before_metrics['total_time'] - after_metrics['total_time']) / before_metrics['total_time'] * 100
+    print(f"\n📊 Total Time:")
+    print(f"   Before: {before_metrics['total_time']:.2f} seconds")
+    print(f"   After:  {after_metrics['total_time']:.2f} seconds")
+    print(f"   Improvement: {time_improvement:.1f}% faster ✅" if time_improvement > 0 else f"   Slower: {-time_improvement:.1f}% ❌")
+    
+    # Memory
+    mem_improvement = (before_metrics['memory_mb'] - after_metrics['memory_mb']) / before_metrics['memory_mb'] * 100
+    print(f"\n💾 Memory Usage:")
+    print(f"   Before: {before_metrics['memory_mb']:.2f} MB")
+    print(f"   After:  {after_metrics['memory_mb']:.2f} MB")
+    print(f"   Improvement: {mem_improvement:.1f}% less memory ✅" if mem_improvement > 0 else f"   More memory: {-mem_improvement:.1f}% ❌")
+    
+    # Key operations
+    print(f"\n⚡ Key Operations:")
+    
+    # Validate coverage
+    if 'validate_coverage_ms' in before_metrics and 'validate_coverage_ms' in after_metrics:
+        val_improvement = (before_metrics['validate_coverage_ms'] - after_metrics['validate_coverage_ms']) / before_metrics['validate_coverage_ms'] * 100
+        print(f"\n   validate_coverage:")
+        print(f"     Before: {before_metrics['validate_coverage_ms']:.1f} ms")
+        print(f"     After:  {after_metrics['validate_coverage_ms']:.1f} ms")
+        print(f"     Improvement: {val_improvement:.1f}% faster ✅" if val_improvement > 0 else f"     Slower: {-val_improvement:.1f}% ❌")
+    
+    # Select links
+    if 'select_links_ms' in before_metrics and 'select_links_ms' in after_metrics:
+        sel_improvement = (before_metrics['select_links_ms'] - after_metrics['select_links_ms']) / before_metrics['select_links_ms'] * 100
+        print(f"\n   select_links:")
+        print(f"     Before: {before_metrics['select_links_ms']:.1f} ms")
+        print(f"     After:  {after_metrics['select_links_ms']:.1f} ms")
+        print(f"     Improvement: {sel_improvement:.1f}% faster ✅" if sel_improvement > 0 else f"     Slower: {-sel_improvement:.1f}% ❌")
+    
+    # Calculate confidence
+    if 'calculate_confidence_ms' in before_metrics and 'calculate_confidence_ms' in after_metrics:
+        calc_improvement = (before_metrics['calculate_confidence_ms'] - after_metrics['calculate_confidence_ms']) / before_metrics['calculate_confidence_ms'] * 100
+        print(f"\n   calculate_confidence:")
+        print(f"     Before: {before_metrics['calculate_confidence_ms']:.1f} ms")
+        print(f"     After:  {after_metrics['calculate_confidence_ms']:.1f} ms")
+        print(f"     Improvement: {calc_improvement:.1f}% faster ✅" if calc_improvement > 0 else f"     Slower: {-calc_improvement:.1f}% ❌")
+    
+    print("\n" + "="*80)
+    
+    # Overall assessment
+    if time_improvement > 50:
+        print("🎉 EXCELLENT OPTIMIZATION! More than 50% performance improvement!")
+    elif time_improvement > 30:
+        print("✅ GOOD OPTIMIZATION! Significant performance improvement!")
+    elif time_improvement > 10:
+        print("👍 DECENT OPTIMIZATION! Noticeable performance improvement!")
+    else:
+        print("🤔 MINIMAL IMPROVEMENT. Further optimization may be needed.")
+    
+    print("="*80)
+
+
+if __name__ == "__main__":
+    # Example usage - you'll run this after implementing optimizations
+    baseline = read_baseline()
+    print("Baseline metrics loaded:")
+    for k, v in baseline.items():
+        print(f"  {k}: {v}")
+    
+    print("\n⚠️  Run the performance test again after optimizations to compare!")
+    print("Then update this script with the new metrics to see the comparison.")

tests/adaptive/test_adaptive_crawler.py

@@ -0,0 +1,293 @@
+"""
+Test and demo script for Adaptive Crawler
+
+This script demonstrates the progressive crawling functionality
+with various configurations and use cases.
+"""
+
+import asyncio
+import json
+from pathlib import Path
+import time
+from typing import Dict, List
+from rich.console import Console
+from rich.table import Table
+from rich.progress import Progress
+from rich import print as rprint
+
+# Add parent directory to path for imports
+import sys
+sys.path.append(str(Path(__file__).parent.parent))
+
+from crawl4ai import (
+    AsyncWebCrawler,
+    AdaptiveCrawler,
+    AdaptiveConfig,
+    CrawlState
+)
+
+
+console = Console()
+
+
+
+
+def print_relevant_content(crawler: AdaptiveCrawler, top_k: int = 3):
+    """Print most relevant content found"""
+    relevant = crawler.get_relevant_content(top_k=top_k)
+    
+    if not relevant:
+        console.print("[yellow]No relevant content found yet.[/yellow]")
+        return
+    
+    console.print(f"\n[bold cyan]Top {len(relevant)} Most Relevant Pages:[/bold cyan]")
+    for i, doc in enumerate(relevant, 1):
+        console.print(f"\n[green]{i}. {doc['url']}[/green]")
+        console.print(f"   Score: {doc['score']:.2f}")
+        # Show snippet
+        content = doc['content'] or ""
+        snippet = content[:200].replace('\n', ' ') + "..." if len(content) > 200 else content
+        console.print(f"   [dim]{snippet}[/dim]")
+
+
+async def test_basic_progressive_crawl():
+    """Test basic progressive crawling functionality"""
+    console.print("\n[bold yellow]Test 1: Basic Progressive Crawl[/bold yellow]")
+    console.print("Testing on Python documentation with query about async/await")
+    
+    config = AdaptiveConfig(
+        confidence_threshold=0.7,
+        max_pages=10,
+        top_k_links=2,
+        min_gain_threshold=0.1
+    )
+    
+    # Create crawler
+    async with AsyncWebCrawler() as crawler:
+        prog_crawler = AdaptiveCrawler(
+            crawler=crawler,
+            config=config
+        )
+        
+        # Start progressive crawl
+        start_time = time.time()
+        state = await prog_crawler.digest(
+            start_url="https://docs.python.org/3/library/asyncio.html",
+            query="async await context managers"
+        )
+        elapsed = time.time() - start_time
+        
+        # Print results
+        prog_crawler.print_stats(detailed=False)
+        prog_crawler.print_stats(detailed=True)
+        print_relevant_content(prog_crawler)
+        
+        console.print(f"\n[green]Crawl completed in {elapsed:.2f} seconds[/green]")
+        console.print(f"Final confidence: {prog_crawler.confidence:.2%}")
+        console.print(f"URLs crawled: {list(state.crawled_urls)[:5]}...")  # Show first 5
+        
+        # Test export functionality
+        export_path = "knowledge_base_export.jsonl"
+        prog_crawler.export_knowledge_base(export_path)
+        console.print(f"[green]Knowledge base exported to {export_path}[/green]")
+        
+        # Clean up
+        Path(export_path).unlink(missing_ok=True)
+
+
+async def test_with_persistence():
+    """Test state persistence and resumption"""
+    console.print("\n[bold yellow]Test 2: Persistence and Resumption[/bold yellow]")
+    console.print("Testing state save/load functionality")
+    
+    state_path = "test_crawl_state.json"
+    
+    config = AdaptiveConfig(
+        confidence_threshold=0.6,
+        max_pages=5,
+        top_k_links=2,
+        save_state=True,
+        state_path=state_path
+    )
+    
+    # First crawl - partial
+    async with AsyncWebCrawler() as crawler:
+        prog_crawler = AdaptiveCrawler(
+            crawler=crawler,
+            config=config
+        )
+        
+        state1 = await prog_crawler.digest(
+            start_url="https://httpbin.org",
+            query="http headers response"
+        )
+        
+        console.print(f"[cyan]First crawl: {len(state1.crawled_urls)} pages[/cyan]")
+        
+    # Resume crawl
+    config.max_pages = 10  # Increase limit
+    
+    async with AsyncWebCrawler() as crawler:
+        prog_crawler = AdaptiveCrawler(
+            crawler=crawler,
+            config=config
+        )
+        
+        state2 = await prog_crawler.digest(
+            start_url="https://httpbin.org",
+            query="http headers response",
+            resume_from=state_path
+        )
+        
+        console.print(f"[green]Resumed crawl: {len(state2.crawled_urls)} total pages[/green]")
+        
+    # Clean up
+    Path(state_path).unlink(missing_ok=True)
+
+
+async def test_different_domains():
+    """Test on different types of websites"""
+    console.print("\n[bold yellow]Test 3: Different Domain Types[/bold yellow]")
+    
+    test_cases = [
+        {
+            "name": "Documentation Site",
+            "url": "https://docs.python.org/3/",
+            "query": "decorators and context managers"
+        },
+        {
+            "name": "API Documentation",  
+            "url": "https://httpbin.org",
+            "query": "http authentication headers"
+        }
+    ]
+    
+    for test in test_cases:
+        console.print(f"\n[cyan]Testing: {test['name']}[/cyan]")
+        console.print(f"URL: {test['url']}")
+        console.print(f"Query: {test['query']}")
+        
+        config = AdaptiveConfig(
+            confidence_threshold=0.6,
+            max_pages=5,
+            top_k_links=2
+        )
+        
+        async with AsyncWebCrawler() as crawler:
+            prog_crawler = AdaptiveCrawler(
+                crawler=crawler,
+                config=config
+            )
+            
+            start_time = time.time()
+            state = await prog_crawler.digest(
+                start_url=test['url'],
+                query=test['query']
+            )
+            elapsed = time.time() - start_time
+            
+            # Summary using print_stats
+            prog_crawler.print_stats(detailed=False)
+
+
+async def test_stopping_criteria():
+    """Test different stopping criteria"""
+    console.print("\n[bold yellow]Test 4: Stopping Criteria[/bold yellow]")
+    
+    # Test 1: High confidence threshold
+    console.print("\n[cyan]4.1 High confidence threshold (0.9)[/cyan]")
+    config = AdaptiveConfig(
+        confidence_threshold=0.9,  # Very high
+        max_pages=20,
+        top_k_links=3
+    )
+    
+    async with AsyncWebCrawler() as crawler:
+        prog_crawler = AdaptiveCrawler(crawler=crawler, config=config)
+        state = await prog_crawler.digest(
+            start_url="https://docs.python.org/3/library/",
+            query="python standard library"
+        )
+        
+        console.print(f"Pages needed for 90% confidence: {len(state.crawled_urls)}")
+        prog_crawler.print_stats(detailed=False)
+    
+    # Test 2: Page limit
+    console.print("\n[cyan]4.2 Page limit (3 pages max)[/cyan]")
+    config = AdaptiveConfig(
+        confidence_threshold=0.9,
+        max_pages=3,  # Very low limit
+        top_k_links=2
+    )
+    
+    async with AsyncWebCrawler() as crawler:
+        prog_crawler = AdaptiveCrawler(crawler=crawler, config=config)
+        state = await prog_crawler.digest(
+            start_url="https://docs.python.org/3/library/",
+            query="python standard library modules"
+        )
+        
+        console.print(f"Stopped by: {'Page limit' if len(state.crawled_urls) >= 3 else 'Other'}")
+        prog_crawler.print_stats(detailed=False)
+
+
+async def test_crawl_patterns():
+    """Analyze crawl patterns and link selection"""
+    console.print("\n[bold yellow]Test 5: Crawl Pattern Analysis[/bold yellow]")
+    
+    config = AdaptiveConfig(
+        confidence_threshold=0.7,
+        max_pages=8,
+        top_k_links=2,
+        min_gain_threshold=0.05
+    )
+    
+    async with AsyncWebCrawler() as crawler:
+        prog_crawler = AdaptiveCrawler(crawler=crawler, config=config)
+        
+        # Track crawl progress
+        console.print("\n[cyan]Crawl Progress:[/cyan]")
+        
+        state = await prog_crawler.digest(
+            start_url="https://httpbin.org",
+            query="http methods post get"
+        )
+        
+        # Show crawl order
+        console.print("\n[green]Crawl Order:[/green]")
+        for i, url in enumerate(state.crawl_order, 1):
+            console.print(f"{i}. {url}")
+        
+        # Show new terms discovered per page
+        console.print("\n[green]New Terms Discovered:[/green]")
+        for i, new_terms in enumerate(state.new_terms_history, 1):
+            console.print(f"Page {i}: {new_terms} new terms")
+        
+        # Final metrics
+        console.print(f"\n[yellow]Saturation reached: {state.metrics.get('saturation', 0):.2%}[/yellow]")
+
+
+async def main():
+    """Run all tests"""
+    console.print("[bold magenta]Adaptive Crawler Test Suite[/bold magenta]")
+    console.print("=" * 50)
+    
+    try:
+        # Run tests
+        await test_basic_progressive_crawl()
+        # await test_with_persistence()
+        # await test_different_domains()
+        # await test_stopping_criteria()
+        # await test_crawl_patterns()
+        
+        console.print("\n[bold green]✅ All tests completed successfully![/bold green]")
+        
+    except Exception as e:
+        console.print(f"\n[bold red]❌ Test failed with error: {e}[/bold red]")
+        import traceback
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    # Run the test suite
+    asyncio.run(main())

tests/adaptive/test_confidence_debug.py

@@ -0,0 +1,182 @@
+"""
+Test script for debugging confidence calculation in adaptive crawler
+Focus: Testing why confidence decreases when crawling relevant URLs
+"""
+
+import asyncio
+import sys
+from pathlib import Path
+from typing import List, Dict
+import math
+
+# Add parent directory to path for imports
+sys.path.append(str(Path(__file__).parent.parent))
+
+from crawl4ai import AsyncWebCrawler
+from crawl4ai.adaptive_crawler import CrawlState, StatisticalStrategy
+from crawl4ai.models import CrawlResult
+
+
+class ConfidenceTestHarness:
+    """Test harness for analyzing confidence calculation"""
+    
+    def __init__(self):
+        self.strategy = StatisticalStrategy()
+        self.test_urls = [
+            'https://docs.python.org/3/library/asyncio.html',
+            'https://docs.python.org/3/library/asyncio-runner.html', 
+            'https://docs.python.org/3/library/asyncio-api-index.html',
+            'https://docs.python.org/3/library/contextvars.html',
+            'https://docs.python.org/3/library/asyncio-stream.html'
+        ]
+        self.query = "async await context manager"
+        
+    async def test_confidence_progression(self):
+        """Test confidence calculation as we crawl each URL"""
+        print(f"Testing confidence for query: '{self.query}'")
+        print("=" * 80)
+        
+        # Initialize state
+        state = CrawlState(query=self.query)
+        
+        # Create crawler
+        async with AsyncWebCrawler() as crawler:
+            for i, url in enumerate(self.test_urls, 1):
+                print(f"\n{i}. Crawling: {url}")
+                print("-" * 80)
+                
+                # Crawl the URL
+                result = await crawler.arun(url=url)
+                
+                # Extract markdown content
+                if hasattr(result, '_results') and result._results:
+                    result = result._results[0]
+                
+                # Create a mock CrawlResult with markdown
+                mock_result = type('CrawlResult', (), {
+                    'markdown': type('Markdown', (), {
+                        'raw_markdown': result.markdown.raw_markdown if hasattr(result, 'markdown') else ''
+                    })(),
+                    'url': url
+                })()
+                
+                # Update state
+                state.knowledge_base.append(mock_result)
+                await self.strategy.update_state(state, [mock_result])
+                
+                # Calculate metrics
+                confidence = await self.strategy.calculate_confidence(state)
+                
+                # Get individual components
+                coverage = state.metrics.get('coverage', 0)
+                consistency = state.metrics.get('consistency', 0)
+                saturation = state.metrics.get('saturation', 0)
+                
+                # Analyze term frequencies
+                query_terms = self.strategy._tokenize(self.query.lower())
+                term_stats = {}
+                for term in query_terms:
+                    term_stats[term] = {
+                        'tf': state.term_frequencies.get(term, 0),
+                        'df': state.document_frequencies.get(term, 0)
+                    }
+                
+                # Print detailed results
+                print(f"State after crawl {i}:")
+                print(f"  Total documents: {state.total_documents}")
+                print(f"  Unique terms: {len(state.term_frequencies)}")
+                print(f"  New terms added: {state.new_terms_history[-1] if state.new_terms_history else 0}")
+                
+                print(f"\nQuery term statistics:")
+                for term, stats in term_stats.items():
+                    print(f"  '{term}': tf={stats['tf']}, df={stats['df']}")
+                
+                print(f"\nMetrics:")
+                print(f"  Coverage: {coverage:.3f}")
+                print(f"  Consistency: {consistency:.3f}")
+                print(f"  Saturation: {saturation:.3f}")
+                print(f"  → Confidence: {confidence:.3f}")
+                
+                # Show coverage calculation details
+                print(f"\nCoverage calculation details:")
+                self._debug_coverage_calculation(state, query_terms)
+                
+                # Alert if confidence decreased
+                if i > 1 and confidence < state.metrics.get('prev_confidence', 0):
+                    print(f"\n⚠️  WARNING: Confidence decreased from {state.metrics.get('prev_confidence', 0):.3f} to {confidence:.3f}")
+                
+                state.metrics['prev_confidence'] = confidence
+    
+    def _debug_coverage_calculation(self, state: CrawlState, query_terms: List[str]):
+        """Debug coverage calculation step by step"""
+        coverage_score = 0.0
+        max_possible_score = 0.0
+        
+        for term in query_terms:
+            tf = state.term_frequencies.get(term, 0)
+            df = state.document_frequencies.get(term, 0)
+            
+            if df > 0:
+                idf = math.log((state.total_documents - df + 0.5) / (df + 0.5) + 1)
+                doc_coverage = df / state.total_documents
+                tf_boost = min(tf / df, 3.0)
+                term_score = doc_coverage * idf * (1 + 0.1 * math.log1p(tf_boost))
+                
+                print(f"    '{term}': doc_cov={doc_coverage:.2f}, idf={idf:.2f}, boost={1 + 0.1 * math.log1p(tf_boost):.2f} → score={term_score:.3f}")
+                coverage_score += term_score
+            else:
+                print(f"    '{term}': not found → score=0.000")
+            
+            max_possible_score += 1.0 * 1.0 * 1.1
+        
+        print(f"    Total: {coverage_score:.3f} / {max_possible_score:.3f} = {coverage_score/max_possible_score if max_possible_score > 0 else 0:.3f}")
+        
+        # New coverage calculation
+        print(f"\n  NEW Coverage calculation (without IDF):")
+        new_coverage = self._calculate_coverage_new(state, query_terms)
+        print(f"    → New Coverage: {new_coverage:.3f}")
+    
+    def _calculate_coverage_new(self, state: CrawlState, query_terms: List[str]) -> float:
+        """New coverage calculation without IDF"""
+        if not query_terms or state.total_documents == 0:
+            return 0.0
+            
+        term_scores = []
+        max_tf = max(state.term_frequencies.values()) if state.term_frequencies else 1
+        
+        for term in query_terms:
+            tf = state.term_frequencies.get(term, 0)
+            df = state.document_frequencies.get(term, 0)
+            
+            if df > 0:
+                # Document coverage: what fraction of docs contain this term
+                doc_coverage = df / state.total_documents
+                
+                # Frequency signal: normalized log frequency
+                freq_signal = math.log(1 + tf) / math.log(1 + max_tf) if max_tf > 0 else 0
+                
+                # Combined score: document coverage with frequency boost
+                term_score = doc_coverage * (1 + 0.5 * freq_signal)
+                
+                print(f"    '{term}': doc_cov={doc_coverage:.2f}, freq_signal={freq_signal:.2f} → score={term_score:.3f}")
+                term_scores.append(term_score)
+            else:
+                print(f"    '{term}': not found → score=0.000")
+                term_scores.append(0.0)
+        
+        # Average across all query terms
+        coverage = sum(term_scores) / len(term_scores)
+        return coverage
+
+
+async def main():
+    """Run the confidence test"""
+    tester = ConfidenceTestHarness()
+    await tester.test_confidence_progression()
+    
+    print("\n" + "=" * 80)
+    print("Test complete!")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

tests/adaptive/test_embedding_performance.py

@@ -0,0 +1,254 @@
+"""
+Performance test for Embedding Strategy optimizations
+Measures time and memory usage before and after optimizations
+"""
+
+import asyncio
+import time
+import tracemalloc
+import numpy as np
+from pathlib import Path
+import sys
+import os
+
+# Add parent directory to path for imports
+sys.path.append(str(Path(__file__).parent.parent.parent))
+
+from crawl4ai import AsyncWebCrawler, AdaptiveCrawler, AdaptiveConfig
+from crawl4ai.adaptive_crawler import EmbeddingStrategy, CrawlState
+from crawl4ai.models import CrawlResult
+
+
+class PerformanceMetrics:
+    def __init__(self):
+        self.start_time = 0
+        self.end_time = 0
+        self.start_memory = 0
+        self.peak_memory = 0
+        self.operation_times = {}
+        
+    def start(self):
+        tracemalloc.start()
+        self.start_time = time.perf_counter()
+        self.start_memory = tracemalloc.get_traced_memory()[0]
+        
+    def end(self):
+        self.end_time = time.perf_counter()
+        current, peak = tracemalloc.get_traced_memory()
+        self.peak_memory = peak
+        tracemalloc.stop()
+        
+    def record_operation(self, name: str, duration: float):
+        if name not in self.operation_times:
+            self.operation_times[name] = []
+        self.operation_times[name].append(duration)
+        
+    @property
+    def total_time(self):
+        return self.end_time - self.start_time
+        
+    @property
+    def memory_used_mb(self):
+        return (self.peak_memory - self.start_memory) / 1024 / 1024
+        
+    def print_summary(self, label: str):
+        print(f"\n{'='*60}")
+        print(f"Performance Summary: {label}")
+        print(f"{'='*60}")
+        print(f"Total Time: {self.total_time:.3f} seconds")
+        print(f"Memory Used: {self.memory_used_mb:.2f} MB")
+        
+        if self.operation_times:
+            print("\nOperation Breakdown:")
+            for op, times in self.operation_times.items():
+                avg_time = sum(times) / len(times)
+                total_time = sum(times)
+                print(f"  {op}:")
+                print(f"    - Calls: {len(times)}")
+                print(f"    - Avg Time: {avg_time*1000:.2f} ms")
+                print(f"    - Total Time: {total_time:.3f} s")
+
+
+async def create_mock_crawl_results(n: int) -> list:
+    """Create mock crawl results for testing"""
+    results = []
+    for i in range(n):
+        class MockMarkdown:
+            def __init__(self, content):
+                self.raw_markdown = content
+                
+        class MockResult:
+            def __init__(self, url, content):
+                self.url = url
+                self.markdown = MockMarkdown(content)
+                self.success = True
+                
+        content = f"This is test content {i} about async await coroutines event loops. " * 50
+        result = MockResult(f"https://example.com/page{i}", content)
+        results.append(result)
+    return results
+
+
+async def test_embedding_performance():
+    """Test the performance of embedding strategy operations"""
+    
+    # Configuration
+    n_kb_docs = 30  # Number of documents in knowledge base
+    n_queries = 10  # Number of query variations
+    n_links = 50   # Number of candidate links
+    n_iterations = 5  # Number of calculation iterations
+    
+    print(f"\nTest Configuration:")
+    print(f"- Knowledge Base Documents: {n_kb_docs}")
+    print(f"- Query Variations: {n_queries}")
+    print(f"- Candidate Links: {n_links}")
+    print(f"- Iterations: {n_iterations}")
+    
+    # Create embedding strategy
+    config = AdaptiveConfig(
+        strategy="embedding",
+        max_pages=50,
+        n_query_variations=n_queries,
+        embedding_model="sentence-transformers/all-MiniLM-L6-v2"  # 384 dimensions
+    )
+    
+    # Set up API key if available
+    if os.getenv('OPENAI_API_KEY'):
+        config.embedding_llm_config = {
+            'provider': 'openai/text-embedding-3-small',
+            'api_token': os.getenv('OPENAI_API_KEY'),
+            'embedding_model': 'text-embedding-3-small'
+        }
+    else:
+        config.embedding_llm_config = {
+            'provider': 'openai/gpt-4o-mini',
+            'api_token': 'dummy-key'
+        }
+    
+    strategy = EmbeddingStrategy(
+        embedding_model=config.embedding_model,
+        llm_config=config.embedding_llm_config
+    )
+    strategy.config = config
+    
+    # Initialize state
+    state = CrawlState()
+    state.query = "async await coroutines event loops tasks"
+    
+    # Start performance monitoring
+    metrics = PerformanceMetrics()
+    metrics.start()
+    
+    # 1. Generate query embeddings
+    print("\n1. Generating query embeddings...")
+    start = time.perf_counter()
+    query_embeddings, expanded_queries = await strategy.map_query_semantic_space(
+        state.query, 
+        config.n_query_variations
+    )
+    state.query_embeddings = query_embeddings
+    state.expanded_queries = expanded_queries
+    metrics.record_operation("query_embedding", time.perf_counter() - start)
+    print(f"   Generated {len(query_embeddings)} query embeddings")
+    
+    # 2. Build knowledge base incrementally
+    print("\n2. Building knowledge base...")
+    mock_results = await create_mock_crawl_results(n_kb_docs)
+    
+    for i in range(0, n_kb_docs, 5):  # Add 5 documents at a time
+        batch = mock_results[i:i+5]
+        start = time.perf_counter()
+        await strategy.update_state(state, batch)
+        metrics.record_operation("update_state", time.perf_counter() - start)
+        state.knowledge_base.extend(batch)
+    
+    print(f"   Knowledge base has {len(state.kb_embeddings)} documents")
+    
+    # 3. Test repeated confidence calculations
+    print(f"\n3. Testing {n_iterations} confidence calculations...")
+    for i in range(n_iterations):
+        start = time.perf_counter()
+        confidence = await strategy.calculate_confidence(state)
+        metrics.record_operation("calculate_confidence", time.perf_counter() - start)
+        print(f"   Iteration {i+1}: {confidence:.3f} ({(time.perf_counter() - start)*1000:.1f} ms)")
+    
+    # 4. Test coverage gap calculations
+    print(f"\n4. Testing coverage gap calculations...")
+    for i in range(n_iterations):
+        start = time.perf_counter()
+        gaps = strategy.find_coverage_gaps(state.kb_embeddings, state.query_embeddings)
+        metrics.record_operation("find_coverage_gaps", time.perf_counter() - start)
+        print(f"   Iteration {i+1}: {len(gaps)} gaps ({(time.perf_counter() - start)*1000:.1f} ms)")
+    
+    # 5. Test validation
+    print(f"\n5. Testing validation coverage...")
+    for i in range(n_iterations):
+        start = time.perf_counter()
+        val_score = await strategy.validate_coverage(state)
+        metrics.record_operation("validate_coverage", time.perf_counter() - start)
+        print(f"   Iteration {i+1}: {val_score:.3f} ({(time.perf_counter() - start)*1000:.1f} ms)")
+    
+    # 6. Create mock links for ranking
+    from crawl4ai.models import Link
+    mock_links = []
+    for i in range(n_links):
+        link = Link(
+            href=f"https://example.com/new{i}",
+            text=f"Link about async programming {i}",
+            title=f"Async Guide {i}"
+        )
+        mock_links.append(link)
+    
+    # 7. Test link selection
+    print(f"\n6. Testing link selection with {n_links} candidates...")
+    start = time.perf_counter()
+    scored_links = await strategy.select_links_for_expansion(
+        mock_links,
+        gaps,
+        state.kb_embeddings
+    )
+    metrics.record_operation("select_links", time.perf_counter() - start)
+    print(f"   Scored {len(scored_links)} links in {(time.perf_counter() - start)*1000:.1f} ms")
+    
+    # End monitoring
+    metrics.end()
+    
+    return metrics
+
+
+async def main():
+    """Run performance tests before and after optimizations"""
+    
+    print("="*80)
+    print("EMBEDDING STRATEGY PERFORMANCE TEST")
+    print("="*80)
+    
+    # Test current implementation
+    print("\n📊 Testing CURRENT Implementation...")
+    metrics_before = await test_embedding_performance()
+    metrics_before.print_summary("BEFORE Optimizations")
+    
+    # Store key metrics for comparison
+    total_time_before = metrics_before.total_time
+    memory_before = metrics_before.memory_used_mb
+    
+    # Calculate specific operation costs
+    calc_conf_avg = sum(metrics_before.operation_times.get("calculate_confidence", [])) / len(metrics_before.operation_times.get("calculate_confidence", [1]))
+    find_gaps_avg = sum(metrics_before.operation_times.get("find_coverage_gaps", [])) / len(metrics_before.operation_times.get("find_coverage_gaps", [1]))
+    validate_avg = sum(metrics_before.operation_times.get("validate_coverage", [])) / len(metrics_before.operation_times.get("validate_coverage", [1]))
+    
+    print(f"\n🔍 Key Bottlenecks Identified:")
+    print(f"   - calculate_confidence: {calc_conf_avg*1000:.1f} ms per call")
+    print(f"   - find_coverage_gaps: {find_gaps_avg*1000:.1f} ms per call")
+    print(f"   - validate_coverage: {validate_avg*1000:.1f} ms per call")
+    
+    print("\n" + "="*80)
+    print("EXPECTED IMPROVEMENTS AFTER OPTIMIZATION:")
+    print("- Distance calculations: 80-90% faster (vectorization)")
+    print("- Memory usage: 20-30% reduction (deduplication)")
+    print("- Overall performance: 60-70% improvement")
+    print("="*80)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

tests/adaptive/test_embedding_strategy.py

@@ -0,0 +1,634 @@
+"""
+Test and demo script for Embedding-based Adaptive Crawler
+
+This script demonstrates the embedding-based adaptive crawling
+with semantic space coverage and gap-driven expansion.
+"""
+
+import asyncio
+import os
+from pathlib import Path
+import time
+from rich.console import Console
+from rich import print as rprint
+import sys
+
+# Add parent directory to path for imports
+sys.path.append(str(Path(__file__).parent.parent.parent))
+
+from crawl4ai import (
+    AsyncWebCrawler,
+    AdaptiveCrawler,
+    AdaptiveConfig,
+    CrawlState
+)
+
+console = Console()
+
+
+async def test_basic_embedding_crawl():
+    """Test basic embedding-based adaptive crawling"""
+    console.print("\n[bold yellow]Test 1: Basic Embedding-based Crawl[/bold yellow]")
+    console.print("Testing semantic space coverage with query expansion")
+    
+    # Configure with embedding strategy
+    config = AdaptiveConfig(
+        strategy="embedding",
+        confidence_threshold=0.7,  # Not used for stopping in embedding strategy
+        min_gain_threshold=0.01,
+        max_pages=15,
+        top_k_links=3,
+        n_query_variations=8,
+        embedding_model="sentence-transformers/all-MiniLM-L6-v2"  # Fast, good quality
+    )
+    
+    # For query expansion, we need an LLM config
+    llm_config = {
+        'provider': 'openai/gpt-4o-mini',
+        'api_token': os.getenv('OPENAI_API_KEY')
+    }
+    
+    if not llm_config['api_token']:
+        console.print("[red]Warning: OPENAI_API_KEY not set. Using mock data for demo.[/red]")
+        # Continue with mock for demo purposes
+    
+    config.embedding_llm_config = llm_config
+    
+    # Create crawler
+    async with AsyncWebCrawler() as crawler:
+        prog_crawler = AdaptiveCrawler(
+            crawler=crawler,
+            config=config
+        )
+        
+        # Start adaptive crawl
+        start_time = time.time()
+        console.print("\n[cyan]Starting semantic adaptive crawl...[/cyan]")
+        
+        state = await prog_crawler.digest(
+            start_url="https://docs.python.org/3/library/asyncio.html",
+            query="async await coroutines event loops"
+        )
+        elapsed = time.time() - start_time
+        
+        # Print results
+        console.print(f"\n[green]Crawl completed in {elapsed:.2f} seconds[/green]")
+        prog_crawler.print_stats(detailed=False)
+        
+        # Show semantic coverage details
+        console.print("\n[bold cyan]Semantic Coverage Details:[/bold cyan]")
+        if state.expanded_queries:
+            console.print(f"Query expanded to {len(state.expanded_queries)} variations")
+            console.print("Sample variations:")
+            for i, q in enumerate(state.expanded_queries[:3], 1):
+                console.print(f"  {i}. {q}")
+        
+        if state.semantic_gaps:
+            console.print(f"\nSemantic gaps identified: {len(state.semantic_gaps)}")
+        
+        console.print(f"\nFinal confidence: {prog_crawler.confidence:.2%}")
+        console.print(f"Is Sufficient: {'Yes (Validated)' if prog_crawler.is_sufficient else 'No'}")
+        console.print(f"Pages needed: {len(state.crawled_urls)}")
+
+
+async def test_embedding_vs_statistical(use_openai=False):
+    """Compare embedding strategy with statistical strategy"""
+    console.print("\n[bold yellow]Test 2: Embedding vs Statistical Strategy Comparison[/bold yellow]")
+    
+    test_url = "https://httpbin.org"
+    test_query = "http headers authentication api"
+    
+    # Test 1: Statistical strategy
+    console.print("\n[cyan]1. Statistical Strategy:[/cyan]")
+    config_stat = AdaptiveConfig(
+        strategy="statistical",
+        confidence_threshold=0.7,
+        max_pages=10
+    )
+    
+    async with AsyncWebCrawler() as crawler:
+        stat_crawler = AdaptiveCrawler(crawler=crawler, config=config_stat)
+        
+        start_time = time.time()
+        state_stat = await stat_crawler.digest(start_url=test_url, query=test_query)
+        stat_time = time.time() - start_time
+        
+        stat_pages = len(state_stat.crawled_urls)
+        stat_confidence = stat_crawler.confidence
+    
+    # Test 2: Embedding strategy
+    console.print("\n[cyan]2. Embedding Strategy:[/cyan]")
+    config_emb = AdaptiveConfig(
+        strategy="embedding",
+        confidence_threshold=0.7,  # Not used for stopping
+        max_pages=10,
+        n_query_variations=5,
+        min_gain_threshold=0.01
+    )
+    
+    # Use OpenAI if available or requested
+    if use_openai and os.getenv('OPENAI_API_KEY'):
+        config_emb.embedding_llm_config = {
+            'provider': 'openai/text-embedding-3-small',
+            'api_token': os.getenv('OPENAI_API_KEY'),
+            'embedding_model': 'text-embedding-3-small'
+        }
+        console.print("[cyan]Using OpenAI embeddings[/cyan]")
+    else:
+        # Default config will try sentence-transformers
+        config_emb.embedding_llm_config = {
+            'provider': 'openai/gpt-4o-mini',
+            'api_token': os.getenv('OPENAI_API_KEY', 'dummy-key')
+        }
+    
+    async with AsyncWebCrawler() as crawler:
+        emb_crawler = AdaptiveCrawler(crawler=crawler, config=config_emb)
+        
+        start_time = time.time()
+        state_emb = await emb_crawler.digest(start_url=test_url, query=test_query)
+        emb_time = time.time() - start_time
+        
+        emb_pages = len(state_emb.crawled_urls)
+        emb_confidence = emb_crawler.confidence
+    
+    # Compare results
+    console.print("\n[bold green]Comparison Results:[/bold green]")
+    console.print(f"Statistical: {stat_pages} pages in {stat_time:.2f}s, confidence: {stat_confidence:.2%}, sufficient: {stat_crawler.is_sufficient}")
+    console.print(f"Embedding:   {emb_pages} pages in {emb_time:.2f}s, confidence: {emb_confidence:.2%}, sufficient: {emb_crawler.is_sufficient}")
+    
+    if emb_pages < stat_pages:
+        efficiency = ((stat_pages - emb_pages) / stat_pages) * 100
+        console.print(f"\n[green]Embedding strategy used {efficiency:.0f}% fewer pages![/green]")
+    
+    # Show validation info for embedding
+    if hasattr(state_emb, 'metrics') and 'validation_confidence' in state_emb.metrics:
+        console.print(f"Embedding validation score: {state_emb.metrics['validation_confidence']:.2%}")
+
+
+async def test_custom_embedding_provider():
+    """Test with different embedding providers"""
+    console.print("\n[bold yellow]Test 3: Custom Embedding Provider[/bold yellow]")
+    
+    # Example with OpenAI embeddings
+    config = AdaptiveConfig(
+        strategy="embedding",
+        confidence_threshold=0.8,  # Not used for stopping
+        max_pages=10,
+        min_gain_threshold=0.01,
+        n_query_variations=5
+    )
+    
+    # Configure to use OpenAI embeddings instead of sentence-transformers
+    config.embedding_llm_config = {
+        'provider': 'openai/text-embedding-3-small',
+        'api_token': os.getenv('OPENAI_API_KEY'),
+        'embedding_model': 'text-embedding-3-small'
+    }
+    
+    if not config.embedding_llm_config['api_token']:
+        console.print("[yellow]Skipping OpenAI embedding test - no API key[/yellow]")
+        return
+    
+    async with AsyncWebCrawler() as crawler:
+        prog_crawler = AdaptiveCrawler(crawler=crawler, config=config)
+        
+        console.print("Using OpenAI embeddings for semantic analysis...")
+        state = await prog_crawler.digest(
+            start_url="https://httpbin.org",
+            query="api endpoints json response"
+        )
+        
+        prog_crawler.print_stats(detailed=False)
+
+
+async def test_knowledge_export_import():
+    """Test exporting and importing semantic knowledge bases"""
+    console.print("\n[bold yellow]Test 4: Semantic Knowledge Base Export/Import[/bold yellow]")
+    
+    config = AdaptiveConfig(
+        strategy="embedding",
+        confidence_threshold=0.7,  # Not used for stopping
+        max_pages=5,
+        min_gain_threshold=0.01,
+        n_query_variations=4
+    )
+    
+    # First crawl
+    async with AsyncWebCrawler() as crawler:
+        crawler1 = AdaptiveCrawler(crawler=crawler, config=config)
+        
+        console.print("\n[cyan]Building initial knowledge base...[/cyan]")
+        state1 = await crawler1.digest(
+            start_url="https://httpbin.org",
+            query="http methods headers"
+        )
+        
+        # Export
+        export_path = "semantic_kb.jsonl"
+        crawler1.export_knowledge_base(export_path)
+        console.print(f"[green]Exported {len(state1.knowledge_base)} documents with embeddings[/green]")
+    
+    # Import and continue
+    async with AsyncWebCrawler() as crawler:
+        crawler2 = AdaptiveCrawler(crawler=crawler, config=config)
+        
+        console.print("\n[cyan]Importing knowledge base...[/cyan]")
+        crawler2.import_knowledge_base(export_path)
+        
+        # Continue with new query - should be faster
+        console.print("\n[cyan]Extending with new query...[/cyan]")
+        state2 = await crawler2.digest(
+            start_url="https://httpbin.org",
+            query="authentication oauth tokens"
+        )
+        
+        console.print(f"[green]Total knowledge base: {len(state2.knowledge_base)} documents[/green]")
+    
+    # Cleanup
+    Path(export_path).unlink(missing_ok=True)
+
+
+async def test_gap_visualization():
+    """Visualize semantic gaps and coverage"""
+    console.print("\n[bold yellow]Test 5: Semantic Gap Analysis[/bold yellow]")
+    
+    config = AdaptiveConfig(
+        strategy="embedding",
+        confidence_threshold=0.9,  # Not used for stopping
+        max_pages=8,
+        n_query_variations=6,
+        min_gain_threshold=0.01
+    )
+    
+    async with AsyncWebCrawler() as crawler:
+        prog_crawler = AdaptiveCrawler(crawler=crawler, config=config)
+        
+        # Initial crawl
+        state = await prog_crawler.digest(
+            start_url="https://docs.python.org/3/library/",
+            query="concurrency threading multiprocessing"
+        )
+        
+        # Analyze gaps
+        console.print("\n[bold cyan]Semantic Gap Analysis:[/bold cyan]")
+        console.print(f"Query variations: {len(state.expanded_queries)}")
+        console.print(f"Knowledge documents: {len(state.knowledge_base)}")
+        console.print(f"Identified gaps: {len(state.semantic_gaps)}")
+        
+        if state.semantic_gaps:
+            console.print("\n[yellow]Gap sizes (distance from coverage):[/yellow]")
+            for i, (_, distance) in enumerate(state.semantic_gaps[:5], 1):
+                console.print(f"  Gap {i}: {distance:.3f}")
+        
+        # Show crawl progression
+        console.print("\n[cyan]Crawl Order (gap-driven selection):[/cyan]")
+        for i, url in enumerate(state.crawl_order[:5], 1):
+            console.print(f"  {i}. {url}")
+
+
+async def test_fast_convergence_with_relevant_query():
+    """Test that both strategies reach high confidence quickly with relevant queries"""
+    console.print("\n[bold yellow]Test 7: Fast Convergence with Relevant Query[/bold yellow]")
+    console.print("Testing that strategies reach 80%+ confidence within 2-3 batches")
+    
+    # Test scenarios
+    test_cases = [
+        {
+            "name": "Python Async Documentation",
+            "url": "https://docs.python.org/3/library/asyncio.html",
+            "query": "async await coroutines event loops tasks"
+        }
+    ]
+    
+    for test_case in test_cases:
+        console.print(f"\n[bold cyan]Testing: {test_case['name']}[/bold cyan]")
+        console.print(f"URL: {test_case['url']}")
+        console.print(f"Query: {test_case['query']}")
+        
+        # Test Embedding Strategy
+        console.print("\n[yellow]Embedding Strategy:[/yellow]")
+        config_emb = AdaptiveConfig(
+            strategy="embedding",
+            confidence_threshold=0.8,
+            max_pages=9,
+            top_k_links=3,
+            min_gain_threshold=0.01,
+            n_query_variations=5
+        )
+        
+        # Configure embeddings
+        config_emb.embedding_llm_config = {
+            'provider': 'openai/gpt-4o-mini',
+            'api_token': os.getenv('OPENAI_API_KEY'),
+        }
+        
+        async with AsyncWebCrawler() as crawler:
+            emb_crawler = AdaptiveCrawler(crawler=crawler, config=config_emb)
+            
+            start_time = time.time()
+            state = await emb_crawler.digest(
+                start_url=test_case['url'],
+                query=test_case['query']
+            )
+            
+            # Get batch breakdown
+            total_pages = len(state.crawled_urls)
+            for i in range(0, total_pages, 3):
+                batch_num = (i // 3) + 1
+                batch_pages = min(3, total_pages - i)
+                pages_so_far = i + batch_pages
+                estimated_confidence = state.metrics.get('confidence', 0) * (pages_so_far / total_pages)
+                
+                console.print(f"Batch {batch_num}: {batch_pages} pages → Confidence: {estimated_confidence:.1%} {'✅' if estimated_confidence >= 0.8 else '❌'}")
+            
+            final_confidence = emb_crawler.confidence
+            console.print(f"[green]Final: {total_pages} pages → Confidence: {final_confidence:.1%} {'✅ (Sufficient!)' if emb_crawler.is_sufficient else '❌'}[/green]")
+            
+            # Show learning metrics for embedding
+            if 'avg_min_distance' in state.metrics:
+                console.print(f"[dim]Avg gap distance: {state.metrics['avg_min_distance']:.3f}[/dim]")
+            if 'validation_confidence' in state.metrics:
+                console.print(f"[dim]Validation score: {state.metrics['validation_confidence']:.1%}[/dim]")
+        
+        # Test Statistical Strategy
+        console.print("\n[yellow]Statistical Strategy:[/yellow]")
+        config_stat = AdaptiveConfig(
+            strategy="statistical",
+            confidence_threshold=0.8,
+            max_pages=9,
+            top_k_links=3,
+            min_gain_threshold=0.01
+        )
+        
+        async with AsyncWebCrawler() as crawler:
+            stat_crawler = AdaptiveCrawler(crawler=crawler, config=config_stat)
+            
+            # Track batch progress
+            batch_results = []
+            current_pages = 0
+            
+            # Custom batch tracking
+            start_time = time.time()
+            state = await stat_crawler.digest(
+                start_url=test_case['url'],
+                query=test_case['query']
+            )
+            
+            # Get batch breakdown (every 3 pages)
+            total_pages = len(state.crawled_urls)
+            for i in range(0, total_pages, 3):
+                batch_num = (i // 3) + 1
+                batch_pages = min(3, total_pages - i)
+                # Estimate confidence at this point (simplified)
+                pages_so_far = i + batch_pages
+                estimated_confidence = state.metrics.get('confidence', 0) * (pages_so_far / total_pages)
+                
+                console.print(f"Batch {batch_num}: {batch_pages} pages → Confidence: {estimated_confidence:.1%} {'✅' if estimated_confidence >= 0.8 else '❌'}")
+            
+            final_confidence = stat_crawler.confidence
+            console.print(f"[green]Final: {total_pages} pages → Confidence: {final_confidence:.1%} {'✅ (Sufficient!)' if stat_crawler.is_sufficient else '❌'}[/green]")
+        
+        
+
+
+async def test_irrelevant_query_behavior():
+    """Test how embedding strategy handles completely irrelevant queries"""
+    console.print("\n[bold yellow]Test 8: Irrelevant Query Behavior[/bold yellow]")
+    console.print("Testing embedding strategy with a query that has no semantic relevance to the content")
+    
+    # Test with irrelevant query on Python async documentation
+    test_case = {
+        "name": "Irrelevant Query on Python Docs",
+        "url": "https://docs.python.org/3/library/asyncio.html",
+        "query": "how to cook fried rice with vegetables"
+    }
+    
+    console.print(f"\n[bold cyan]Testing: {test_case['name']}[/bold cyan]")
+    console.print(f"URL: {test_case['url']} (Python async documentation)")
+    console.print(f"Query: '{test_case['query']}' (completely irrelevant)")
+    console.print("\n[dim]Expected behavior: Low confidence, high distances, no convergence[/dim]")
+    
+    # Configure embedding strategy
+    config_emb = AdaptiveConfig(
+        strategy="embedding",
+        confidence_threshold=0.8,
+        max_pages=9,
+        top_k_links=3,
+        min_gain_threshold=0.01,
+        n_query_variations=5,
+        embedding_min_relative_improvement=0.05,  # Lower threshold to see more iterations
+        embedding_min_confidence_threshold=0.1  # Will stop if confidence < 10%
+    )
+    
+    # Configure embeddings using the correct format
+    config_emb.embedding_llm_config = {
+        'provider': 'openai/gpt-4o-mini',
+        'api_token': os.getenv('OPENAI_API_KEY'),
+    }
+    
+    async with AsyncWebCrawler() as crawler:
+        emb_crawler = AdaptiveCrawler(crawler=crawler, config=config_emb)
+        
+        start_time = time.time()
+        state = await emb_crawler.digest(
+            start_url=test_case['url'],
+            query=test_case['query']
+        )
+        elapsed = time.time() - start_time
+        
+        # Analyze results
+        console.print(f"\n[bold]Results after {elapsed:.1f} seconds:[/bold]")
+        
+        # Basic metrics
+        total_pages = len(state.crawled_urls)
+        final_confidence = emb_crawler.confidence
+        
+        console.print(f"\nPages crawled: {total_pages}")
+        console.print(f"Final confidence: {final_confidence:.1%} {'✅' if emb_crawler.is_sufficient else '❌'}")
+        
+        # Distance metrics
+        if 'avg_min_distance' in state.metrics:
+            console.print(f"\n[yellow]Distance Metrics:[/yellow]")
+            console.print(f"  Average minimum distance: {state.metrics['avg_min_distance']:.3f}")
+            console.print(f"  Close neighbors (<0.3): {state.metrics.get('avg_close_neighbors', 0):.1f}")
+            console.print(f"  Very close neighbors (<0.2): {state.metrics.get('avg_very_close_neighbors', 0):.1f}")
+            
+            # Interpret distances
+            avg_dist = state.metrics['avg_min_distance']
+            if avg_dist > 0.8:
+                console.print(f"  [red]→ Very poor match (distance > 0.8)[/red]")
+            elif avg_dist > 0.6:
+                console.print(f"  [yellow]→ Poor match (distance > 0.6)[/yellow]")
+            elif avg_dist > 0.4:
+                console.print(f"  [blue]→ Moderate match (distance > 0.4)[/blue]")
+            else:
+                console.print(f"  [green]→ Good match (distance < 0.4)[/green]")
+        
+        # Show sample expanded queries
+        if state.expanded_queries:
+            console.print(f"\n[yellow]Sample Query Variations Generated:[/yellow]")
+            for i, q in enumerate(state.expanded_queries[:3], 1):
+                console.print(f"  {i}. {q}")
+        
+        # Show crawl progression
+        console.print(f"\n[yellow]Crawl Progression:[/yellow]")
+        for i, url in enumerate(state.crawl_order[:5], 1):
+            console.print(f"  {i}. {url}")
+        if len(state.crawl_order) > 5:
+            console.print(f"  ... and {len(state.crawl_order) - 5} more")
+        
+        # Validation score
+        if 'validation_confidence' in state.metrics:
+            console.print(f"\n[yellow]Validation:[/yellow]")
+            console.print(f"  Validation score: {state.metrics['validation_confidence']:.1%}")
+        
+        # Why it stopped
+        if 'stopped_reason' in state.metrics:
+            console.print(f"\n[yellow]Stopping Reason:[/yellow] {state.metrics['stopped_reason']}")
+            if state.metrics.get('is_irrelevant', False):
+                console.print("[red]→ Query and content are completely unrelated![/red]")
+        elif total_pages >= config_emb.max_pages:
+            console.print(f"\n[yellow]Stopping Reason:[/yellow] Reached max pages limit ({config_emb.max_pages})")
+        
+        # Summary
+        console.print(f"\n[bold]Summary:[/bold]")
+        if final_confidence < 0.2:
+            console.print("[red]✗ As expected: Query is completely irrelevant to content[/red]")
+            console.print("[green]✓ The embedding strategy correctly identified no semantic match[/green]")
+        else:
+            console.print(f"[yellow]⚠ Unexpected: Got {final_confidence:.1%} confidence for irrelevant query[/yellow]")
+            console.print("[yellow]  This may indicate the query variations are too broad[/yellow]")
+
+
+async def test_high_dimensional_handling():
+    """Test handling of high-dimensional embedding spaces"""
+    console.print("\n[bold yellow]Test 6: High-Dimensional Embedding Space Handling[/bold yellow]")
+    console.print("Testing how the system handles 384+ dimensional embeddings")
+    
+    config = AdaptiveConfig(
+        strategy="embedding",
+        confidence_threshold=0.8,  # Not used for stopping
+        max_pages=5,
+        n_query_variations=8,  # Will create 9 points total
+        min_gain_threshold=0.01,
+        embedding_model="sentence-transformers/all-MiniLM-L6-v2"  # 384 dimensions
+    )
+    
+    # Use OpenAI if available, otherwise mock
+    if os.getenv('OPENAI_API_KEY'):
+        config.embedding_llm_config = {
+            'provider': 'openai/text-embedding-3-small',
+            'api_token': os.getenv('OPENAI_API_KEY'),
+            'embedding_model': 'text-embedding-3-small'
+        }
+    else:
+        config.embedding_llm_config = {
+            'provider': 'openai/gpt-4o-mini',
+            'api_token': 'mock-key'
+        }
+    
+    async with AsyncWebCrawler() as crawler:
+        prog_crawler = AdaptiveCrawler(crawler=crawler, config=config)
+        
+        console.print("\n[cyan]Testing with high-dimensional embeddings (384D)...[/cyan]")
+        
+        try:
+            state = await prog_crawler.digest(
+                start_url="https://httpbin.org",
+                query="api endpoints json"
+            )
+            
+            console.print(f"[green]✓ Successfully handled {len(state.expanded_queries)} queries in 384D space[/green]")
+            console.print(f"Coverage shape type: {type(state.coverage_shape)}")
+            
+            if isinstance(state.coverage_shape, dict):
+                console.print(f"Coverage model: centroid + radius")
+                console.print(f"  - Center shape: {state.coverage_shape['center'].shape if 'center' in state.coverage_shape else 'N/A'}")
+                console.print(f"  - Radius: {state.coverage_shape.get('radius', 'N/A'):.3f}")
+            
+        except Exception as e:
+            console.print(f"[red]Error: {e}[/red]")
+            console.print("[yellow]This demonstrates why alpha shapes don't work in high dimensions[/yellow]")
+
+
+async def main():
+    """Run all embedding strategy tests"""
+    console.print("[bold magenta]Embedding-based Adaptive Crawler Test Suite[/bold magenta]")
+    console.print("=" * 60)
+    
+    try:
+        # Check if we have required dependencies
+        has_sentence_transformers = True
+        has_numpy = True
+        
+        try:
+            import numpy
+            console.print("[green]✓ NumPy installed[/green]")
+        except ImportError:
+            has_numpy = False
+            console.print("[red]Missing numpy[/red]")
+            
+        # Try to import sentence_transformers but catch numpy compatibility errors
+        try:
+            import sentence_transformers
+            console.print("[green]✓ Sentence-transformers installed[/green]")
+        except (ImportError, RuntimeError, ValueError) as e:
+            has_sentence_transformers = False
+            console.print(f"[yellow]Warning: sentence-transformers not available[/yellow]")
+            console.print("[yellow]Tests will use OpenAI embeddings if available or mock data[/yellow]")
+        
+        # Run tests based on available dependencies
+        if has_numpy:
+            # Check if we should use OpenAI for embeddings
+            use_openai = not has_sentence_transformers and os.getenv('OPENAI_API_KEY')
+            
+            if not has_sentence_transformers and not os.getenv('OPENAI_API_KEY'):
+                console.print("\n[red]Neither sentence-transformers nor OpenAI API key available[/red]")
+                console.print("[yellow]Please set OPENAI_API_KEY or fix sentence-transformers installation[/yellow]")
+                return
+            
+            # Run all tests
+            # await test_basic_embedding_crawl()
+            # await test_embedding_vs_statistical(use_openai=use_openai)
+            
+            # Run the fast convergence test - this is the most important one
+            # await test_fast_convergence_with_relevant_query()
+            
+            # Test with irrelevant query
+            await test_irrelevant_query_behavior()
+            
+            # Only run OpenAI-specific test if we have API key
+            # if os.getenv('OPENAI_API_KEY'):
+            #     await test_custom_embedding_provider()
+            
+            # # Skip tests that require sentence-transformers when it's not available
+            # if has_sentence_transformers:
+            #     await test_knowledge_export_import()
+            #     await test_gap_visualization()
+            # else:
+            #     console.print("\n[yellow]Skipping tests that require sentence-transformers due to numpy compatibility issues[/yellow]")
+            
+            # This test should work with mock data
+            # await test_high_dimensional_handling()
+        else:
+            console.print("\n[red]Cannot run tests without NumPy[/red]")
+            return
+        
+        console.print("\n[bold green]✅ All tests completed![/bold green]")
+        
+    except Exception as e:
+        console.print(f"\n[bold red]❌ Test failed: {e}[/bold red]")
+        import traceback
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+    
+    
+    
+    
+    
+    
+    
+    

tests/deep_crwaling/test_filter.py

@@ -0,0 +1,75 @@
+# // File: tests/deep_crawling/test_filters.py
+import pytest
+from urllib.parse import urlparse
+from crawl4ai import ContentTypeFilter, URLFilter 
+
+# Minimal URLFilter base class stub if not already importable directly for tests
+# In a real scenario, this would be imported from the library
+if not hasattr(URLFilter, '_update_stats'): # Check if it's a basic stub
+    class URLFilter: # Basic stub for testing if needed
+        def __init__(self, name=None): self.name = name
+        def apply(self, url: str) -> bool: raise NotImplementedError
+        def _update_stats(self, passed: bool): pass # Mock implementation
+
+# Assume ContentTypeFilter is structured as discussed. If its definition is not fully
+# available for direct import in the test environment, a more elaborate stub or direct
+# instantiation of the real class (if possible) would be needed.
+# For this example, we assume ContentTypeFilter can be imported and used.
+
+class TestContentTypeFilter:
+    @pytest.mark.parametrize(
+        "url, allowed_types, expected",
+        [
+            # Existing tests (examples)
+            ("http://example.com/page.html", ["text/html"], True),
+            ("http://example.com/page.json", ["application/json"], True),
+            ("http://example.com/image.png", ["text/html"], False),
+            ("http://example.com/document.pdf", ["application/pdf"], True),
+            ("http://example.com/page", ["text/html"], True), # No extension, allowed
+            ("http://example.com/page", ["text/html"], False), # No extension, disallowed
+            ("http://example.com/page.unknown", ["text/html"], False), # Unknown extension
+            
+            # Tests for PHP extensions
+            ("http://example.com/index.php", ["application/x-httpd-php"], True),
+            ("http://example.com/script.php3", ["application/x-httpd-php"], True),
+            ("http://example.com/legacy.php4", ["application/x-httpd-php"], True),
+            ("http://example.com/main.php5", ["application/x-httpd-php"], True),
+            ("http://example.com/api.php7", ["application/x-httpd-php"], True),
+            ("http://example.com/index.phtml", ["application/x-httpd-php"], True),
+            ("http://example.com/source.phps", ["application/x-httpd-php-source"], True),
+
+            # Test rejection of PHP extensions
+            ("http://example.com/index.php", ["text/html"], False),
+            ("http://example.com/script.php3", ["text/plain"], False),
+            ("http://example.com/source.phps", ["application/x-httpd-php"], False), # Mismatch MIME
+            ("http://example.com/source.php", ["application/x-httpd-php-source"], False), # Mismatch MIME for .php
+
+            # Test case-insensitivity of extensions in URL
+            ("http://example.com/PAGE.HTML", ["text/html"], True),
+            ("http://example.com/INDEX.PHP", ["application/x-httpd-php"], True),
+            ("http://example.com/SOURCE.PHPS", ["application/x-httpd-php-source"], True),
+
+            # Test case-insensitivity of allowed_types
+            ("http://example.com/index.php", ["APPLICATION/X-HTTPD-PHP"], True),
+        ],
+    )
+    def test_apply(self, url, allowed_types, expected):
+        content_filter = ContentTypeFilter(
+            allowed_types=allowed_types
+        )
+        assert content_filter.apply(url) == expected
+
+    @pytest.mark.parametrize(
+        "url, expected_extension",
+        [
+            ("http://example.com/file.html", "html"),
+            ("http://example.com/file.tar.gz", "gz"),
+            ("http://example.com/path/", ""),
+            ("http://example.com/nodot", ""),
+            ("http://example.com/.config", "config"), # hidden file with extension
+            ("http://example.com/path/to/archive.BIG.zip", "zip"), # Case test
+        ]
+    )
+    def test_extract_extension(self, url, expected_extension):
+        # Test the static method directly
+        assert ContentTypeFilter._extract_extension(url) == expected_extension

tests/docker_example.py

@@ -105,7 +105,7 @@ def test_docker_deployment(version="basic"):
 def test_basic_crawl(tester: Crawl4AiTester):
     print("\n=== Testing Basic Crawl ===")
     request = {
-        "urls": "https://www.nbcnews.com/business",
+        "urls": ["https://www.nbcnews.com/business"],
         "priority": 10,
         "session_id": "test",
     }
@@ -119,7 +119,7 @@ def test_basic_crawl(tester: Crawl4AiTester):
 def test_basic_crawl_sync(tester: Crawl4AiTester):
     print("\n=== Testing Basic Crawl (Sync) ===")
     request = {
-        "urls": "https://www.nbcnews.com/business",
+        "urls": ["https://www.nbcnews.com/business"],
         "priority": 10,
         "session_id": "test",
     }
@@ -134,7 +134,7 @@ def test_basic_crawl_sync(tester: Crawl4AiTester):
 def test_js_execution(tester: Crawl4AiTester):
     print("\n=== Testing JS Execution ===")
     request = {
-        "urls": "https://www.nbcnews.com/business",
+        "urls": ["https://www.nbcnews.com/business"],
         "priority": 8,
         "js_code": [
             "const loadMoreButton = Array.from(document.querySelectorAll('button')).find(button => button.textContent.includes('Load More')); loadMoreButton && loadMoreButton.click();"
@@ -151,7 +151,7 @@ def test_js_execution(tester: Crawl4AiTester):
 def test_css_selector(tester: Crawl4AiTester):
     print("\n=== Testing CSS Selector ===")
     request = {
-        "urls": "https://www.nbcnews.com/business",
+        "urls": ["https://www.nbcnews.com/business"],
         "priority": 7,
         "css_selector": ".wide-tease-item__description",
         "crawler_params": {"headless": True},
@@ -188,7 +188,7 @@ def test_structured_extraction(tester: Crawl4AiTester):
     }
 
     request = {
-        "urls": "https://www.coinbase.com/explore",
+        "urls": ["https://www.coinbase.com/explore"],
         "priority": 9,
         "extraction_config": {"type": "json_css", "params": {"schema": schema}},
     }
@@ -223,7 +223,7 @@ def test_llm_extraction(tester: Crawl4AiTester):
     }
 
     request = {
-        "urls": "https://openai.com/api/pricing",
+        "urls": ["https://openai.com/api/pricing"],
         "priority": 8,
         "extraction_config": {
             "type": "llm",
@@ -270,7 +270,7 @@ def test_llm_with_ollama(tester: Crawl4AiTester):
     }
 
     request = {
-        "urls": "https://www.nbcnews.com/business",
+        "urls": ["https://www.nbcnews.com/business"],
         "priority": 8,
         "extraction_config": {
             "type": "llm",
@@ -297,7 +297,7 @@ def test_llm_with_ollama(tester: Crawl4AiTester):
 def test_cosine_extraction(tester: Crawl4AiTester):
     print("\n=== Testing Cosine Extraction ===")
     request = {
-        "urls": "https://www.nbcnews.com/business",
+        "urls": ["https://www.nbcnews.com/business"],
         "priority": 8,
         "extraction_config": {
             "type": "cosine",
@@ -323,7 +323,7 @@ def test_cosine_extraction(tester: Crawl4AiTester):
 def test_screenshot(tester: Crawl4AiTester):
     print("\n=== Testing Screenshot ===")
     request = {
-        "urls": "https://www.nbcnews.com/business",
+        "urls": ["https://www.nbcnews.com/business"],
         "priority": 5,
         "screenshot": True,
         "crawler_params": {"headless": True},

tests/general/test_async_crawler_strategy.py

@@ -15,6 +15,24 @@ CRAWL4AI_HOME_DIR = Path(os.path.expanduser("~")).joinpath(".crawl4ai")
 if not CRAWL4AI_HOME_DIR.joinpath("profiles", "test_profile").exists():
     CRAWL4AI_HOME_DIR.joinpath("profiles", "test_profile").mkdir(parents=True)
 
+@pytest.fixture
+def basic_html():
+    return """
+    <html lang="en">
+    <head>
+        <title>Basic HTML</title>
+    </head>
+    <body>
+        <h1>Main Heading</h1>
+        <main>
+            <div class="container">
+                <p>Basic HTML document for testing purposes.</p>
+            </div>
+        </main>
+    </body>
+    </html>
+    """
+
 # Test Config Files
 @pytest.fixture
 def basic_browser_config():
@@ -325,6 +343,13 @@ async def test_stealth_mode(crawler_strategy):
     )
     assert response.status_code == 200
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("prefix", ("raw:", "raw://"))
+async def test_raw_urls(crawler_strategy, basic_html, prefix):
+    url = f"{prefix}{basic_html}"
+    response = await crawler_strategy.crawl(url, CrawlerRunConfig())
+    assert response.html == basic_html
+
 # Error Handling Tests  
 @pytest.mark.asyncio
 async def test_invalid_url():

tests/general/test_download_file.py

@@ -0,0 +1,34 @@
+import asyncio
+from crawl4ai import CrawlerRunConfig, AsyncWebCrawler, BrowserConfig
+from pathlib import Path
+import os
+
+async def test_basic_download():
+    
+    # Custom folder (otherwise defaults to ~/.crawl4ai/downloads)
+    downloads_path = os.path.join(Path.home(), ".crawl4ai", "downloads")
+    os.makedirs(downloads_path, exist_ok=True)
+    browser_config = BrowserConfig(
+        accept_downloads=True,
+        downloads_path=downloads_path
+    )
+    async with AsyncWebCrawler(config=browser_config) as crawler:
+        run_config = CrawlerRunConfig(
+            js_code="""
+                const link = document.querySelector('a[href$=".exe"]');
+                if (link) { link.click(); }
+            """,
+            delay_before_return_html=5  
+        )
+        result = await crawler.arun("https://www.python.org/downloads/", config=run_config)
+
+        if result.downloaded_files:
+            print("Downloaded files:")
+            for file_path in result.downloaded_files:
+                print("•", file_path)
+        else:
+            print("No files downloaded.")
+
+if __name__ == "__main__":
+    asyncio.run(test_basic_download())
+ 

tests/general/test_max_scroll.py

@@ -0,0 +1,115 @@
+"""
+Sample script to test the max_scroll_steps parameter implementation
+"""
+import asyncio
+import os
+import sys
+
+# Get the grandparent directory
+grandparent_dir = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.append(grandparent_dir)
+__location__ = os.path.realpath(os.path.join(os.getcwd(), os.path.dirname(__file__)))
+
+
+
+from crawl4ai import AsyncWebCrawler
+from crawl4ai.async_configs import CrawlerRunConfig
+
+async def test_max_scroll_steps():
+    """
+    Test the max_scroll_steps parameter with different configurations
+    """
+    print("🚀 Testing max_scroll_steps parameter implementation")
+    print("=" * 60)
+    
+    async with AsyncWebCrawler(verbose=True) as crawler:
+        
+        # Test 1: Without max_scroll_steps (unlimited scrolling)
+        print("\\n📋 Test 1: Unlimited scrolling (max_scroll_steps=None)")
+        config1 = CrawlerRunConfig(
+            scan_full_page=True,
+            scroll_delay=0.1,
+            max_scroll_steps=None,  # Default behavior
+            verbose=True
+        )
+        
+        print(f"Config: scan_full_page={config1.scan_full_page}, max_scroll_steps={config1.max_scroll_steps}")
+        
+        try:
+            result1 = await crawler.arun(
+                url="https://example.com",  # Simple page for testing
+                config=config1
+            )
+            print(f"✅ Test 1 Success: Crawled {len(result1.markdown)} characters")
+        except Exception as e:
+            print(f"❌ Test 1 Failed: {e}")
+        
+        # Test 2: With limited scroll steps
+        print("\\n📋 Test 2: Limited scrolling (max_scroll_steps=3)")
+        config2 = CrawlerRunConfig(
+            scan_full_page=True,
+            scroll_delay=0.1,
+            max_scroll_steps=3,  # Limit to 3 scroll steps
+            verbose=True
+        )
+        
+        print(f"Config: scan_full_page={config2.scan_full_page}, max_scroll_steps={config2.max_scroll_steps}")
+        
+        try:
+            result2 = await crawler.arun(
+                url="https://techcrunch.com/",  # Another test page
+                config=config2
+            )
+            print(f"✅ Test 2 Success: Crawled {len(result2.markdown)} characters")
+        except Exception as e:
+            print(f"❌ Test 2 Failed: {e}")
+        
+        # Test 3: Test serialization/deserialization
+        print("\\n📋 Test 3: Configuration serialization test")
+        config3 = CrawlerRunConfig(
+            scan_full_page=True,
+            max_scroll_steps=5,
+            scroll_delay=0.2
+        )
+        
+        # Test to_dict
+        config_dict = config3.to_dict()
+        print(f"Serialized max_scroll_steps: {config_dict.get('max_scroll_steps')}")
+        
+        # Test from_kwargs
+        config4 = CrawlerRunConfig.from_kwargs({
+            'scan_full_page': True,
+            'max_scroll_steps': 7,
+            'scroll_delay': 0.3
+        })
+        print(f"Deserialized max_scroll_steps: {config4.max_scroll_steps}")
+        print("✅ Test 3 Success: Serialization works correctly")
+        
+        # Test 4: Edge case - max_scroll_steps = 0
+        print("\\n📋 Test 4: Edge case (max_scroll_steps=0)")
+        config5 = CrawlerRunConfig(
+            scan_full_page=True,
+            max_scroll_steps=0,  # Should not scroll at all
+            verbose=True
+        )
+        
+        try:
+            result5 = await crawler.arun(
+                url="https://techcrunch.com/",
+                config=config5
+            )
+            print(f"✅ Test 4 Success: No scrolling performed, crawled {len(result5.markdown)} characters")
+        except Exception as e:
+            print(f"❌ Test 4 Failed: {e}")
+    
+    print("\\n" + "=" * 60)
+    print("🎉 All tests completed!")
+    print("\\nThe max_scroll_steps parameter is working correctly:")
+    print("- None: Unlimited scrolling (default behavior)")
+    print("- Positive integer: Limits scroll steps to that number")
+    print("- 0: No scrolling performed")
+    print("- Properly serializes/deserializes in config")
+
+if __name__ == "__main__":
+    print("Starting max_scroll_steps test...")
+    asyncio.run(test_max_scroll_steps())

tests/general/test_url_pattern.py

@@ -0,0 +1,85 @@
+import sys
+import os
+
+# Get the grandparent directory
+grandparent_dir = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.append(grandparent_dir)
+__location__ = os.path.realpath(os.path.join(os.getcwd(), os.path.dirname(__file__)))
+
+import asyncio
+from crawl4ai.deep_crawling.filters import URLPatternFilter
+
+
+def test_prefix_boundary_matching():
+    """Test that prefix patterns respect path boundaries"""
+    print("=== Testing URLPatternFilter Prefix Boundary Fix ===")
+    
+    filter_obj = URLPatternFilter(patterns=['https://langchain-ai.github.io/langgraph/*'])
+    
+    test_cases = [
+        ('https://langchain-ai.github.io/langgraph/', True),
+        ('https://langchain-ai.github.io/langgraph/concepts/', True),
+        ('https://langchain-ai.github.io/langgraph/tutorials/', True),
+        ('https://langchain-ai.github.io/langgraph?param=1', True),
+        ('https://langchain-ai.github.io/langgraph#section', True),
+        ('https://langchain-ai.github.io/langgraphjs/', False),
+        ('https://langchain-ai.github.io/langgraphjs/concepts/', False),
+        ('https://other-site.com/langgraph/', False),
+    ]
+    
+    all_passed = True
+    for url, expected in test_cases:
+        result = filter_obj.apply(url)
+        status = "PASS" if result == expected else "FAIL"
+        if result != expected:
+            all_passed = False
+        print(f"{status:4} | Expected: {expected:5} | Got: {result:5} | {url}")
+    
+    return all_passed
+
+
+def test_edge_cases():
+    """Test edge cases for path boundary matching"""
+    print("\n=== Testing Edge Cases ===")
+    
+    test_patterns = [
+        ('/api/*', [
+            ('/api/', True),
+            ('/api/v1', True),
+            ('/api?param=1', True),
+            ('/apiv2/', False),
+            ('/api_old/', False),
+        ]),
+        
+        ('*/docs/*', [
+            ('example.com/docs/', True),
+            ('example.com/docs/guide', True),
+            ('example.com/documentation/', False),
+            ('example.com/docs_old/', False),
+        ]),
+    ]
+    
+    all_passed = True
+    for pattern, test_cases in test_patterns:
+        print(f"\nPattern: {pattern}")
+        filter_obj = URLPatternFilter(patterns=[pattern])
+        
+        for url, expected in test_cases:
+            result = filter_obj.apply(url)
+            status = "PASS" if result == expected else "FAIL"
+            if result != expected:
+                all_passed = False
+            print(f"  {status:4} | Expected: {expected:5} | Got: {result:5} | {url}")
+    
+    return all_passed
+
+if __name__ == "__main__":
+    test1_passed = test_prefix_boundary_matching()
+    test2_passed = test_edge_cases()
+    
+    if test1_passed and test2_passed:
+        print("\n✅ All tests passed!")
+        sys.exit(0)
+    else:
+        print("\n❌ Some tests failed!")
+        sys.exit(1)

tests/releases/test_release_0.6.4.py

@@ -0,0 +1,151 @@
+import pytest
+import asyncio
+import time
+from crawl4ai import AsyncWebCrawler, CrawlerRunConfig, BrowserConfig, CacheMode
+
+
+@pytest.mark.asyncio
+async def test_wait_for_timeout_separate_from_page_timeout():
+    """Test that wait_for has its own timeout separate from page_timeout"""
+    browser_config = BrowserConfig(headless=True)
+    
+    # Test with short wait_for_timeout but longer page_timeout
+    config = CrawlerRunConfig(
+        wait_for="css:.nonexistent-element",
+        wait_for_timeout=2000,  # 2 seconds
+        page_timeout=10000,     # 10 seconds
+        cache_mode=CacheMode.BYPASS
+    )
+    
+    async with AsyncWebCrawler(config=browser_config) as crawler:
+        start_time = time.time()
+        result = await crawler.arun("https://example.com", config=config)
+        elapsed = time.time() - start_time
+        
+        # Should timeout after ~2 seconds (wait_for_timeout), not 10 seconds
+        assert elapsed < 5, f"Expected timeout around 2s, but took {elapsed:.2f}s"
+        assert result.success, "Crawl should still succeed even if wait_for times out"
+
+
+@pytest.mark.asyncio
+async def test_wait_for_timeout_with_existing_element():
+    """Test that wait_for_timeout works correctly when element exists"""
+    browser_config = BrowserConfig(headless=True)
+    
+    config = CrawlerRunConfig(
+        wait_for="css:body",  # This should exist quickly
+        wait_for_timeout=5000,
+        cache_mode=CacheMode.BYPASS
+    )
+    
+    async with AsyncWebCrawler(config=browser_config) as crawler:
+        start_time = time.time()
+        result = await crawler.arun("https://example.com", config=config)
+        elapsed = time.time() - start_time
+        
+        # Should complete quickly since body element exists
+        assert elapsed < 3, f"Expected quick completion, but took {elapsed:.2f}s"
+        assert result.success
+        assert "<body" in result.html
+
+
+@pytest.mark.asyncio
+async def test_javascript_wait_for_timeout():
+    """Test wait_for_timeout with JavaScript condition"""
+    browser_config = BrowserConfig(headless=True)
+    
+    config = CrawlerRunConfig(
+        wait_for="js:() => window.nonExistentVariable === true",
+        wait_for_timeout=2000,
+        cache_mode=CacheMode.BYPASS
+    )
+    
+    async with AsyncWebCrawler(config=browser_config) as crawler:
+        start_time = time.time()
+        result = await crawler.arun("https://example.com", config=config)
+        elapsed = time.time() - start_time
+        
+        # Should timeout after ~2 seconds
+        assert elapsed < 4, f"Expected timeout around 2s, but took {elapsed:.2f}s"
+        assert result.success
+
+
+@pytest.mark.asyncio
+async def test_google_analytics_integration():
+    """Test that Google Analytics scripts are properly integrated"""
+    browser_config = BrowserConfig(headless=True)
+    config = CrawlerRunConfig(cache_mode=CacheMode.BYPASS)
+    
+    # Test with a simple HTML page that we can control
+    html_content = """
+    <!DOCTYPE html>
+    <html>
+    <head>
+        <title>Test GA Integration</title>
+        <!-- Google tag (gtag.js) -->
+        <script async src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>
+        <script>
+          window.dataLayer = window.dataLayer || [];
+          function gtag(){dataLayer.push(arguments);}
+          gtag('config', 'GA_MEASUREMENT_ID');
+        </script>
+    </head>
+    <body>
+        <h1>Test Page</h1>
+        <p>Testing Google Analytics integration</p>
+    </body>
+    </html>
+    """
+    
+    async with AsyncWebCrawler(config=browser_config) as crawler:
+        result = await crawler.arun(f"raw://{html_content}", config=config)
+        
+        assert result.success
+        # Check that GA scripts are preserved in the HTML
+        assert "googletagmanager.com/gtag/js" in result.html
+        assert "dataLayer" in result.html
+        assert "gtag('config'" in result.html
+
+
+@pytest.mark.asyncio
+async def test_mkdocs_no_duplicate_gtag():
+    """Test that there are no duplicate gtag.js entries in documentation"""
+    browser_config = BrowserConfig(headless=True)
+    config = CrawlerRunConfig(cache_mode=CacheMode.BYPASS)
+    
+    # Simulate MkDocs-like HTML structure
+    html_content = """
+    <!DOCTYPE html>
+    <html>
+    <head>
+        <title>Crawl4AI Documentation</title>
+        <script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
+        <script>
+          window.dataLayer = window.dataLayer || [];
+          function gtag(){dataLayer.push(arguments);}
+          gtag('config', 'G-XXXXXXXXXX');
+        </script>
+    </head>
+    <body>
+        <h1>Crawl4AI Documentation</h1>
+        <p>Welcome to the documentation</p>
+    </body>
+    </html>
+    """
+    
+    async with AsyncWebCrawler(config=browser_config) as crawler:
+        result = await crawler.arun(f"raw://{html_content}", config=config)
+        
+        assert result.success
+        # Count occurrences of gtag.js to ensure no duplicates
+        gtag_count = result.html.count("googletagmanager.com/gtag/js")
+        assert gtag_count <= 1, f"Found {gtag_count} gtag.js scripts, expected at most 1"
+        
+        # Ensure the analytics functionality is still there
+        if gtag_count == 1:
+            assert "dataLayer" in result.html
+            assert "gtag('config'" in result.html
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

tests/test_docker.py

@@ -74,7 +74,7 @@ def test_docker_deployment(version="basic"):
 
 def test_basic_crawl(tester: Crawl4AiTester):
     print("\n=== Testing Basic Crawl ===")
-    request = {"urls": "https://www.nbcnews.com/business", "priority": 10}
+    request = {"urls": ["https://www.nbcnews.com/business"], "priority": 10}
 
     result = tester.submit_and_wait(request)
     print(f"Basic crawl result length: {len(result['result']['markdown'])}")
@@ -85,7 +85,7 @@ def test_basic_crawl(tester: Crawl4AiTester):
 def test_js_execution(tester: Crawl4AiTester):
     print("\n=== Testing JS Execution ===")
     request = {
-        "urls": "https://www.nbcnews.com/business",
+        "urls": ["https://www.nbcnews.com/business"],
         "priority": 8,
         "js_code": [
             "const loadMoreButton = Array.from(document.querySelectorAll('button')).find(button => button.textContent.includes('Load More')); loadMoreButton && loadMoreButton.click();"
@@ -102,7 +102,7 @@ def test_js_execution(tester: Crawl4AiTester):
 def test_css_selector(tester: Crawl4AiTester):
     print("\n=== Testing CSS Selector ===")
     request = {
-        "urls": "https://www.nbcnews.com/business",
+        "urls": ["https://www.nbcnews.com/business"],
         "priority": 7,
         "css_selector": ".wide-tease-item__description",
         "crawler_params": {"headless": True},
@@ -139,7 +139,7 @@ def test_structured_extraction(tester: Crawl4AiTester):
     }
 
     request = {
-        "urls": "https://www.coinbase.com/explore",
+        "urls": ["https://www.coinbase.com/explore"],
         "priority": 9,
         "extraction_config": {"type": "json_css", "params": {"schema": schema}},
     }
@@ -174,7 +174,7 @@ def test_llm_extraction(tester: Crawl4AiTester):
     }
 
     request = {
-        "urls": "https://openai.com/api/pricing",
+        "urls": ["https://openai.com/api/pricing"],
         "priority": 8,
         "extraction_config": {
             "type": "llm",
@@ -221,7 +221,7 @@ def test_llm_with_ollama(tester: Crawl4AiTester):
     }
 
     request = {
-        "urls": "https://www.nbcnews.com/business",
+        "urls": ["https://www.nbcnews.com/business"],
         "priority": 8,
         "extraction_config": {
             "type": "llm",
@@ -248,7 +248,7 @@ def test_llm_with_ollama(tester: Crawl4AiTester):
 def test_cosine_extraction(tester: Crawl4AiTester):
     print("\n=== Testing Cosine Extraction ===")
     request = {
-        "urls": "https://www.nbcnews.com/business",
+        "urls": ["https://www.nbcnews.com/business"],
         "priority": 8,
         "extraction_config": {
             "type": "cosine",
@@ -274,7 +274,7 @@ def test_cosine_extraction(tester: Crawl4AiTester):
 def test_screenshot(tester: Crawl4AiTester):
     print("\n=== Testing Screenshot ===")
     request = {
-        "urls": "https://www.nbcnews.com/business",
+        "urls": ["https://www.nbcnews.com/business"],
         "priority": 5,
         "screenshot": True,
         "crawler_params": {"headless": True},

tests/test_main.py

@@ -54,7 +54,7 @@ class NBCNewsAPITest:
 async def test_basic_crawl():
     print("\n=== Testing Basic Crawl ===")
     async with NBCNewsAPITest() as api:
-        request = {"urls": "https://www.nbcnews.com/business", "priority": 10}
+        request = {"urls": ["https://www.nbcnews.com/business"], "priority": 10}
         task_id = await api.submit_crawl(request)
         result = await api.wait_for_task(task_id)
         print(f"Basic crawl result length: {len(result['result']['markdown'])}")
@@ -67,7 +67,7 @@ async def test_js_execution():
     print("\n=== Testing JS Execution ===")
     async with NBCNewsAPITest() as api:
         request = {
-            "urls": "https://www.nbcnews.com/business",
+            "urls": ["https://www.nbcnews.com/business"],
             "priority": 8,
             "js_code": [
                 "const loadMoreButton = Array.from(document.querySelectorAll('button')).find(button => button.textContent.includes('Load More')); loadMoreButton && loadMoreButton.click();"
@@ -86,7 +86,7 @@ async def test_css_selector():
     print("\n=== Testing CSS Selector ===")
     async with NBCNewsAPITest() as api:
         request = {
-            "urls": "https://www.nbcnews.com/business",
+            "urls": ["https://www.nbcnews.com/business"],
             "priority": 7,
             "css_selector": ".wide-tease-item__description",
         }
@@ -120,7 +120,7 @@ async def test_structured_extraction():
         }
 
         request = {
-            "urls": "https://www.nbcnews.com/business",
+            "urls": ["https://www.nbcnews.com/business"],
             "priority": 9,
             "extraction_config": {"type": "json_css", "params": {"schema": schema}},
         }
@@ -177,7 +177,7 @@ async def test_llm_extraction():
         }
 
         request = {
-            "urls": "https://www.nbcnews.com/business",
+            "urls": ["https://www.nbcnews.com/business"],
             "priority": 8,
             "extraction_config": {
                 "type": "llm",
@@ -209,7 +209,7 @@ async def test_screenshot():
     print("\n=== Testing Screenshot ===")
     async with NBCNewsAPITest() as api:
         request = {
-            "urls": "https://www.nbcnews.com/business",
+            "urls": ["https://www.nbcnews.com/business"],
             "priority": 5,
             "screenshot": True,
             "crawler_params": {"headless": True},
@@ -227,7 +227,7 @@ async def test_priority_handling():
     async with NBCNewsAPITest() as api:
         # Submit low priority task first
         low_priority = {
-            "urls": "https://www.nbcnews.com/business",
+            "urls": ["https://www.nbcnews.com/business"],
             "priority": 1,
             "crawler_params": {"headless": True},
         }
@@ -235,7 +235,7 @@ async def test_priority_handling():
 
         # Submit high priority task
         high_priority = {
-            "urls": "https://www.nbcnews.com/business/consumer",
+            "urls": ["https://www.nbcnews.com/business/consumer"],
             "priority": 10,
             "crawler_params": {"headless": True},
         }

tests/test_normalize_url.py

@@ -0,0 +1,91 @@
+import unittest
+from crawl4ai.utils import normalize_url
+
+class TestNormalizeUrl(unittest.TestCase):
+
+    def test_basic_relative_path(self):
+        self.assertEqual(normalize_url("path/to/page.html", "http://example.com/base/"), "http://example.com/base/path/to/page.html")
+
+    def test_base_url_with_trailing_slash(self):
+        self.assertEqual(normalize_url("page.html", "http://example.com/base/"), "http://example.com/base/page.html")
+
+    def test_base_url_without_trailing_slash(self):
+        # If normalize_url correctly uses urljoin, "base" is treated as a file.
+        self.assertEqual(normalize_url("page.html", "http://example.com/base"), "http://example.com/page.html")
+
+    def test_absolute_url_as_href(self):
+        self.assertEqual(normalize_url("http://another.com/page.html", "http://example.com/"), "http://another.com/page.html")
+
+    def test_href_with_leading_trailing_spaces(self):
+        self.assertEqual(normalize_url("  page.html  ", "http://example.com/"), "http://example.com/page.html")
+
+    def test_empty_href(self):
+        # urljoin with an empty href and base ending in '/' returns the base.
+        self.assertEqual(normalize_url("", "http://example.com/base/"), "http://example.com/base/")
+        # urljoin with an empty href and base not ending in '/' also returns base.
+        self.assertEqual(normalize_url("", "http://example.com/base"), "http://example.com/base")
+
+    def test_href_with_query_parameters(self):
+        self.assertEqual(normalize_url("page.html?query=test", "http://example.com/"), "http://example.com/page.html?query=test")
+
+    def test_href_with_fragment(self):
+        self.assertEqual(normalize_url("page.html#section", "http://example.com/"), "http://example.com/page.html#section")
+
+    def test_different_scheme_in_href(self):
+        self.assertEqual(normalize_url("https://secure.example.com/page.html", "http://example.com/"), "https://secure.example.com/page.html")
+
+    def test_parent_directory_in_href(self):
+        self.assertEqual(normalize_url("../otherpage.html", "http://example.com/base/current/"), "http://example.com/base/otherpage.html")
+
+    def test_root_relative_href(self):
+        self.assertEqual(normalize_url("/otherpage.html", "http://example.com/base/current/"), "http://example.com/otherpage.html")
+
+    def test_base_url_with_path_and_no_trailing_slash(self):
+        # If normalize_url correctly uses urljoin, "path" is treated as a file.
+        self.assertEqual(normalize_url("file.html", "http://example.com/path"), "http://example.com/file.html")
+
+    def test_base_url_is_just_domain(self):
+        self.assertEqual(normalize_url("page.html", "http://example.com"), "http://example.com/page.html")
+
+    def test_href_is_only_query(self):
+        self.assertEqual(normalize_url("?query=true", "http://example.com/page.html"), "http://example.com/page.html?query=true")
+
+    def test_href_is_only_fragment(self):
+        self.assertEqual(normalize_url("#fragment", "http://example.com/page.html"), "http://example.com/page.html#fragment")
+
+    def test_relative_link_from_base_file_url(self):
+        """
+        Tests the specific bug report: relative links from a base URL that is a file.
+        Example:
+        Page URL: http://example.com/path/to/document.html
+        Link on page: <a href="./file.xlsx">
+        Expected: http://example.com/path/to/file.xlsx
+        """
+        base_url_file = "http://example.com/zwgk/fdzdgk/zdxx/spaq/t19360680.shtml"
+        href_relative_current_dir = "./P020241203375994691134.xlsx"
+        expected_url1 = "http://example.com/zwgk/fdzdgk/zdxx/spaq/P020241203375994691134.xlsx"
+        self.assertEqual(normalize_url(href_relative_current_dir, base_url_file), expected_url1)
+
+        # Test with a relative link that doesn't start with "./"
+        href_relative_no_dot_slash = "another.doc"
+        expected_url2 = "http://example.com/zwgk/fdzdgk/zdxx/spaq/another.doc"
+        self.assertEqual(normalize_url(href_relative_no_dot_slash, base_url_file), expected_url2)
+
+    def test_invalid_base_url_scheme(self):
+        with self.assertRaises(ValueError) as context:
+            normalize_url("page.html", "ftp://example.com/")
+        self.assertIn("Invalid base URL format", str(context.exception))
+
+    def test_invalid_base_url_netloc(self):
+        with self.assertRaises(ValueError) as context:
+            normalize_url("page.html", "http:///path/")
+        self.assertIn("Invalid base URL format", str(context.exception))
+        
+    def test_base_url_with_port(self):
+        self.assertEqual(normalize_url("path/file.html", "http://example.com:8080/base/"), "http://example.com:8080/base/path/file.html")
+
+    def test_href_with_special_characters(self):
+        self.assertEqual(normalize_url("path%20with%20spaces/file.html", "http://example.com/"), "http://example.com/path%20with%20spaces/file.html")
+
+if __name__ == '__main__':
+    unittest.main()