diff --git a/README.md b/README.md index 8e2490a..437c20b 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,52 @@ cd okf-compiler uv sync --extra dev --extra llm ``` +## Configure the LLM with `.env` + +Copy the included template and fill in your provider values: + +```powershell +Copy-Item .env.example .env +``` + +```env +OKF_LLM_BASE_URL=https://api.example.com/v1 +OKF_LLM_MODEL=your-model +OKF_LLM_API_KEY=your-key +OKF_LLM_TIMEOUT=120 +``` + +Then test the connection: + +```powershell +uv run okf test-llm +``` + +Configuration priority is: + +```text +CLI flags > process environment > .env > defaults +``` + +Dotenv discovery order is: + +1. `--env-file PATH`. +2. The path in `OKF_ENV_FILE`. +3. `.env` in the current working directory. +4. `.env` beside the input Markdown or input directory. + +Only one dotenv file is loaded. An explicitly selected file must exist; a typo does not silently fall back to some unrelated `.env` lurking elsewhere like a credential poltergeist. + +Use a custom file when needed: + +```powershell +uv run okf test-llm --env-file "D:\secrets\okf.env" +``` + +`.env` is ignored by Git. `.env.example` is safe to commit and contains no real credentials. + +For migration, the old `OPENKB_LLM_*` names remain accepted as fallback values. + ## Compile one Markdown file Without LLM: @@ -65,7 +111,13 @@ Without LLM: uv run okf compile article.md --no-llm ``` -With an OpenAI-compatible endpoint: +With `.env` configured, no repeated LLM flags are needed: + +```powershell +uv run okf compile article.md +``` + +CLI flags remain available for one-off overrides: ```powershell uv run okf compile article.md ` @@ -96,23 +148,6 @@ Input selection priority in `wechat` mode: 4. The only Markdown file in the directory. 5. Otherwise the directory is reported as ambiguous and skipped. -## Environment variables - -```env -OKF_LLM_BASE_URL=https://api.example.com/v1 -OKF_LLM_MODEL=your-model -OKF_LLM_API_KEY=your-key -OKF_LLM_TIMEOUT=120 -``` - -For migration, the old `OPENKB_LLM_*` names remain accepted as fallback values. - -Test configuration: - -```powershell -uv run okf test-llm -``` - ## Sectioning rules - H1 is treated as the document title. diff --git a/pyproject.toml b/pyproject.toml index d6f69ce..fca22f9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "okf-compiler" -version = "0.1.0" +version = "0.1.1" description = "Compile Markdown articles into isolated, self-contained OKF Bundles." readme = "README.md" requires-python = ">=3.10" diff --git a/src/okf_compiler/cli.py b/src/okf_compiler/cli.py index f284e28..1ef1e67 100644 --- a/src/okf_compiler/cli.py +++ b/src/okf_compiler/cli.py @@ -16,11 +16,36 @@ def _llm_options(fn): click.option("--api-key", default=None, help="LLM API key. Env: OKF_LLM_API_KEY."), click.option("--model", default=None, help="LLM model. Env: OKF_LLM_MODEL."), click.option("--base-url", default=None, help="OpenAI-compatible base URL."), + click.option( + "--env-file", + type=click.Path(exists=True, dir_okay=False, path_type=Path), + default=None, + envvar="OKF_ENV_FILE", + help="Dotenv file. Defaults to .env in CWD, then beside the input.", + ), ): fn = decorator(fn) return fn +def _resolve_llm_config( + *, + base_url: str | None, + model: str | None, + api_key: str | None, + timeout: float | None, + env_file: Path | None, + search_dir: Path, +): + return resolve_config( + base_url=base_url, + model=model, + api_key=api_key, + timeout=timeout, + dotenv=load_dotenv_values(env_file, search_dirs=[search_dir]), + ) + + @click.group(context_settings={"help_option_names": ["-h", "--help"]}) @click.version_option(package_name="okf-compiler") def main() -> None: @@ -52,17 +77,19 @@ def compile_cmd( model: str | None, api_key: str | None, timeout: float | None, + env_file: Path | None, ) -> None: """Compile one Markdown file into one .okf.zip.""" target = out or input_md.with_name(input_md.stem + ".okf.zip") config = None if not no_llm: - config = resolve_config( + config = _resolve_llm_config( base_url=base_url, model=model, api_key=api_key, timeout=timeout, - dotenv=load_dotenv_values(), + env_file=env_file, + search_dir=input_md.parent, ) result = compile_one( input_md, @@ -130,16 +157,18 @@ def compile_dir_cmd( model: str | None, api_key: str | None, timeout: float | None, + env_file: Path | None, ) -> None: """Compile a directory, producing one OKF Bundle per Markdown article.""" config = None if not no_llm: - config = resolve_config( + config = _resolve_llm_config( base_url=base_url, model=model, api_key=api_key, timeout=timeout, - dotenv=load_dotenv_values(), + env_file=env_file, + search_dir=input_dir, ) def progress(result, completed: int, total: int) -> None: @@ -181,14 +210,16 @@ def test_llm_cmd( model: str | None, api_key: str | None, timeout: float | None, + env_file: Path | None, ) -> None: """Test the configured OpenAI-compatible endpoint.""" - config = resolve_config( + config = _resolve_llm_config( base_url=base_url, model=model, api_key=api_key, timeout=timeout, - dotenv=load_dotenv_values(), + env_file=env_file, + search_dir=Path.cwd(), ) try: click.echo(LLMClient(config).test()) diff --git a/src/okf_compiler/llm.py b/src/okf_compiler/llm.py index 3a59370..9fe1321 100644 --- a/src/okf_compiler/llm.py +++ b/src/okf_compiler/llm.py @@ -28,6 +28,7 @@ ENV_MODEL = "OKF_LLM_MODEL" ENV_API_KEY = "OKF_LLM_API_KEY" ENV_TIMEOUT = "OKF_LLM_TIMEOUT" +ENV_FILE = "OKF_ENV_FILE" _LEGACY = { ENV_BASE_URL: "OPENKB_LLM_BASE_URL", ENV_MODEL: "OPENKB_LLM_MODEL", @@ -50,8 +51,58 @@ def is_configured(self) -> bool: return bool(self.model and self.model.strip()) -def load_dotenv_values(path: Path | None = None) -> dict[str, str]: - values = dotenv_values(path or ".env") +def find_dotenv_path( + path: Path | None = None, + *, + search_dirs: list[Path] | tuple[Path, ...] | None = None, + env: dict[str, str] | None = None, +) -> Path | None: + """Resolve the one dotenv file used for a command. + + Resolution order: + 1. explicit ``path`` / ``--env-file``; + 2. ``OKF_ENV_FILE`` from the process environment; + 3. ``.env`` in the current working directory; + 4. ``.env`` in each caller-provided search directory. + + Only one file is loaded. Explicit/configured files must exist so a typo + cannot silently fall back to unrelated credentials. + """ + current_env = dict(os.environ) if env is None else env + explicit = path + if explicit is None: + configured = current_env.get(ENV_FILE) + explicit = Path(configured).expanduser() if configured else None + + if explicit is not None: + candidate = Path(explicit).expanduser().resolve() + if not candidate.is_file(): + raise FileNotFoundError(f"dotenv file not found: {candidate}") + return candidate + + candidates = [Path.cwd()] + candidates.extend(Path(item) for item in (search_dirs or [])) + seen: set[Path] = set() + for directory in candidates: + candidate = (directory.expanduser() / ".env").resolve() + if candidate in seen: + continue + seen.add(candidate) + if candidate.is_file(): + return candidate + return None + + +def load_dotenv_values( + path: Path | None = None, + *, + search_dirs: list[Path] | tuple[Path, ...] | None = None, + env: dict[str, str] | None = None, +) -> dict[str, str]: + resolved = find_dotenv_path(path, search_dirs=search_dirs, env=env) + if resolved is None: + return {} + values = dotenv_values(resolved) return {str(k): str(v) for k, v in values.items() if k and v is not None} @@ -64,8 +115,8 @@ def resolve_config( env: dict[str, str] | None = None, dotenv: dict[str, str] | None = None, ) -> LLMConfig: - env = env or dict(os.environ) - dotenv = dotenv or load_dotenv_values() + env = dict(os.environ) if env is None else env + dotenv = load_dotenv_values() if dotenv is None else dotenv def pick(value: str | None, name: str) -> str | None: if value and value.strip(): diff --git a/tests/test_okf_compiler.py b/tests/test_okf_compiler.py index 4c98f18..7974747 100644 --- a/tests/test_okf_compiler.py +++ b/tests/test_okf_compiler.py @@ -7,6 +7,7 @@ from okf_compiler.assets import collect_images from okf_compiler.cli import main from okf_compiler.compiler import CompileOptions, compile_dir, compile_one, enumerate_inputs +from okf_compiler.llm import load_dotenv_values, resolve_config from okf_compiler.markdown import extract_title, split_sections @@ -133,3 +134,63 @@ def test_cli_compile_no_llm(tmp_path: Path): ) assert result.exit_code == 0, result.output assert out.is_file() + + +def test_dotenv_discovery_and_config_precedence(tmp_path: Path, monkeypatch): + (tmp_path / ".env").write_text( + "OKF_LLM_BASE_URL=https://dotenv.example/v1\n" + "OKF_LLM_MODEL=dotenv-model\n" + "OKF_LLM_API_KEY=dotenv-key\n" + "OKF_LLM_TIMEOUT=45\n", + encoding="utf-8", + ) + monkeypatch.chdir(tmp_path) + dotenv = load_dotenv_values(env={}) + config = resolve_config( + base_url=None, + model=None, + api_key="cli-key", + timeout=None, + env={"OKF_LLM_MODEL": "env-model"}, + dotenv=dotenv, + ) + assert config.base_url == "https://dotenv.example/v1" + assert config.model == "env-model" + assert config.api_key == "cli-key" + assert config.timeout == 45 + + +def test_dotenv_discovery_falls_back_to_input_dir(tmp_path: Path, monkeypatch): + cwd = tmp_path / "cwd" + input_dir = tmp_path / "articles" + cwd.mkdir() + input_dir.mkdir() + (input_dir / ".env").write_text("OKF_LLM_MODEL=input-model\n", encoding="utf-8") + monkeypatch.chdir(cwd) + values = load_dotenv_values(search_dirs=[input_dir], env={}) + assert values["OKF_LLM_MODEL"] == "input-model" + + +def test_cli_test_llm_accepts_env_file(tmp_path: Path, monkeypatch): + env_file = tmp_path / "custom.env" + env_file.write_text( + "OKF_LLM_BASE_URL=https://custom.example/v1\n" + "OKF_LLM_MODEL=custom-model\n" + "OKF_LLM_API_KEY=custom-key\n", + encoding="utf-8", + ) + captured = {} + + class FakeClient: + def __init__(self, config): + captured["config"] = config + + def test(self): + return '{"ok": true}' + + monkeypatch.setattr("okf_compiler.cli.LLMClient", FakeClient) + result = CliRunner().invoke(main, ["test-llm", "--env-file", str(env_file)]) + assert result.exit_code == 0, result.output + assert captured["config"].base_url == "https://custom.example/v1" + assert captured["config"].model == "custom-model" + assert captured["config"].api_key == "custom-key"