ni.agentkit 0.7.3__tar.gz → 0.7.4__tar.gz

{ni_agentkit-0.7.3 → ni_agentkit-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ni.agentkit
-Version: 0.7.3
+Version: 0.7.4
 Summary: A Python-native Agent framework with first-class Skill support and multi-LLM adapter
 Author-email: Krix Tam <krix.tam@qq.com>
 License: MIT
@@ -155,8 +155,8 @@ python "$(python -c "import agentkit, os; print(os.path.join(agentkit.get_exampl
 
 ```bash
 dist/
-├── ni_agentkit-0.7.3-py3-none-any.whl   # pip install 用这个
-└── ni_agentkit-0.7.3.tar.gz             # 源码分发
+├── ni_agentkit-0.7.4-py3-none-any.whl   # pip install 用这个
+└── ni_agentkit-0.7.4.tar.gz             # 源码分发
 ```
 
 ## 📄 License

{ni_agentkit-0.7.3 → ni_agentkit-0.7.4}/README.md

@@ -112,8 +112,8 @@ python "$(python -c "import agentkit, os; print(os.path.join(agentkit.get_exampl
 
 ```bash
 dist/
-├── ni_agentkit-0.7.3-py3-none-any.whl   # pip install 用这个
-└── ni_agentkit-0.7.3.tar.gz             # 源码分发
+├── ni_agentkit-0.7.4-py3-none-any.whl   # pip install 用这个
+└── ni_agentkit-0.7.4.tar.gz             # 源码分发
 ```
 
 ## 📄 License

{ni_agentkit-0.7.3 → ni_agentkit-0.7.4}/agents/agent.py

@@ -293,11 +293,12 @@ class Agent(BaseAgent):
 
                 # 5. 调用 LLM（支持缓存）
                 cached = False
+                cache_key: str | None = None
 
                 # 检查缓存
                 if self.enable_cache:
                     cache = self._get_cache()
-                    cached_response = cache.get(messages, tool_defs if tool_defs else None)
+                    cache_key, cached_response = cache.get_with_key(messages, tool_defs if tool_defs else None)
                     if cached_response is not None:
                         response = cached_response
                         cached = True
@@ -318,7 +319,10 @@ class Agent(BaseAgent):
 
                     # 写入缓存
                     if self.enable_cache:
-                        cache.put(messages, tool_defs if tool_defs else None, response)
+                        if cache_key is not None:
+                            cache.put_with_key(cache_key, response)
+                        else:
+                            cache.put(messages, tool_defs if tool_defs else None, response)
 
                 cache_key_ms = 0.0
                 if self.enable_cache:

{ni_agentkit-0.7.3 → ni_agentkit-0.7.4}/docs/Architecture.md

@@ -471,6 +471,7 @@ agent.clear_cache()
 > - 缓存仅在单 Agent 实例内有效，重新创建 Agent 会清空缓存
 > - 默认最大 128 条缓存，LRU 淘汰最久未使用的条目
 > - 缓存实现内置 key 生成统计：`key_gen_calls / key_gen_total_ms / key_gen_last_ms / key_gen_avg_ms`
+> - 缓存实现对同一轮的缓存 key 计算做了复用（避免 miss 场景下重复算 key）
 
 ### 3. 记忆异步写入
 

{ni_agentkit-0.7.3 → ni_agentkit-0.7.4}/docs/README.md

@@ -3,7 +3,7 @@
 > Python 原生的 Agent 开发框架，内置一等公民级别的 Skill 支持和自研多模型适配层。
 
 [![Python](https://img.shields.io/badge/Python-≥3.11-blue.svg)](https://python.org)
-[![Version](https://img.shields.io/badge/Version-0.7.3-green.svg)]()
+[![Version](https://img.shields.io/badge/Version-0.7.4-green.svg)]()
 [![License](https://img.shields.io/badge/License-MIT-yellow.svg)]()
 
 ---

{ni_agentkit-0.7.3 → ni_agentkit-0.7.4}/docs/Reference.md

@@ -577,6 +577,20 @@ from agentkit import LLMRegistry
 | `LLMRegistry.create_default()` | 创建默认模型实例 |
 | `LLMRegistry.register(prefix, adapter_class)` | 注册自定义适配器 |
 
+默认模型解析优先级：
+
+1. 若代码中调用过 `LLMRegistry.set_default(...)`，优先使用该默认配置。
+2. 否则会尝试从环境变量（或本地 `.env/.evn`）读取：`AGENTKIT_MODEL` → `AGENTKIT_DEFAULT_MODEL` → `AGENTKIT_STANDARD_MODEL` → `AGENTKIT_OLLAMA_MODEL`。
+3. 都未配置时回退到内置默认值。
+
+示例：
+
+```bash
+export AGENTKIT_DEFAULT_MODEL="ollama/qwen3.5:cloud"
+# 或在项目根目录写入 .env（无需额外依赖）
+# AGENTKIT_DEFAULT_MODEL=ollama/qwen3.5:cloud
+```
+
 **前缀路由表**：
 
 | 前缀 | 适配器 | 需要的包 |

{ni_agentkit-0.7.3 → ni_agentkit-0.7.4}/docs/TestReport.md

@@ -3,7 +3,7 @@
 > 测试时间：`2026-06-15`  
 > 测试环境：`macOS (Apple Silicon)`  
 > 模型：`qwen/qwen3.6-flash` (DashScope)  
-> AgentKit 版本：v0.7.3  
+> AgentKit 版本：v0.7.4  
 > Thinking 模式：开启（默认）  
 > LLM 调用模式：非流式（默认）  
 > 缓存：开启（默认）  
@@ -16,39 +16,39 @@
 
 | # | 示例 | 文件 | 耗时 | 状态 | 说明 |
 |---|------|------|-----:|:----:|------|
-| 1 | 01_basic_chat | `01_basic_chat.py` | 6.67s | ✅ | 运行通过 |
-| 2 | 02_tool_calling | `02_tool_calling.py` | 10.60s | ✅ | 运行通过 |
-| 3 | 03_skill_usage | `03_skill_usage.py` | 11.34s | ✅ | 运行通过 |
-| 4 | 03b_skill_tools_entry | `03b_skill_tools_entry.py` | 7.69s | ✅ | 运行通过 |
-| 5 | 04_multi_agent | `04_multi_agent.py` | 54.06s | ✅ | 运行通过 |
-| 6 | 05_guardrail | `05_guardrail.py` | 8.95s | ✅ | 运行通过 |
-| 7 | 05_human_in_the_loop | `05_human_in_the_loop.py` | 0.25s | ✅ | 运行通过 |
-| 8 | 06_orchestration | `06_orchestration.py` | 41.62s | ✅ | 运行通过 |
-| 9 | 07_sync_async_stream | `07_sync_async_stream.py` | 16.21s | ✅ | 运行通过 |
-| 10 | 08_memory | `08_memory.py` | 31.10s | ✅ | 运行通过 |
-| 11 | 08a_memory_simple_provider | `08a_memory_simple_provider.py` | 8.81s | ✅ | 运行通过 |
-| 12 | 08b_memory_mem0_provider | `08b_memory_mem0_provider.py` | 0.25s | ✅ | 运行通过 |
-| 13 | 08c_memory_file_provider | `08c_memory_file_provider.py` | 10.82s | ✅ | 运行通过 |
-| 14 | 09a_structured_data_sql | `09a_structured_data_sql.py` | 6.37s | ✅ | 运行通过 |
-| 15 | 09b_structured_data_graph | `09b_structured_data_graph.py` | 2.58s | ✅ | 运行通过 |
-| 16 | 09c_nebula_graph_tool | `09c_nebula_graph_tool.py` | 0.34s | ✅ | 运行通过 |
-| 17 | 10_skill_lifecycle | `10_skill_lifecycle.py` | 2.98s | ✅ | 运行通过 |
-| 18 | 11_orchestration_enhancement | `11_orchestration_enhancement.py` | 3.41s | ✅ | 运行通过 |
-| 19 | 12_run_context_serialization | `12_run_context_serialization.py` | 0.18s | ✅ | 运行通过 |
-| 20 | 13_human_in_the_loop | `13_human_in_the_loop.py` | 6.36s | ✅ | 运行通过 |
-| 21 | 14_event_standardization | `14_event_standardization.py` | 2.87s | ✅ | 运行通过 |
-| 22 | 15_multi_tenant_isolation | `15_multi_tenant_isolation.py` | 8.43s | ✅ | 运行通过 |
-| 23 | 16_lifecycle_hooks | `16_lifecycle_hooks.py` | 4.92s | ✅ | 运行通过 |
-| 24 | 17_checkpoint_handoff_resume | `17_checkpoint_handoff_resume.py` | 0.19s | ✅ | 运行通过 |
-| 25 | 18_model_cosplay | `18_model_cosplay.py` | 0.20s | ✅ | 运行通过 |
-| 26 | 19_hitl_deterministic | `19_hitl_deterministic.py` | 0.19s | ✅ | 运行通过 |
-| | **合计** | | **247.37s** | **26/26** | |
+| 1 | 01_basic_chat | `01_basic_chat.py` | 5.63s | ✅ | 运行通过 |
+| 2 | 02_tool_calling | `02_tool_calling.py` | 10.70s | ✅ | 运行通过 |
+| 3 | 03_skill_usage | `03_skill_usage.py` | 15.31s | ✅ | 运行通过 |
+| 4 | 03b_skill_tools_entry | `03b_skill_tools_entry.py` | 7.79s | ✅ | 运行通过 |
+| 5 | 04_multi_agent | `04_multi_agent.py` | 39.61s | ✅ | 运行通过 |
+| 6 | 05_guardrail | `05_guardrail.py` | 7.09s | ✅ | 运行通过 |
+| 7 | 05_human_in_the_loop | `05_human_in_the_loop.py` | 0.31s | ✅ | 运行通过 |
+| 8 | 06_orchestration | `06_orchestration.py` | 36.54s | ✅ | 运行通过 |
+| 9 | 07_sync_async_stream | `07_sync_async_stream.py` | 21.68s | ✅ | 运行通过 |
+| 10 | 08_memory | `08_memory.py` | 35.79s | ✅ | 运行通过 |
+| 11 | 08a_memory_simple_provider | `08a_memory_simple_provider.py` | 9.05s | ✅ | 运行通过 |
+| 12 | 08b_memory_mem0_provider | `08b_memory_mem0_provider.py` | 0.29s | ✅ | 运行通过 |
+| 13 | 08c_memory_file_provider | `08c_memory_file_provider.py` | 11.53s | ✅ | 运行通过 |
+| 14 | 09a_structured_data_sql | `09a_structured_data_sql.py` | 6.91s | ✅ | 运行通过 |
+| 15 | 09b_structured_data_graph | `09b_structured_data_graph.py` | 5.44s | ✅ | 运行通过 |
+| 16 | 09c_nebula_graph_tool | `09c_nebula_graph_tool.py` | 0.45s | ✅ | 运行通过 |
+| 17 | 10_skill_lifecycle | `10_skill_lifecycle.py` | 2.38s | ✅ | 运行通过 |
+| 18 | 11_orchestration_enhancement | `11_orchestration_enhancement.py` | 3.16s | ✅ | 运行通过 |
+| 19 | 12_run_context_serialization | `12_run_context_serialization.py` | 0.23s | ✅ | 运行通过 |
+| 20 | 13_human_in_the_loop | `13_human_in_the_loop.py` | 5.88s | ✅ | 运行通过 |
+| 21 | 14_event_standardization | `14_event_standardization.py` | 3.84s | ✅ | 运行通过 |
+| 22 | 15_multi_tenant_isolation | `15_multi_tenant_isolation.py` | 6.93s | ✅ | 运行通过 |
+| 23 | 16_lifecycle_hooks | `16_lifecycle_hooks.py` | 6.70s | ✅ | 运行通过 |
+| 24 | 17_checkpoint_handoff_resume | `17_checkpoint_handoff_resume.py` | 0.22s | ✅ | 运行通过 |
+| 25 | 18_model_cosplay | `18_model_cosplay.py` | 0.26s | ✅ | 运行通过 |
+| 26 | 19_hitl_deterministic | `19_hitl_deterministic.py` | 0.25s | ✅ | 运行通过 |
+| | **合计** | | **243.97s** | **26/26** | |
 
 ## 耗时分析
 
-- **最快示例**：12_run_context_serialization (0.18s)
-- **最慢示例**：04_multi_agent (54.06s)
-- **性能改进**：本次批跑合计 247.37s，耗时主要集中在 04_multi_agent / 06_orchestration / 08_memory 等编排类示例。
+- **最快示例**：17_checkpoint_handoff_resume (0.22s)
+- **最慢示例**：04_multi_agent (39.61s)
+- **性能改进**：本次批跑合计 243.97s，耗时主要集中在 04_multi_agent / 06_orchestration / 08_memory 等编排类示例。
 
 ## 已知问题
 

{ni_agentkit-0.7.3 → ni_agentkit-0.7.4}/llm/cache.py

@@ -107,12 +107,21 @@ class LLMCache:
         tools: list[ToolDefinition] | None = None,
     ) -> Optional[LLMResponse]:
         """查询缓存，命中返回 LLMResponse，未命中返回 None"""
+        _, res = self.get_with_key(messages, tools)
+        return res
+
+    def get_with_key(
+        self,
+        messages: list[Message],
+        tools: list[ToolDefinition] | None = None,
+    ) -> tuple[str, Optional[LLMResponse]]:
+        """查询缓存并返回 (key, response_or_none)"""
         key = self._make_key(messages, tools)
         entry = self._cache.get(key)
 
         if entry is None:
             self._misses += 1
-            return None
+            return key, None
 
         timestamp, response = entry
 
@@ -120,12 +129,12 @@ class LLMCache:
         if self._ttl > 0 and (time.time() - timestamp) > self._ttl:
             del self._cache[key]
             self._misses += 1
-            return None
+            return key, None
 
         # 命中：移到末尾（LRU）
         self._cache.move_to_end(key)
         self._hits += 1
-        return response
+        return key, response
 
     def put(
         self,
@@ -139,6 +148,13 @@ class LLMCache:
             return
 
         key = self._make_key(messages, tools)
+        self.put_with_key(key, response)
+
+    def put_with_key(self, key: str, response: LLMResponse) -> None:
+        """写入缓存（key 由外部预计算）。"""
+        if response.has_tool_calls:
+            return
+
         self._cache[key] = (time.time(), response)
         self._cache.move_to_end(key)
 

{ni_agentkit-0.7.3 → ni_agentkit-0.7.4}/llm/registry.py

@@ -14,6 +14,7 @@ from typing import Any
 
 from .base import BaseLLM
 from .types import LLMConfig
+from ..utils.env import load_env
 
 
 class LLMRegistry:
@@ -75,8 +76,23 @@ class LLMRegistry:
     def create_default(cls) -> BaseLLM:
         if cls._default_config:
             return cls.create(cls._default_config)
+        env_model = cls._get_default_model_from_env()
+        if env_model:
+            return cls.create(env_model)
         return cls.create(cls._default_model)
 
+    @classmethod
+    def _get_default_model_from_env(cls) -> str | None:
+        load_env()
+        for key in ("AGENTKIT_MODEL", "AGENTKIT_DEFAULT_MODEL", "AGENTKIT_STANDARD_MODEL", "AGENTKIT_OLLAMA_MODEL"):
+            value = (os.environ.get(key) or "").strip()
+            if not value:
+                continue
+            if key == "AGENTKIT_OLLAMA_MODEL" and not value.startswith("ollama/"):
+                value = f"ollama/{value}"
+            return value
+        return None
+
     # ------------------------------------------------------------------
 
     @classmethod

{ni_agentkit-0.7.3 → ni_agentkit-0.7.4}/ni.agentkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ni.agentkit
-Version: 0.7.3
+Version: 0.7.4
 Summary: A Python-native Agent framework with first-class Skill support and multi-LLM adapter
 Author-email: Krix Tam <krix.tam@qq.com>
 License: MIT
@@ -155,8 +155,8 @@ python "$(python -c "import agentkit, os; print(os.path.join(agentkit.get_exampl
 
 ```bash
 dist/
-├── ni_agentkit-0.7.3-py3-none-any.whl   # pip install 用这个
-└── ni_agentkit-0.7.3.tar.gz             # 源码分发
+├── ni_agentkit-0.7.4-py3-none-any.whl   # pip install 用这个
+└── ni_agentkit-0.7.4.tar.gz             # 源码分发
 ```
 
 ## 📄 License

{ni_agentkit-0.7.3 → ni_agentkit-0.7.4}/ni.agentkit.egg-info/SOURCES.txt

@@ -124,6 +124,7 @@ pyproject.toml
 ./tools/sqlite_tool.py
 ./tools/structured_data.py
 ./utils/__init__.py
+./utils/env.py
 ./utils/schema.py
 agents/__init__.py
 agents/agent.py
@@ -243,6 +244,7 @@ skills/loader.py
 skills/models.py
 skills/registry.py
 tests/test_after_callback.py
+tests/test_default_model_env.py
 tests/test_graph_repository.py
 tests/test_quickstart_core.py
 tests/test_runner_checkpoint_resume.py
@@ -256,4 +258,5 @@ tools/skill_toolset.py
 tools/sqlite_tool.py
 tools/structured_data.py
 utils/__init__.py
+utils/env.py
 utils/schema.py

{ni_agentkit-0.7.3 → ni_agentkit-0.7.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ni.agentkit"
-version = "0.7.3"
+version = "0.7.4"
 description = "A Python-native Agent framework with first-class Skill support and multi-LLM adapter"
 authors = [
     { name = "Krix Tam", email = "krix.tam@qq.com" }

{ni_agentkit-0.7.3 → ni_agentkit-0.7.4}/rag/file_memory_provider.py

@@ -15,13 +15,20 @@ class SQLiteMemoryProvider(BaseMemoryProvider):
 
     def __init__(self, db_path: str = ".agentkit/rag/index.db") -> None:
         self._db_path = db_path
+        self._token_cache: dict[str, set[str]] = {}
 
     @staticmethod
     def _to_memory(record: dict, *, score: float = 0.0) -> Memory:
+        metadata = record.get("metadata", {})
+        if isinstance(metadata, str):
+            try:
+                metadata = json.loads(metadata or "{}")
+            except Exception:
+                metadata = {}
         return Memory(
             id=str(record["id"]),
             content=str(record["content"]),
-            metadata=dict(record.get("metadata", {})),
+            metadata=dict(metadata),
             created_at=record.get("created_at"),
             score=score,
         )
@@ -48,14 +55,21 @@ class SQLiteMemoryProvider(BaseMemoryProvider):
         return [self._to_memory(record)]
 
     async def search(self, query, *, user_id=None, agent_id=None, limit=10):
-        records = self._query_records(user_id=user_id, agent_id=agent_id)
+        records = self._query_records(user_id=user_id, agent_id=agent_id, decode_metadata=False)
         query_tokens = tokenize(str(query))
         query_set = set(query_tokens) if query_tokens else set(str(query))
         ranked: list[tuple[float, dict]] = []
         for record in records:
             content = str(record.get("content", ""))
-            content_tokens = tokenize(content)
-            content_set = set(content_tokens) if content_tokens else set(content)
+            cache_key = str(record.get("id", ""))
+            cached_set = self._token_cache.get(cache_key)
+            if cached_set is None:
+                content_tokens = tokenize(content)
+                cached_set = set(content_tokens) if content_tokens else set(content)
+                self._token_cache[cache_key] = cached_set
+                if len(self._token_cache) > 4096:
+                    self._token_cache.clear()
+            content_set = cached_set
             overlap = len(query_set & content_set)
             if overlap <= 0:
                 continue
@@ -73,7 +87,7 @@ class SQLiteMemoryProvider(BaseMemoryProvider):
             conn.commit()
             return cursor.rowcount > 0
 
-    def _query_records(self, *, user_id=None, agent_id=None) -> list[dict]:
+    def _query_records(self, *, user_id=None, agent_id=None, decode_metadata: bool = True) -> list[dict]:
         clauses: list[str] = []
         params: list[str | None] = []
         if user_id is not None:
@@ -90,13 +104,25 @@ class SQLiteMemoryProvider(BaseMemoryProvider):
 
         with connect(self._db_path) as conn:
             rows = conn.execute(sql, params).fetchall()
+        if decode_metadata:
+            return [
+                {
+                    "id": str(row["id"]),
+                    "content": row["content"],
+                    "user_id": row["user_id"],
+                    "agent_id": row["agent_id"],
+                    "metadata": json.loads(row["metadata"] or "{}"),
+                    "created_at": row["created_at"],
+                }
+                for row in rows
+            ]
         return [
             {
                 "id": str(row["id"]),
                 "content": row["content"],
                 "user_id": row["user_id"],
                 "agent_id": row["agent_id"],
-                "metadata": json.loads(row["metadata"] or "{}"),
+                "metadata": row["metadata"] or "{}",
                 "created_at": row["created_at"],
             }
             for row in rows

{ni_agentkit-0.7.3 → ni_agentkit-0.7.4}/rag/sqlite_store.py

@@ -3,17 +3,26 @@
 from __future__ import annotations
 
 import sqlite3
+import threading
 from pathlib import Path
 
+_schema_lock = threading.Lock()
+_schema_initialized: set[str] = set()
+
 
 def connect(db_path: str) -> sqlite3.Connection:
     """创建启用外键与行字典访问的 SQLite 连接。"""
-    path = Path(db_path)
+    path = Path(db_path).expanduser().resolve()
     path.parent.mkdir(parents=True, exist_ok=True)
     conn = sqlite3.connect(path)
     conn.row_factory = sqlite3.Row
     conn.execute("PRAGMA foreign_keys = ON")
-    initialize_schema(conn)
+    key = str(path)
+    if key not in _schema_initialized:
+        with _schema_lock:
+            if key not in _schema_initialized:
+                initialize_schema(conn)
+                _schema_initialized.add(key)
     return conn
 
 

ni_agentkit-0.7.4/tests/test_default_model_env.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from agentkit.llm.registry import LLMRegistry
+
+
+def test_llmregistry_create_default_uses_env_from_dotenv(tmp_path: Path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / ".env").write_text("AGENTKIT_OLLAMA_MODEL=qwen3.5:cloud\n", encoding="utf-8")
+
+    llm = LLMRegistry.create_default()
+    assert llm.__class__.__name__ == "OllamaAdapter"
+    assert llm.config.model == "qwen3.5:cloud"
+

ni_agentkit-0.7.4/utils/env.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+_NEAREST_DOTENV_CACHE: dict[str, Path | None] = {}
+_DOTENV_LOAD_CACHE: dict[str, tuple[int, dict[str, str]]] = {}
+
+
+def load_env(dotenv_path: str | None = None) -> dict[str, str]:
+    path = Path(dotenv_path).expanduser().resolve() if dotenv_path else _find_nearest_dotenv()
+    if path is None or not path.exists() or not path.is_file():
+        return {}
+
+    stat = path.stat()
+    cache_key = str(path)
+    cached = _DOTENV_LOAD_CACHE.get(cache_key)
+    if cached and cached[0] == stat.st_mtime_ns:
+        loaded = cached[1]
+        for k, v in loaded.items():
+            if k not in os.environ:
+                os.environ[k] = v
+        return dict(loaded)
+
+    loaded: dict[str, str] = {}
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export ") :].strip()
+        if "=" not in line:
+            continue
+
+        key, value = line.split("=", 1)
+        key = key.strip()
+        if not key:
+            continue
+
+        value = value.strip()
+        if (value.startswith('"') and value.endswith('"')) or (value.startswith("'") and value.endswith("'")):
+            value = value[1:-1]
+
+        if key not in os.environ:
+            os.environ[key] = value
+        loaded[key] = value
+
+    _DOTENV_LOAD_CACHE[cache_key] = (stat.st_mtime_ns, dict(loaded))
+    return loaded
+
+
+def _find_nearest_dotenv() -> Path | None:
+    cwd = Path.cwd().resolve()
+    cached = _NEAREST_DOTENV_CACHE.get(str(cwd))
+    if cached is not None:
+        return cached
+
+    candidates: list[Path] = []
+    for base in [cwd, *cwd.parents]:
+        candidates.append(base / ".env")
+        candidates.append(base / ".evn")
+
+    seen: set[Path] = set()
+    for path in candidates:
+        if path in seen:
+            continue
+        seen.add(path)
+        if path.exists() and path.is_file():
+            _NEAREST_DOTENV_CACHE[str(cwd)] = path
+            return path
+    _NEAREST_DOTENV_CACHE[str(cwd)] = None
+    return None