Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 53 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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 `
Expand Down Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
43 changes: 37 additions & 6 deletions src/okf_compiler/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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())
Expand Down
59 changes: 55 additions & 4 deletions src/okf_compiler/llm.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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}


Expand All @@ -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():
Expand Down
61 changes: 61 additions & 0 deletions tests/test_okf_compiler.py
Original file line number Diff line number Diff line change
Expand Up @@ -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


Expand Down Expand Up @@ -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"
Loading