Learning Claude Code

Author: dndcreator

.coverage

@@ -89,7 +89,19 @@ yarn.lock
 .DS_Store
 Thumbs.db
 .tmp/
+_pytest_session_tmp/
+_pytest_case_tmp/
 
 # Runtime workflow artifacts
 memory/moirai_runs/wf_*.json
+memory/moirai_runs/opro_*.json
+memory/moirai_runs/*.json
+
+# Runtime user config/state (generated locally)
+config/users/
+
+# Test coverage artifacts
+.coverage
+coverage.xml
+htmlcov/
 

.gitignore

@@ -34,6 +34,7 @@ Governance: [`GOVERNANCE.md`](GOVERNANCE.md)
 Maintainers: [`MAINTAINERS.md`](MAINTAINERS.md)
 Roadmap: [`ROADMAP.md`](ROADMAP.md)
 Deployment: [`docs/deployment.md`](docs/deployment.md)
+User setup (copy-and-run): [`docs/getting-started/real-user-setup.md`](docs/getting-started/real-user-setup.md)
 
 ## Why Promethea?
 
@@ -134,10 +135,10 @@ pip install -r requirements.txt
 
 ```bash
 # Windows
-copy example.env .env
+copy env.example .env
 
 # macOS / Linux
-cp example.env .env
+cp env.example .env
 ```
 
 Open `.env` and set **at minimum these three fields** (they are coupled — all three must match your provider):
@@ -161,12 +162,7 @@ API__MODEL=your-local-model-id
 
 > ⚠️ `API__BASE_URL` and `API__MODEL` must match. Changing only the key will not work.
 
-Choose a memory backend (start here if you want zero external dependencies):
-
-```bash
-MEMORY__ENABLED=true
-MEMORY__STORE_BACKEND=sqlite_graph   # or flat_memory
-```
+Non-sensitive runtime options (including memory backend, default `neo4j`) come from `config/default.json`.
 
 ### 3. Run
 

README.md

@@ -540,8 +540,8 @@ <h3 id="settingsSectionSystemTitle">System</h3>
                         <div class="form-group">
                             <label for="logLevel">Log Level</label>
                             <select id="logLevel" name="system.log_level">
-                                <option value="DEBUG">DEBUG</option>
                                 <option value="INFO">INFO</option>
+                                <option value="DEBUG">DEBUG</option>
                                 <option value="WARNING">WARNING</option>
                                 <option value="ERROR">ERROR</option>
                             </select>
@@ -664,7 +664,7 @@ <h3 id="settingsSectionMemoryTitle">Memory</h3>
         <button id="quickAskBtn" class="quick-ask-btn">Follow-up</button>
     </div>
 
-    <script src="https://d3js.org/d3.v7.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/d3@7/dist/d3.min.js"></script>
     <script src="script.js?v=20260317a" charset="UTF-8"></script>
     <script src="voice.js?v=20260309a" charset="UTF-8"></script>
 </body>

UI/index.html

@@ -10,6 +10,17 @@
 logger = logging.getLogger(__name__)
 
 
+def _resolve_ddgs_class():
+    try:
+        from ddgs import DDGS
+
+        return DDGS
+    except ImportError:
+        from duckduckgo_search import DDGS
+
+        return DDGS
+
+
 class WebSearchService:
     """Simple DuckDuckGo search wrapper with sandbox-aware network guard."""
 
@@ -25,7 +36,12 @@ def _ensure_network_allowed(self) -> Optional[str]:
             return f"Sandbox blocked web search: {decision.reason}"
         return None
 
-    async def search(self, query: str, max_results: Optional[int] = None) -> str:
+    async def search(
+        self,
+        query: str,
+        max_results: Optional[int] = None,
+        num_results: Optional[int] = None,
+    ) -> str:
         """Run a general web search."""
         blocked = self._ensure_network_allowed()
         if blocked:
@@ -34,10 +50,11 @@ async def search(self, query: str, max_results: Optional[int] = None) -> str:
             if not query or not query.strip():
                 return "Error: query cannot be empty"
 
-            limit = max_results if max_results and max_results > 0 else self.max_results
+            requested = max_results if max_results and max_results > 0 else num_results
+            limit = requested if requested and requested > 0 else self.max_results
 
             try:
-                from duckduckgo_search import DDGS
+                DDGS = _resolve_ddgs_class()
 
                 logger.info("Search: %s (max=%s)", query, limit)
                 results = []
@@ -60,7 +77,7 @@ async def search(self, query: str, max_results: Optional[int] = None) -> str:
                     )
                 return "\n".join(formatted)
             except ImportError:
-                return "Missing dependency: install duckduckgo-search"
+                return "Missing dependency: install ddgs"
         except Exception as e:
             logger.error("Search failed: %s", e)
             return f"Error: search failed: {e}"
@@ -71,7 +88,7 @@ async def quick_answer(self, query: str) -> str:
         if blocked:
             return blocked
         try:
-            from duckduckgo_search import DDGS
+            DDGS = _resolve_ddgs_class()
 
             with DDGS() as ddgs:
                 answers = list(ddgs.answers(query))
@@ -90,15 +107,21 @@ async def quick_answer(self, query: str) -> str:
             logger.error("Quick answer failed: %s", e)
             return await self.search(query, max_results=3)
 
-    async def news_search(self, query: str, max_results: Optional[int] = None) -> str:
+    async def news_search(
+        self,
+        query: str,
+        max_results: Optional[int] = None,
+        num_results: Optional[int] = None,
+    ) -> str:
         """Search news results."""
         blocked = self._ensure_network_allowed()
         if blocked:
             return blocked
         try:
-            from duckduckgo_search import DDGS
+            DDGS = _resolve_ddgs_class()
 
-            limit = max_results if max_results and max_results > 0 else self.max_results
+            requested = max_results if max_results and max_results > 0 else num_results
+            limit = requested if requested and requested > 0 else self.max_results
             results = []
             with DDGS() as ddgs:
                 for result in ddgs.news(query, max_results=limit):
@@ -122,7 +145,7 @@ async def news_search(self, query: str, max_results: Optional[int] = None) -> st
                 )
             return "\n".join(formatted)
         except ImportError:
-            return "Missing dependency: install duckduckgo-search"
+            return "Missing dependency: install ddgs"
         except Exception as e:
             logger.error("News search failed: %s", e)
             return f"Error: news search failed: {e}"

UI/script.js

@@ -9,11 +9,16 @@
 from pydantic_settings import BaseSettings, SettingsConfigDict
 from dotenv import dotenv_values
 
+PROJECT_ROOT = Path(__file__).resolve().parent
+ENV_FILE = PROJECT_ROOT / ".env"
+DEFAULT_CONFIG_PATH = PROJECT_ROOT / "config" / "default.json"
+LEGACY_CONFIG_PATH = PROJECT_ROOT / "config.json"
+
 
 class SystemConfig(BaseSettings):
     version: str = Field(default="1.0")
-    base_dir: Path = Field(default_factory=lambda: Path(__file__).parent)
-    log_dir: Path = Field(default_factory=lambda: Path(__file__).parent / "logs")
+    base_dir: Path = Field(default_factory=lambda: PROJECT_ROOT)
+    log_dir: Path = Field(default_factory=lambda: PROJECT_ROOT / "logs")
     stream_mode: bool = Field(default=True)
     debug: bool = Field(default=False)
     log_level: str = Field(default="INFO")
@@ -297,7 +302,7 @@ class PrometheaConfig(BaseSettings):
     sandbox: SandboxConfig = Field(default_factory=SandboxConfig)
 
     model_config = SettingsConfigDict(
-        env_file=".env",
+        env_file=str(ENV_FILE),
         env_file_encoding="utf-8",
         env_nested_delimiter="__",
         extra="ignore",
@@ -324,36 +329,70 @@ def _set_nested_value(target: dict, path: tuple[str, ...], value: Any) -> None:
     current[path[-1]] = value
 
 
-def _overlay_explicit_env_values(merged_data: dict, base_from_env: PrometheaConfig) -> None:
-    env_map = {
-        ("api", "api_key"): "API__API_KEY",
-        ("api", "model"): "API__MODEL",
-        ("api", "failover_models"): "API__FAILOVER_MODELS",
-        ("memory", "api", "api_key"): "MEMORY__API__API_KEY",
-        ("memory", "neo4j", "password"): "MEMORY__NEO4J__PASSWORD",
-    }
+def _resolve_key_case_insensitive(payload: dict, key: str) -> Optional[str]:
+    if key in payload:
+        return key
+    key_lower = key.lower()
+    for existing in payload.keys():
+        if str(existing).lower() == key_lower:
+            return str(existing)
+    return None
+
+
+def _get_nested_value_ci(payload: dict, path: tuple[str, ...]) -> tuple[bool, Any]:
+    current: Any = payload
+    for segment in path:
+        if not isinstance(current, dict):
+            return False, None
+        resolved = _resolve_key_case_insensitive(current, segment)
+        if resolved is None:
+            return False, None
+        current = current.get(resolved)
+    return True, current
+
+
+def _set_nested_value_ci(payload: dict, path: tuple[str, ...], value: Any) -> bool:
+    current: Any = payload
+    for segment in path[:-1]:
+        if not isinstance(current, dict):
+            return False
+        resolved = _resolve_key_case_insensitive(current, segment)
+        if resolved is None:
+            return False
+        current = current.get(resolved)
+    if not isinstance(current, dict):
+        return False
+    last = _resolve_key_case_insensitive(current, path[-1])
+    if last is None:
+        return False
+    current[last] = value
+    return True
+
 
+def _overlay_explicit_env_values(merged_data: dict, base_from_env: PrometheaConfig) -> None:
     env_data = base_from_env.model_dump()
     explicit_env_keys = set(os.environ.keys())
-    env_file = dotenv_values(".env")
+    env_file = dotenv_values(str(ENV_FILE)) if ENV_FILE.exists() else {}
     explicit_env_keys.update(str(k) for k in env_file.keys() if k)
-    for path, env_name in env_map.items():
-        if env_name not in explicit_env_keys:
+    for env_name in sorted(explicit_env_keys):
+        if "__" not in env_name:
             continue
-
-        value: Any = env_data
-        for segment in path:
-            value = value[segment]
-        _set_nested_value(merged_data, path, value)
+        path = tuple(seg for seg in str(env_name).split("__") if seg)
+        if not path:
+            continue
+        found, value = _get_nested_value_ci(env_data, path)
+        if not found:
+            continue
+        _set_nested_value_ci(merged_data, path, value)
 
 
 def load_config() -> PrometheaConfig:
     base_from_env = PrometheaConfig()
     merged_data = base_from_env.model_dump()
 
-    config_path = Path("config/default.json")
+    config_path = DEFAULT_CONFIG_PATH
     if not config_path.exists():
-        legacy_path = Path("config.json")
+        legacy_path = LEGACY_CONFIG_PATH
         config_path = legacy_path if legacy_path.exists() else None
 
     if config_path and config_path.exists():