agno 2.4.5__tar.gz → 2.4.6__tar.gz

{agno-2.4.5 → agno-2.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agno
-Version: 2.4.5
+Version: 2.4.6
 Summary: Agno: a lightweight library for building Multi-Agent Systems
 Author-email: Ashpreet Bedi <ashpreet@agno.com>
 Project-URL: homepage, https://agno.com
@@ -266,7 +266,7 @@ Provides-Extra: excel
 Requires-Dist: openpyxl; extra == "excel"
 Requires-Dist: xlrd; extra == "excel"
 Provides-Extra: markdown
-Requires-Dist: unstructured; extra == "markdown"
+Requires-Dist: unstructured<0.18.31; extra == "markdown"
 Requires-Dist: markdown; extra == "markdown"
 Requires-Dist: aiofiles; extra == "markdown"
 Provides-Extra: chonkie
@@ -445,7 +445,7 @@ Dynamic: license-file
 </div>
 
 <p align="center">
-  Build, run, manage multi-agent systems.
+  Build agents that learn.
 </p>
 
 <div align="center">
@@ -460,68 +460,58 @@ Dynamic: license-file
 
 ## What is Agno?
 
-Agno is a framework, runtime, and control plane for multi-agent systems.
+**A Python SDK for building agents that learn and improve with every interaction.**
 
-| Layer | What it does |
-|-------|--------------|
-| **Framework** | Build agents, teams, and workflows with memory, knowledge, guardrails, and 100+ integrations |
-| **AgentOS Runtime** | Run your system in production with a stateless, secure FastAPI backend |
-| **Control Plane** | Test, monitor, and manage your system using the [AgentOS UI](https://os.agno.com) |
+Most agents are stateless. They reason, respond, forget. Session history helps, but they're exactly as capable on day 1000 as they were on day 1.
 
-## Why Agno?
+Agno agents are different. They remember users across sessions, accumulate knowledge across conversations, and learn from decisions. Insights from one user benefit everyone.
 
-- **Private by design.** AgentOS runs in your cloud. The control plane connects directly to your runtime from your browser. No retention costs, no vendor lock-in, no compliance headaches.
-- **Production-ready on day one.** Pre-built FastAPI runtime with SSE endpoints, ready to deploy.
-- **Fast.** 529× faster instantiation than LangGraph. 24× lower memory. [See benchmarks →](#performance)
+Everything runs in your cloud. Your data never leaves your environment.
 
-## Example
-
-An agent with MCP tools, persistent state, served via FastAPI:
+## Quick Example
 ```python
 from agno.agent import Agent
 from agno.db.sqlite import SqliteDb
-from agno.models.anthropic import Claude
-from agno.os import AgentOS
-from agno.tools.mcp import MCPTools
+from agno.models.openai import OpenAIResponses
 
-agno_agent = Agent(
-    name="Agno Agent",
-    model=Claude(id="claude-sonnet-4-5"),
-    db=SqliteDb(db_file="agno.db"),
-    tools=[MCPTools(transport="streamable-http", url="https://docs.agno.com/mcp")],
-    add_history_to_context=True,
-    markdown=True,
+agent = Agent(
+    model=OpenAIResponses(id="gpt-5.2"),
+    db=SqliteDb(db_file="tmp/agents.db"),
+    learning=True,
 )
-
-agent_os = AgentOS(agents=[agno_agent])
-app = agent_os.get_app()
-
-if __name__ == "__main__":
-    agent_os.serve(app="agno_agent:app", reload=True)
 ```
 
-Run this and connect to the [AgentOS UI](https://os.agno.com):
+One line. Your agent now remembers users, accumulates knowledge, and improves over time.
+
+## Production Stack
 
-https://github.com/user-attachments/assets/feb23db8-15cc-4e88-be7c-01a21a03ebf6
+| Layer | What it does |
+|-------|--------------|
+| **SDK** | Build agents with learning, tools, knowledge, and guardrails |
+| **Runtime** | Run in production using [AgentOS](https://docs.agno.com/agent-os/introduction) |
+| **Control Plane** | Monitor and manage via the [AgentOS UI](https://os.agno.com) |
 
 ## Features
 
+**Learning**
+- User profiles that persist across sessions
+- User memories that accumulate over time
+- Learned knowledge that transfers across users
+- Always or agentic learning modes
+
 **Core**
 - Model-agnostic: OpenAI, Anthropic, Google, local models
 - Type-safe I/O with `input_schema` and `output_schema`
 - Async-first, built for long-running tasks
 - Natively multimodal (text, images, audio, video, files)
 
-**Memory & Knowledge**
-- Persistent storage for session history and state
-- User memory across sessions
+**Knowledge**
 - Agentic RAG with 20+ vector stores, hybrid search, reranking
-- Culture: shared long-term memory across agents
+- Persistent storage for session history and state
 
 **Orchestration**
 - Human-in-the-loop (confirmations, approvals, overrides)
 - Guardrails for validation and security
-- Pre/post hooks for the agent lifecycle
 - First-class MCP and A2A support
 - 100+ built-in toolkits
 
@@ -529,27 +519,12 @@ https://github.com/user-attachments/assets/feb23db8-15cc-4e88-be7c-01a21a03ebf6
 - Ready-to-use FastAPI runtime
 - Integrated control plane UI
 - Evals for accuracy, performance, latency
-- Durable execution for resumable workflows
-- RBAC and per-agent permissions
 
 ## Getting Started
 
-1. Follow the [quickstart guide](https://github.com/agno-agi/agno/tree/main/cookbook/00_quickstart)
-2. Browse the [cookbook](https://github.com/agno-agi/agno/tree/main/cookbook) for real-world examples
-3. Read the [docs](https://docs.agno.com) to go deeper
-
-## Performance
-
-Agent workloads spawn hundreds of instances. Stateless, horizontal scalability isn't optional.
-
-| Metric | Agno | LangGraph | PydanticAI | CrewAI |
-|--------|------|-----------|------------|--------|
-| Instantiation | **3μs** | 1,587μs (529×) | 170μs (57×) | 210μs (70×) |
-| Memory | **6.6 KiB** | 161 KiB (24×) | 29 KiB (4×) | 66 KiB (10×) |
-
-<sub>Apple M4 MacBook Pro, Oct 2025. [Run benchmarks yourself →](https://github.com/agno-agi/agno/tree/main/cookbook/12_evals/performance)</sub>
-
-https://github.com/user-attachments/assets/54b98576-1859-4880-9f2d-15e1a426719d
+1. Follow the [quickstart](https://docs.agno.com/get-started/quickstart)
+2. Browse the [cookbook](https://github.com/agno-agi/agno/tree/main/cookbook)
+3. Read the [docs](https://docs.agno.com)
 
 ## IDE Integration
 
@@ -561,7 +536,7 @@ Also works with VSCode, Windsurf, and similar tools.
 
 ## Contributing
 
-We welcome contributions. See the [contributing guide](https://github.com/agno-agi/agno/blob/v2.0/CONTRIBUTING.md).
+See the [contributing guide](https://github.com/agno-agi/agno/blob/v2.0/CONTRIBUTING.md).
 
 ## Telemetry
 

agno-2.4.6/README.md

@@ -0,0 +1,109 @@
+<div align="center" id="top">
+  <a href="https://agno.com">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://agno-public.s3.us-east-1.amazonaws.com/assets/logo-dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset="https://agno-public.s3.us-east-1.amazonaws.com/assets/logo-light.svg">
+      <img src="https://agno-public.s3.us-east-1.amazonaws.com/assets/logo-light.svg" alt="Agno">
+    </picture>
+  </a>
+</div>
+
+<p align="center">
+  Build agents that learn.
+</p>
+
+<div align="center">
+  <a href="https://docs.agno.com">Docs</a>
+  <span>&nbsp;•&nbsp;</span>
+  <a href="https://github.com/agno-agi/agno/tree/main/cookbook">Cookbook</a>
+  <span>&nbsp;•&nbsp;</span>
+  <a href="https://community.agno.com/">Community</a>
+  <span>&nbsp;•&nbsp;</span>
+  <a href="https://www.agno.com/discord">Discord</a>
+</div>
+
+## What is Agno?
+
+**A Python SDK for building agents that learn and improve with every interaction.**
+
+Most agents are stateless. They reason, respond, forget. Session history helps, but they're exactly as capable on day 1000 as they were on day 1.
+
+Agno agents are different. They remember users across sessions, accumulate knowledge across conversations, and learn from decisions. Insights from one user benefit everyone.
+
+Everything runs in your cloud. Your data never leaves your environment.
+
+## Quick Example
+```python
+from agno.agent import Agent
+from agno.db.sqlite import SqliteDb
+from agno.models.openai import OpenAIResponses
+
+agent = Agent(
+    model=OpenAIResponses(id="gpt-5.2"),
+    db=SqliteDb(db_file="tmp/agents.db"),
+    learning=True,
+)
+```
+
+One line. Your agent now remembers users, accumulates knowledge, and improves over time.
+
+## Production Stack
+
+| Layer | What it does |
+|-------|--------------|
+| **SDK** | Build agents with learning, tools, knowledge, and guardrails |
+| **Runtime** | Run in production using [AgentOS](https://docs.agno.com/agent-os/introduction) |
+| **Control Plane** | Monitor and manage via the [AgentOS UI](https://os.agno.com) |
+
+## Features
+
+**Learning**
+- User profiles that persist across sessions
+- User memories that accumulate over time
+- Learned knowledge that transfers across users
+- Always or agentic learning modes
+
+**Core**
+- Model-agnostic: OpenAI, Anthropic, Google, local models
+- Type-safe I/O with `input_schema` and `output_schema`
+- Async-first, built for long-running tasks
+- Natively multimodal (text, images, audio, video, files)
+
+**Knowledge**
+- Agentic RAG with 20+ vector stores, hybrid search, reranking
+- Persistent storage for session history and state
+
+**Orchestration**
+- Human-in-the-loop (confirmations, approvals, overrides)
+- Guardrails for validation and security
+- First-class MCP and A2A support
+- 100+ built-in toolkits
+
+**Production**
+- Ready-to-use FastAPI runtime
+- Integrated control plane UI
+- Evals for accuracy, performance, latency
+
+## Getting Started
+
+1. Follow the [quickstart](https://docs.agno.com/get-started/quickstart)
+2. Browse the [cookbook](https://github.com/agno-agi/agno/tree/main/cookbook)
+3. Read the [docs](https://docs.agno.com)
+
+## IDE Integration
+
+Add our docs to your AI-enabled editor:
+
+**Cursor:** Settings → Indexing & Docs → Add `https://docs.agno.com/llms-full.txt`
+
+Also works with VSCode, Windsurf, and similar tools.
+
+## Contributing
+
+See the [contributing guide](https://github.com/agno-agi/agno/blob/v2.0/CONTRIBUTING.md).
+
+## Telemetry
+
+Agno logs which model providers are used to prioritize updates. Disable with `AGNO_TELEMETRY=false`.
+
+<p align="right"><a href="#top">↑ Back to top</a></p>

{agno-2.4.5 → agno-2.4.6}/agno/agent/agent.py

@@ -858,8 +858,9 @@ class Agent:
             return
 
         # Handle learning=True: create default LearningMachine
+        # Enables user_profile (structured fields) and user_memory (unstructured observations)
         if self.learning is True:
-            self._learning = LearningMachine(db=self.db, model=self.model, user_profile=True)
+            self._learning = LearningMachine(db=self.db, model=self.model, user_profile=True, user_memory=True)
             return
 
         # Handle learning=LearningMachine(...): inject dependencies

{agno-2.4.5 → agno-2.4.6}/agno/db/surrealdb/models.py

@@ -48,7 +48,7 @@ def surrealize_dates(record: dict) -> dict:
         if isinstance(value, date):
             copy[key] = datetime.combine(value, datetime.min.time()).replace(tzinfo=timezone.utc)
         elif key in ["created_at", "updated_at"] and isinstance(value, (int, float)):
-            copy[key] = datetime.fromtimestamp(value).replace(tzinfo=timezone.utc)
+            copy[key] = datetime.fromtimestamp(value, tz=timezone.utc)
         elif key in ["created_at", "updated_at"] and isinstance(value, str):
             # Handle ISO string format - convert back to datetime object for SurrealDB
             try:

{agno-2.4.5 → agno-2.4.6}/agno/knowledge/chunking/agentic.py

@@ -55,11 +55,7 @@ class AgenticChunking(ChunkingStrategy):
             chunk = remaining_text[:break_point].strip()
             meta_data = chunk_meta_data.copy()
             meta_data["chunk"] = chunk_number
-            chunk_id = None
-            if document.id:
-                chunk_id = f"{document.id}_{chunk_number}"
-            elif document.name:
-                chunk_id = f"{document.name}_{chunk_number}"
+            chunk_id = self._generate_chunk_id(document, chunk_number, chunk)
             meta_data["chunk_size"] = len(chunk)
             chunks.append(
                 Document(

{agno-2.4.5 → agno-2.4.6}/agno/knowledge/chunking/code.py

@@ -82,7 +82,7 @@ class CodeChunking(ChunkingStrategy):
         for i, chunk in enumerate(chunks, 1):
             meta_data = document.meta_data.copy()
             meta_data["chunk"] = i
-            chunk_id = f"{document.id}_{i}" if document.id else None
+            chunk_id = self._generate_chunk_id(document, i, chunk.text)
             meta_data["chunk_size"] = len(chunk.text)
 
             chunked_documents.append(Document(id=chunk_id, name=document.name, meta_data=meta_data, content=chunk.text))

{agno-2.4.5 → agno-2.4.6}/agno/knowledge/chunking/document.py

@@ -38,17 +38,10 @@ class DocumentChunking(ChunkingStrategy):
                 if current_chunk:
                     meta_data = chunk_meta_data.copy()
                     meta_data["chunk"] = chunk_number
-                    chunk_id = None
-                    if document.id:
-                        chunk_id = f"{document.id}_{chunk_number}"
-                    elif document.name:
-                        chunk_id = f"{document.name}_{chunk_number}"
-                    meta_data["chunk_size"] = len("\n\n".join(current_chunk))
-                    chunks.append(
-                        Document(
-                            id=chunk_id, name=document.name, meta_data=meta_data, content="\n\n".join(current_chunk)
-                        )
-                    )
+                    chunk_content = "\n\n".join(current_chunk)
+                    chunk_id = self._generate_chunk_id(document, chunk_number, chunk_content)
+                    meta_data["chunk_size"] = len(chunk_content)
+                    chunks.append(Document(id=chunk_id, name=document.name, meta_data=meta_data, content=chunk_content))
                     chunk_number += 1
                     current_chunk = []
                     current_size = 0
@@ -70,18 +63,15 @@ class DocumentChunking(ChunkingStrategy):
                         if current_chunk:
                             meta_data = chunk_meta_data.copy()
                             meta_data["chunk"] = chunk_number
-                            chunk_id = None
-                            if document.id:
-                                chunk_id = f"{document.id}_{chunk_number}"
-                            elif document.name:
-                                chunk_id = f"{document.name}_{chunk_number}"
-                            meta_data["chunk_size"] = len(" ".join(current_chunk))
+                            chunk_content = " ".join(current_chunk)
+                            chunk_id = self._generate_chunk_id(document, chunk_number, chunk_content)
+                            meta_data["chunk_size"] = len(chunk_content)
                             chunks.append(
                                 Document(
                                     id=chunk_id,
                                     name=document.name,
                                     meta_data=meta_data,
-                                    content=" ".join(current_chunk),
+                                    content=chunk_content,
                                 )
                             )
                             chunk_number += 1
@@ -94,18 +84,11 @@ class DocumentChunking(ChunkingStrategy):
             else:
                 meta_data = chunk_meta_data.copy()
                 meta_data["chunk"] = chunk_number
-                chunk_id = None
-                if document.id:
-                    chunk_id = f"{document.id}_{chunk_number}"
-                elif document.name:
-                    chunk_id = f"{document.name}_{chunk_number}"
-                meta_data["chunk_size"] = len("\n\n".join(current_chunk))
+                chunk_content = "\n\n".join(current_chunk)
+                chunk_id = self._generate_chunk_id(document, chunk_number, chunk_content)
+                meta_data["chunk_size"] = len(chunk_content)
                 if current_chunk:
-                    chunks.append(
-                        Document(
-                            id=chunk_id, name=document.name, meta_data=meta_data, content="\n\n".join(current_chunk)
-                        )
-                    )
+                    chunks.append(Document(id=chunk_id, name=document.name, meta_data=meta_data, content=chunk_content))
                     chunk_number += 1
                 current_chunk = [para]
                 current_size = para_size
@@ -113,15 +96,10 @@ class DocumentChunking(ChunkingStrategy):
         if current_chunk:
             meta_data = chunk_meta_data.copy()
             meta_data["chunk"] = chunk_number
-            chunk_id = None
-            if document.id:
-                chunk_id = f"{document.id}_{chunk_number}"
-            elif document.name:
-                chunk_id = f"{document.name}_{chunk_number}"
-            meta_data["chunk_size"] = len("\n\n".join(current_chunk))
-            chunks.append(
-                Document(id=chunk_id, name=document.name, meta_data=meta_data, content="\n\n".join(current_chunk))
-            )
+            chunk_content = "\n\n".join(current_chunk)
+            chunk_id = self._generate_chunk_id(document, chunk_number, chunk_content)
+            meta_data["chunk_size"] = len(chunk_content)
+            chunks.append(Document(id=chunk_id, name=document.name, meta_data=meta_data, content=chunk_content))
 
         # Handle overlap if specified
         if self.overlap > 0:
@@ -131,11 +109,11 @@ class DocumentChunking(ChunkingStrategy):
                     # Add overlap from previous chunk
                     prev_text = chunks[i - 1].content[-self.overlap :]
                     meta_data = chunk_meta_data.copy()
-                    meta_data["chunk"] = chunk_number
-                    chunk_id = None
-                    if document.id:
-                        chunk_id = f"{document.id}_{chunk_number}"
+                    # Use the chunk's existing metadata and ID instead of stale chunk_number
+                    meta_data["chunk"] = chunks[i].meta_data["chunk"]
+                    chunk_id = chunks[i].id
                     meta_data["chunk_size"] = len(prev_text + chunks[i].content)
+
                     if prev_text:
                         overlapped_chunks.append(
                             Document(
@@ -145,6 +123,8 @@ class DocumentChunking(ChunkingStrategy):
                                 content=prev_text + chunks[i].content,
                             )
                         )
+                    else:
+                        overlapped_chunks.append(chunks[i])
                 else:
                     overlapped_chunks.append(chunks[i])
             chunks = overlapped_chunks

{agno-2.4.5 → agno-2.4.6}/agno/knowledge/chunking/fixed.py

@@ -38,11 +38,7 @@ class FixedSizeChunking(ChunkingStrategy):
             chunk = content[start:end]
             meta_data = chunk_meta_data.copy()
             meta_data["chunk"] = chunk_number
-            chunk_id = None
-            if document.id:
-                chunk_id = f"{document.id}_{chunk_number}"
-            elif document.name:
-                chunk_id = f"{document.name}_{chunk_number}"
+            chunk_id = self._generate_chunk_id(document, chunk_number, chunk)
             meta_data["chunk_size"] = len(chunk)
             chunked_documents.append(
                 Document(

{agno-2.4.5 → agno-2.4.6}/agno/knowledge/chunking/markdown.py

@@ -267,11 +267,7 @@ class MarkdownChunking(ChunkingStrategy):
                 for sub_chunk in sub_chunks:
                     meta_data = chunk_meta_data.copy()
                     meta_data["chunk"] = chunk_number
-                    chunk_id = None
-                    if document.id:
-                        chunk_id = f"{document.id}_{chunk_number}"
-                    elif document.name:
-                        chunk_id = f"{document.name}_{chunk_number}"
+                    chunk_id = self._generate_chunk_id(document, chunk_number, sub_chunk)
                     meta_data["chunk_size"] = len(sub_chunk)
 
                     chunks.append(Document(id=chunk_id, name=document.name, meta_data=meta_data, content=sub_chunk))
@@ -282,19 +278,12 @@ class MarkdownChunking(ChunkingStrategy):
             else:
                 meta_data = chunk_meta_data.copy()
                 meta_data["chunk"] = chunk_number
-                chunk_id = None
-                if document.id:
-                    chunk_id = f"{document.id}_{chunk_number}"
-                elif document.name:
-                    chunk_id = f"{document.name}_{chunk_number}"
-                meta_data["chunk_size"] = len("\n\n".join(current_chunk))
+                chunk_content = "\n\n".join(current_chunk)
+                chunk_id = self._generate_chunk_id(document, chunk_number, chunk_content)
+                meta_data["chunk_size"] = len(chunk_content)
 
                 if current_chunk:
-                    chunks.append(
-                        Document(
-                            id=chunk_id, name=document.name, meta_data=meta_data, content="\n\n".join(current_chunk)
-                        )
-                    )
+                    chunks.append(Document(id=chunk_id, name=document.name, meta_data=meta_data, content=chunk_content))
                     chunk_number += 1
 
                 current_chunk = [section]
@@ -304,15 +293,10 @@ class MarkdownChunking(ChunkingStrategy):
         if current_chunk and not self.split_on_headings:
             meta_data = chunk_meta_data.copy()
             meta_data["chunk"] = chunk_number
-            chunk_id = None
-            if document.id:
-                chunk_id = f"{document.id}_{chunk_number}"
-            elif document.name:
-                chunk_id = f"{document.name}_{chunk_number}"
-            meta_data["chunk_size"] = len("\n\n".join(current_chunk))
-            chunks.append(
-                Document(id=chunk_id, name=document.name, meta_data=meta_data, content="\n\n".join(current_chunk))
-            )
+            chunk_content = "\n\n".join(current_chunk)
+            chunk_id = self._generate_chunk_id(document, chunk_number, chunk_content)
+            meta_data["chunk_size"] = len(chunk_content)
+            chunks.append(Document(id=chunk_id, name=document.name, meta_data=meta_data, content=chunk_content))
 
         # Handle overlap if specified
         if self.overlap > 0:

{agno-2.4.5 → agno-2.4.6}/agno/knowledge/chunking/recursive.py

@@ -46,9 +46,7 @@ class RecursiveChunking(ChunkingStrategy):
             chunk = self.clean_text(content[start:end])
             meta_data = chunk_meta_data.copy()
             meta_data["chunk"] = chunk_number
-            chunk_id = None
-            if document.id:
-                chunk_id = f"{document.id}_{chunk_number}"
+            chunk_id = self._generate_chunk_id(document, chunk_number, chunk)
             chunk_number += 1
             meta_data["chunk_size"] = len(chunk)
             chunks.append(Document(id=chunk_id, name=document.name, meta_data=meta_data, content=chunk))

{agno-2.4.5 → agno-2.4.6}/agno/knowledge/chunking/row.py

@@ -33,7 +33,8 @@ class RowChunking(ChunkingStrategy):
 
             if chunk_content:  # Skip empty rows
                 meta_data = document.meta_data.copy()
-                meta_data["row_number"] = start_index + i  # Preserve logical row numbering
-                chunk_id = f"{document.id}_row_{start_index + i}" if document.id else None
+                row_number = start_index + i
+                meta_data["row_number"] = row_number  # Preserve logical row numbering
+                chunk_id = self._generate_chunk_id(document, row_number, chunk_content, prefix="row")
                 chunks.append(Document(id=chunk_id, name=document.name, meta_data=meta_data, content=chunk_content))
         return chunks

{agno-2.4.5 → agno-2.4.6}/agno/knowledge/chunking/semantic.py

@@ -160,7 +160,7 @@ class SemanticChunking(ChunkingStrategy):
         for i, chunk in enumerate(chunks, 1):
             meta_data = document.meta_data.copy()
             meta_data["chunk"] = i
-            chunk_id = f"{document.id}_{i}" if document.id else None
+            chunk_id = self._generate_chunk_id(document, i, chunk.text)
             meta_data["chunk_size"] = len(chunk.text)
 
             chunked_documents.append(Document(id=chunk_id, name=document.name, meta_data=meta_data, content=chunk.text))

{agno-2.4.5 → agno-2.4.6}/agno/knowledge/chunking/strategy.py

@@ -1,3 +1,4 @@
+import hashlib
 from abc import ABC, abstractmethod
 from enum import Enum
 from typing import List, Optional
@@ -12,6 +13,24 @@ class ChunkingStrategy(ABC):
     def chunk(self, document: Document) -> List[Document]:
         raise NotImplementedError
 
+    def _generate_chunk_id(
+        self, document: Document, chunk_number: int, content: Optional[str] = None, prefix: Optional[str] = None
+    ) -> Optional[str]:
+        """Generate a deterministic ID for the chunk."""
+        suffix = f"_{prefix}_{chunk_number}" if prefix else f"_{chunk_number}"
+
+        if document.id:
+            return f"{document.id}{suffix}"
+        elif document.name:
+            return f"{document.name}{suffix}"
+        else:
+            # Hash the chunk content for a deterministic ID when no identifier exists
+            hash_source = content if content else document.content
+            if hash_source:
+                content_hash = hashlib.md5(hash_source.encode("utf-8")).hexdigest()[:12]  # nosec B324
+                return f"chunk_{content_hash}{suffix}"
+            return None
+
     async def achunk(self, document: Document) -> List[Document]:
         """Async version of chunk. Override for truly async implementations."""
         return self.chunk(document)