letta-nightly 0.8.10.dev20250707035305__tar.gz → 0.8.11.dev20250708000504__tar.gz

{letta_nightly-0.8.10.dev20250707035305 → letta_nightly-0.8.11.dev20250708000504}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: letta-nightly
-Version: 0.8.10.dev20250707035305
+Version: 0.8.11.dev20250708000504
 Summary: Create LLM agents with long-term memory and custom tools
 License: Apache License
 Author: Letta Team

{letta_nightly-0.8.10.dev20250707035305 → letta_nightly-0.8.11.dev20250708000504}/letta/__init__.py

@@ -5,7 +5,7 @@ try:
     __version__ = version("letta")
 except PackageNotFoundError:
     # Fallback for development installations
-    __version__ = "0.8.10"
+    __version__ = "0.8.11"
 
 
 if os.environ.get("LETTA_VERSION"):

{letta_nightly-0.8.10.dev20250707035305 → letta_nightly-0.8.11.dev20250708000504}/letta/constants.py

@@ -371,3 +371,4 @@ PINECONE_TEXT_FIELD_NAME = "chunk_text"
 PINECONE_METRIC = "cosine"
 PINECONE_CLOUD = "aws"
 PINECONE_REGION = "us-east-1"
+PINECONE_MAX_BATCH_SIZE = 96

{letta_nightly-0.8.10.dev20250707035305 → letta_nightly-0.8.11.dev20250708000504}/letta/helpers/pinecone_utils.py

@@ -2,7 +2,14 @@ from typing import Any, Dict, List
 
 from pinecone import PineconeAsyncio
 
-from letta.constants import PINECONE_CLOUD, PINECONE_EMBEDDING_MODEL, PINECONE_METRIC, PINECONE_REGION, PINECONE_TEXT_FIELD_NAME
+from letta.constants import (
+    PINECONE_CLOUD,
+    PINECONE_EMBEDDING_MODEL,
+    PINECONE_MAX_BATCH_SIZE,
+    PINECONE_METRIC,
+    PINECONE_REGION,
+    PINECONE_TEXT_FIELD_NAME,
+)
 from letta.log import get_logger
 from letta.schemas.user import User
 from letta.settings import settings
@@ -90,7 +97,10 @@ async def upsert_records_to_pinecone_index(records: List[dict], actor: User):
     async with PineconeAsyncio(api_key=settings.pinecone_api_key) as pc:
         description = await pc.describe_index(name=settings.pinecone_source_index)
         async with pc.IndexAsyncio(host=description.index.host) as dense_index:
-            await dense_index.upsert_records(actor.organization_id, records)
+            # Process records in batches to avoid exceeding Pinecone limits
+            for i in range(0, len(records), PINECONE_MAX_BATCH_SIZE):
+                batch = records[i : i + PINECONE_MAX_BATCH_SIZE]
+                await dense_index.upsert_records(actor.organization_id, batch)
 
 
 async def search_pinecone_index(query: str, limit: int, filter: Dict[str, Any], actor: User) -> Dict[str, Any]:

{letta_nightly-0.8.10.dev20250707035305 → letta_nightly-0.8.11.dev20250708000504}/letta/jobs/scheduler.py

@@ -4,10 +4,11 @@ from typing import Optional
 
 from apscheduler.schedulers.asyncio import AsyncIOScheduler
 from apscheduler.triggers.interval import IntervalTrigger
+from sqlalchemy import text
 
 from letta.jobs.llm_batch_job_polling import poll_running_llm_batches
 from letta.log import get_logger
-from letta.server.db import db_context
+from letta.server.db import db_registry
 from letta.server.server import SyncServer
 from letta.settings import settings
 
@@ -16,68 +17,54 @@ scheduler = AsyncIOScheduler()
 logger = get_logger(__name__)
 ADVISORY_LOCK_KEY = 0x12345678ABCDEF00
 
-_advisory_lock_conn = None  # Holds the raw DB connection if leader
-_advisory_lock_cur = None  # Holds the cursor for the lock connection if leader
+_advisory_lock_session = None  # Holds the async session if leader
 _lock_retry_task: Optional[asyncio.Task] = None  # Background task handle for non-leaders
 _is_scheduler_leader = False  # Flag indicating if this instance runs the scheduler
 
 
 async def _try_acquire_lock_and_start_scheduler(server: SyncServer) -> bool:
     """Attempts to acquire lock, starts scheduler if successful."""
-    global _advisory_lock_conn, _advisory_lock_cur, _is_scheduler_leader, scheduler
+    global _advisory_lock_session, _is_scheduler_leader, scheduler
 
     if _is_scheduler_leader:
         return True  # Already leading
 
-    raw_conn = None
-    cur = None
+    lock_session = None
     acquired_lock = False
     try:
-        # Use a temporary connection context for the attempt initially
-        with db_context() as session:
+        async with db_registry.async_session() as session:
             engine = session.get_bind()
             engine_name = engine.name
             logger.info(f"Database engine type: {engine_name}")
-
             if engine_name != "postgresql":
                 logger.warning(f"Advisory locks not supported for {engine_name} database. Starting scheduler without leader election.")
-                acquired_lock = True  # For SQLite, assume we can start the scheduler
+                acquired_lock = True
             else:
-                # Get raw connection - MUST be kept open if lock is acquired
-                raw_conn = engine.raw_connection()
-                cur = raw_conn.cursor()
-
-                cur.execute("SELECT pg_try_advisory_lock(CAST(%s AS bigint))", (ADVISORY_LOCK_KEY,))
-                acquired_lock = cur.fetchone()[0]
+                lock_session = db_registry.get_async_session_factory()()
+                result = await lock_session.execute(
+                    text("SELECT pg_try_advisory_lock(CAST(:lock_key AS bigint))"), {"lock_key": ADVISORY_LOCK_KEY}
+                )
+                acquired_lock = result.scalar()
 
         if not acquired_lock:
-            if cur:
-                cur.close()
-            if raw_conn:
-                raw_conn.close()
+            if lock_session:
+                await lock_session.close()
             logger.info("Scheduler lock held by another instance.")
             return False
 
-        # --- Lock Acquired ---
         if engine_name == "postgresql":
             logger.info("Acquired PostgreSQL advisory lock.")
-            _advisory_lock_conn = raw_conn  # Keep connection for lock duration
-            _advisory_lock_cur = cur  # Keep cursor for lock duration
-            raw_conn = None  # Prevent closing in finally block
-            cur = None  # Prevent closing in finally block
+            _advisory_lock_session = lock_session
+            lock_session = None
         else:
             logger.info("Starting scheduler for non-PostgreSQL database.")
-            # For SQLite, we don't need to keep the connection open
-            if cur:
-                cur.close()
-            if raw_conn:
-                raw_conn.close()
-            raw_conn = None
-            cur = None
+            if lock_session:
+                await lock_session.close()
+            lock_session = None
 
         trigger = IntervalTrigger(
             seconds=settings.poll_running_llm_batches_interval_seconds,
-            jitter=10,  # Jitter for the job execution
+            jitter=10,
         )
         scheduler.add_job(
             poll_running_llm_batches,
@@ -91,7 +78,7 @@ async def _try_acquire_lock_and_start_scheduler(server: SyncServer) -> bool:
 
         if not scheduler.running:
             scheduler.start()
-        elif scheduler.state == 2:  # PAUSED
+        elif scheduler.state == 2:
             scheduler.resume()
 
         _is_scheduler_leader = True
@@ -99,38 +86,27 @@ async def _try_acquire_lock_and_start_scheduler(server: SyncServer) -> bool:
 
     except Exception as e:
         logger.error(f"Error during lock acquisition/scheduler start: {e}", exc_info=True)
-        if acquired_lock:  # If lock was acquired before error, try to release
+        if acquired_lock:
             logger.warning("Attempting to release lock due to error during startup.")
             try:
-                # Use the cursor/connection we were about to store
-                _advisory_lock_cur = cur
-                _advisory_lock_conn = raw_conn
-                await _release_advisory_lock()  # Attempt cleanup
+                _advisory_lock_session = lock_session
+                await _release_advisory_lock()
             except Exception as unlock_err:
                 logger.error(f"Failed to release lock during error handling: {unlock_err}", exc_info=True)
             finally:
-                # Ensure globals are cleared after failed attempt
-                _advisory_lock_cur = None
-                _advisory_lock_conn = None
+                _advisory_lock_session = None
                 _is_scheduler_leader = False
 
-        # Ensure scheduler is stopped if we failed partially
         if scheduler.running:
             try:
                 scheduler.shutdown(wait=False)
             except:
-                pass  # Best effort
+                pass
         return False
     finally:
-        # Clean up temporary resources if lock wasn't acquired or error occurred before storing
-        if cur:
-            try:
-                cur.close()
-            except:
-                pass
-        if raw_conn:
+        if lock_session:
             try:
-                raw_conn.close()
+                await lock_session.close()
             except:
                 pass
 
@@ -141,63 +117,50 @@ async def _background_lock_retry_loop(server: SyncServer):
     logger.info("Starting background task to periodically check for scheduler lock.")
 
     while True:
-        if _is_scheduler_leader:  # Should be cancelled first, but safety check
+        if _is_scheduler_leader:
             break
         try:
             wait_time = settings.poll_lock_retry_interval_seconds
             await asyncio.sleep(wait_time)
 
-            # Re-check state before attempting lock
             if _is_scheduler_leader or _lock_retry_task is None:
-                break  # Stop if became leader or task was cancelled
+                break
 
             acquired = await _try_acquire_lock_and_start_scheduler(server)
             if acquired:
                 logger.info("Background task acquired lock and started scheduler.")
-                _lock_retry_task = None  # Clear self handle
-                break  # Exit loop, we are now the leader
+                _lock_retry_task = None
+                break
 
         except asyncio.CancelledError:
             logger.info("Background lock retry task cancelled.")
             break
         except Exception as e:
             logger.error(f"Error in background lock retry loop: {e}", exc_info=True)
-            # Avoid tight loop on persistent errors
             await asyncio.sleep(settings.poll_lock_retry_interval_seconds)
 
 
 async def _release_advisory_lock():
-    """Releases the advisory lock using the stored connection."""
-    global _advisory_lock_conn, _advisory_lock_cur
+    """Releases the advisory lock using the stored session."""
+    global _advisory_lock_session
 
-    lock_cur = _advisory_lock_cur
-    lock_conn = _advisory_lock_conn
-    _advisory_lock_cur = None  # Clear global immediately
-    _advisory_lock_conn = None  # Clear global immediately
+    lock_session = _advisory_lock_session
+    _advisory_lock_session = None
 
-    if lock_cur is not None and lock_conn is not None:
+    if lock_session is not None:
         logger.info(f"Attempting to release PostgreSQL advisory lock {ADVISORY_LOCK_KEY}")
         try:
-            # Try to execute unlock - connection/cursor validity is checked by attempting the operation
-            lock_cur.execute("SELECT pg_advisory_unlock(CAST(%s AS bigint))", (ADVISORY_LOCK_KEY,))
-            lock_cur.fetchone()  # Consume result
-            lock_conn.commit()
+            await lock_session.execute(text("SELECT pg_advisory_unlock(CAST(:lock_key AS bigint))"), {"lock_key": ADVISORY_LOCK_KEY})
             logger.info(f"Executed pg_advisory_unlock for lock {ADVISORY_LOCK_KEY}")
         except Exception as e:
             logger.error(f"Error executing pg_advisory_unlock: {e}", exc_info=True)
         finally:
-            # Ensure resources are closed regardless of unlock success
-            try:
-                if lock_cur:
-                    lock_cur.close()
-            except Exception as e:
-                logger.error(f"Error closing advisory lock cursor: {e}", exc_info=True)
             try:
-                if lock_conn:
-                    lock_conn.close()
-                logger.info("Closed database connection that held advisory lock.")
+                if lock_session:
+                    await lock_session.close()
+                logger.info("Closed database session that held advisory lock.")
             except Exception as e:
-                logger.error(f"Error closing advisory lock connection: {e}", exc_info=True)
+                logger.error(f"Error closing advisory lock session: {e}", exc_info=True)
     else:
         logger.info("No PostgreSQL advisory lock to release (likely using SQLite or non-PostgreSQL database).")
 
@@ -220,7 +183,6 @@ async def start_scheduler_with_leader_election(server: SyncServer):
     acquired_immediately = await _try_acquire_lock_and_start_scheduler(server)
 
     if not acquired_immediately and _lock_retry_task is None:
-        # Failed initial attempt, start background retry task
         loop = asyncio.get_running_loop()
         _lock_retry_task = loop.create_task(_background_lock_retry_loop(server))
 
@@ -232,48 +194,40 @@ async def shutdown_scheduler_and_release_lock():
     """
     global _is_scheduler_leader, _lock_retry_task, scheduler
 
-    # 1. Cancel retry task if running (for non-leaders)
     if _lock_retry_task is not None:
         logger.info("Shutting down: Cancelling background lock retry task.")
         current_task = _lock_retry_task
-        _lock_retry_task = None  # Clear handle first
+        _lock_retry_task = None
         current_task.cancel()
         try:
-            await current_task  # Wait for cancellation
+            await current_task
         except asyncio.CancelledError:
             logger.info("Background lock retry task successfully cancelled.")
         except Exception as e:
             logger.warning(f"Exception waiting for cancelled retry task: {e}", exc_info=True)
 
-    # 2. Shutdown scheduler and release lock if we were the leader
     if _is_scheduler_leader:
         logger.info("Shutting down: Leader instance stopping scheduler and releasing lock.")
         if scheduler.running:
             try:
-                # Force synchronous shutdown to prevent callback scheduling
                 scheduler.shutdown(wait=True)
 
-                # wait for any internal cleanup to complete
                 await asyncio.sleep(0.1)
 
                 logger.info("APScheduler shut down.")
             except Exception as e:
-                # Handle SchedulerNotRunningError and other shutdown exceptions
                 logger.warning(f"Exception during APScheduler shutdown: {e}")
                 if "not running" not in str(e).lower():
                     logger.error(f"Unexpected error shutting down APScheduler: {e}", exc_info=True)
 
         await _release_advisory_lock()
-        _is_scheduler_leader = False  # Update state after cleanup
+        _is_scheduler_leader = False
     else:
         logger.info("Shutting down: Non-leader instance.")
 
-    # Final cleanup check for scheduler state (belt and suspenders)
-    # This should rarely be needed if shutdown logic above worked correctly
     try:
         if scheduler.running:
             logger.warning("Scheduler still running after shutdown logic completed? Forcing shutdown.")
             scheduler.shutdown(wait=False)
     except Exception as e:
-        # Catch SchedulerNotRunningError and other shutdown exceptions
         logger.debug(f"Expected exception during final scheduler cleanup: {e}")

letta_nightly-0.8.11.dev20250708000504/letta/schemas/source_metadata.py

@@ -0,0 +1,32 @@
+from typing import List, Optional
+
+from pydantic import Field
+
+from letta.schemas.letta_base import LettaBase
+
+
+class FileStats(LettaBase):
+    """File statistics for metadata endpoint"""
+
+    file_id: str = Field(..., description="Unique identifier of the file")
+    file_name: str = Field(..., description="Name of the file")
+    file_size: Optional[int] = Field(None, description="Size of the file in bytes")
+
+
+class SourceStats(LettaBase):
+    """Aggregated metadata for a source"""
+
+    source_id: str = Field(..., description="Unique identifier of the source")
+    source_name: str = Field(..., description="Name of the source")
+    file_count: int = Field(0, description="Number of files in the source")
+    total_size: int = Field(0, description="Total size of all files in bytes")
+    files: List[FileStats] = Field(default_factory=list, description="List of file statistics")
+
+
+class OrganizationSourcesStats(LettaBase):
+    """Complete metadata response for organization sources"""
+
+    total_sources: int = Field(0, description="Total number of sources")
+    total_files: int = Field(0, description="Total number of files across all sources")
+    total_size: int = Field(0, description="Total size of all files in bytes")
+    sources: List[SourceStats] = Field(default_factory=list, description="List of source metadata")

{letta_nightly-0.8.10.dev20250707035305 → letta_nightly-0.8.11.dev20250708000504}/letta/server/db.py

@@ -226,6 +226,32 @@ class DatabaseRegistry:
     @contextmanager
     def session(self, name: str = "default") -> Generator[Any, None, None]:
         """Context manager for database sessions."""
+        caller_info = "unknown caller"
+        try:
+            import inspect
+
+            frame = inspect.currentframe()
+            stack = inspect.getouterframes(frame)
+
+            for i, frame_info in enumerate(stack):
+                module = inspect.getmodule(frame_info.frame)
+                module_name = module.__name__ if module else "unknown"
+
+                if module_name != "contextlib" and "db.py" not in frame_info.filename:
+                    caller_module = module_name
+                    caller_function = frame_info.function
+                    caller_lineno = frame_info.lineno
+                    caller_file = frame_info.filename.split("/")[-1]
+
+                    caller_info = f"{caller_module}.{caller_function}:{caller_lineno} ({caller_file})"
+                    break
+        except:
+            pass
+        finally:
+            del frame
+
+        self.session_caller_trace(caller_info)
+
         session_factory = self.get_session_factory(name)
         if not session_factory:
             raise ValueError(f"No session factory found for '{name}'")
@@ -250,6 +276,11 @@ class DatabaseRegistry:
         finally:
             await session.close()
 
+    @trace_method
+    def session_caller_trace(self, caller_info: str):
+        """Trace sync db caller information for debugging purposes."""
+        pass  # wrapper used for otel tracing only
+
 
 # Create a singleton instance
 db_registry = DatabaseRegistry()

{letta_nightly-0.8.10.dev20250707035305 → letta_nightly-0.8.11.dev20250708000504}/letta/server/rest_api/routers/v1/sources.py

@@ -23,10 +23,10 @@ from letta.schemas.enums import FileProcessingStatus
 from letta.schemas.file import FileMetadata
 from letta.schemas.passage import Passage
 from letta.schemas.source import Source, SourceCreate, SourceUpdate
+from letta.schemas.source_metadata import OrganizationSourcesStats
 from letta.schemas.user import User
 from letta.server.rest_api.utils import get_letta_server
 from letta.server.server import SyncServer
-from letta.services.file_processor.chunker.llama_index_chunker import LlamaIndexChunker
 from letta.services.file_processor.embedder.openai_embedder import OpenAIEmbedder
 from letta.services.file_processor.embedder.pinecone_embedder import PineconeEmbedder
 from letta.services.file_processor.file_processor import FileProcessor
@@ -95,6 +95,24 @@ async def get_source_id_by_name(
     return source.id
 
 
+@router.get("/metadata", response_model=OrganizationSourcesStats, operation_id="get_sources_metadata")
+async def get_sources_metadata(
+    server: "SyncServer" = Depends(get_letta_server),
+    actor_id: Optional[str] = Header(None, alias="user_id"),
+):
+    """
+    Get aggregated metadata for all sources in an organization.
+
+    Returns structured metadata including:
+    - Total number of sources
+    - Total number of files across all sources
+    - Total size of all files
+    - Per-source breakdown with file details (file_name, file_size per file)
+    """
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    return await server.file_manager.get_organization_sources_metadata(actor=actor)
+
+
 @router.get("/", response_model=List[Source], operation_id="list_sources")
 async def list_sources(
     server: "SyncServer" = Depends(get_letta_server),
@@ -344,7 +362,9 @@ async def get_file_metadata(
 
     if should_use_pinecone() and not file_metadata.is_processing_terminal():
         ids = await list_pinecone_index_for_files(file_id=file_id, actor=actor, limit=file_metadata.total_chunks)
-        logger.info(f"Embedded chunks {len(ids)}/{file_metadata.total_chunks} for {file_id} in organization {actor.organization_id}")
+        logger.info(
+            f"Embedded chunks {len(ids)}/{file_metadata.total_chunks} for {file_id} ({file_metadata.file_name}) in organization {actor.organization_id}"
+        )
 
         if len(ids) != file_metadata.chunks_embedded or len(ids) == file_metadata.total_chunks:
             if len(ids) != file_metadata.total_chunks:
@@ -424,15 +444,12 @@ async def load_file_to_source_cloud(
     file_metadata: FileMetadata,
 ):
     file_processor = MistralFileParser()
-    text_chunker = LlamaIndexChunker(chunk_size=embedding_config.embedding_chunk_size)
     using_pinecone = should_use_pinecone()
     if using_pinecone:
         embedder = PineconeEmbedder()
     else:
         embedder = OpenAIEmbedder(embedding_config=embedding_config)
-    file_processor = FileProcessor(
-        file_parser=file_processor, text_chunker=text_chunker, embedder=embedder, actor=actor, using_pinecone=using_pinecone
-    )
+    file_processor = FileProcessor(file_parser=file_processor, embedder=embedder, actor=actor, using_pinecone=using_pinecone)
     await file_processor.process(
         server=server, agent_states=agent_states, source_id=source_id, content=content, file_metadata=file_metadata
     )

{letta_nightly-0.8.10.dev20250707035305 → letta_nightly-0.8.11.dev20250708000504}/letta/services/file_manager.py

@@ -16,6 +16,7 @@ from letta.otel.tracing import trace_method
 from letta.schemas.enums import FileProcessingStatus
 from letta.schemas.file import FileMetadata as PydanticFileMetadata
 from letta.schemas.source import Source as PydanticSource
+from letta.schemas.source_metadata import FileStats, OrganizationSourcesStats, SourceStats
 from letta.schemas.user import User as PydanticUser
 from letta.server.db import db_registry
 from letta.utils import enforce_types
@@ -272,3 +273,72 @@ class FileManager:
             else:
                 # Add numeric suffix
                 return f"{source.name}/{base}_({count}){ext}"
+
+    @enforce_types
+    @trace_method
+    async def get_organization_sources_metadata(self, actor: PydanticUser) -> OrganizationSourcesStats:
+        """
+        Get aggregated metadata for all sources in an organization with optimized queries.
+
+        Returns structured metadata including:
+        - Total number of sources
+        - Total number of files across all sources
+        - Total size of all files
+        - Per-source breakdown with file details
+        """
+        async with db_registry.async_session() as session:
+            # Import here to avoid circular imports
+            from letta.orm.source import Source as SourceModel
+
+            # Single optimized query to get all sources with their file aggregations
+            query = (
+                select(
+                    SourceModel.id,
+                    SourceModel.name,
+                    func.count(FileMetadataModel.id).label("file_count"),
+                    func.coalesce(func.sum(FileMetadataModel.file_size), 0).label("total_size"),
+                )
+                .outerjoin(FileMetadataModel, (FileMetadataModel.source_id == SourceModel.id) & (FileMetadataModel.is_deleted == False))
+                .where(SourceModel.organization_id == actor.organization_id)
+                .where(SourceModel.is_deleted == False)
+                .group_by(SourceModel.id, SourceModel.name)
+                .order_by(SourceModel.name)
+            )
+
+            result = await session.execute(query)
+            source_aggregations = result.fetchall()
+
+            # Build response
+            metadata = OrganizationSourcesStats()
+
+            for row in source_aggregations:
+                source_id, source_name, file_count, total_size = row
+
+                # Get individual file details for this source
+                files_query = (
+                    select(FileMetadataModel.id, FileMetadataModel.file_name, FileMetadataModel.file_size)
+                    .where(
+                        FileMetadataModel.source_id == source_id,
+                        FileMetadataModel.organization_id == actor.organization_id,
+                        FileMetadataModel.is_deleted == False,
+                    )
+                    .order_by(FileMetadataModel.file_name)
+                )
+
+                files_result = await session.execute(files_query)
+                files_rows = files_result.fetchall()
+
+                # Build file stats
+                files = [FileStats(file_id=file_row[0], file_name=file_row[1], file_size=file_row[2]) for file_row in files_rows]
+
+                # Build source metadata
+                source_metadata = SourceStats(
+                    source_id=source_id, source_name=source_name, file_count=file_count, total_size=total_size, files=files
+                )
+
+                metadata.sources.append(source_metadata)
+                metadata.total_files += file_count
+                metadata.total_size += total_size
+
+            metadata.total_sources = len(metadata.sources)
+            return metadata

{letta_nightly-0.8.10.dev20250707035305 → letta_nightly-0.8.11.dev20250708000504}/letta/services/file_processor/chunker/line_chunker.py

@@ -99,7 +99,12 @@ class LineChunker:
         return [line for line in lines if line.strip()]
 
     def chunk_text(
-        self, file_metadata: FileMetadata, start: Optional[int] = None, end: Optional[int] = None, add_metadata: bool = True
+        self,
+        file_metadata: FileMetadata,
+        start: Optional[int] = None,
+        end: Optional[int] = None,
+        add_metadata: bool = True,
+        validate_range: bool = False,
     ) -> List[str]:
         """Content-aware text chunking based on file type"""
         strategy = self._determine_chunking_strategy(file_metadata)
@@ -116,11 +121,31 @@ class LineChunker:
             content_lines = self._chunk_by_lines(text, preserve_indentation=False)
 
         total_chunks = len(content_lines)
+        chunk_type = (
+            "sentences" if strategy == ChunkingStrategy.DOCUMENTATION else "chunks" if strategy == ChunkingStrategy.PROSE else "lines"
+        )
+
+        # Validate range if requested
+        if validate_range and (start is not None or end is not None):
+            if start is not None and start >= total_chunks:
+                # Convert to 1-indexed for user-friendly error message
+                start_display = start + 1
+                raise ValueError(
+                    f"File {file_metadata.file_name} has only {total_chunks} lines, but requested offset {start_display} is out of range"
+                )
+
+            if start is not None and end is not None and end > total_chunks:
+                # Convert to 1-indexed for user-friendly error message
+                start_display = start + 1
+                end_display = end
+                raise ValueError(
+                    f"File {file_metadata.file_name} has only {total_chunks} lines, but requested range {start_display} to {end_display} extends beyond file bounds"
+                )
 
         # Handle start/end slicing
-        if start is not None and end is not None:
+        if start is not None or end is not None:
             content_lines = content_lines[start:end]
-            line_offset = start
+            line_offset = start if start is not None else 0
         else:
             line_offset = 0
 
@@ -129,14 +154,15 @@ class LineChunker:
 
         # Add metadata about total chunks
         if add_metadata:
-            chunk_type = (
-                "sentences" if strategy == ChunkingStrategy.DOCUMENTATION else "chunks" if strategy == ChunkingStrategy.PROSE else "lines"
-            )
             if start is not None and end is not None:
                 # Display 1-indexed ranges for users
                 start_display = start + 1
                 end_display = end
                 content_lines.insert(0, f"[Viewing {chunk_type} {start_display} to {end_display} (out of {total_chunks} {chunk_type})]")
+            elif start is not None:
+                # Only start specified - viewing from start to end
+                start_display = start + 1
+                content_lines.insert(0, f"[Viewing {chunk_type} {start_display} to end (out of {total_chunks} {chunk_type})]")
             else:
                 content_lines.insert(0, f"[Viewing file start (out of {total_chunks} {chunk_type})]")