Module llm_command 

CommandLlmClient — the shell-out extensibility escape hatch.

Spawns a user-supplied command per extraction call, writes a JSON request to its stdin, and reads a JSON response from its stdout. Use this to plug in any provider Engram does not ship natively — an internal corporate LLM gateway, an exotic model behind a custom RPC, a local inference binary, or a quick wrapper over any HTTP API with whatever auth scheme you need.

The contract

Engram invokes your command through sh -c <command> (so $HOME, pipes, redirects, and environment variables all work). The command must:

1. Read exactly one JSON object from stdin, matching:

   {"system": "...", "user": "...", "structured": true}

   structured is true when Engram wants JSON output (extraction, consolidation), false when it wants plain text.

2. Write exactly one JSON value to stdout. Either:

   • Plain: the JSON value that Engram should use directly.
   • Enveloped: {"content": <value>} or {"error": "message"}.

3. Exit with code 0 on success, non-zero on failure. On non-zero exit, stderr is surfaced to the caller.

Example wrapper (Python, ~15 lines)

#!/usr/bin/env python3
# my-llm.py — wraps any Python LLM SDK for Engram.
import json, sys
from my_llm_sdk import chat  # your SDK

req = json.loads(sys.stdin.read())
resp = chat(system=req["system"], user=req["user"],
            json_mode=req.get("structured", False))
# Either write the raw response:
sys.stdout.write(json.dumps(resp))
# Or envelope it:
# sys.stdout.write(json.dumps({"content": resp}))

Then point Engram at it:

ENGRAM_LLM_PROVIDER=command \
ENGRAM_LLM_COMMAND="python /path/to/my-llm.py" \
engram serve

Security

CommandLlmClient runs arbitrary commands as the Engram process user. Never expose it in a multi-tenant deployment where untrusted users can control ENGRAM_LLM_COMMAND. It is a local and single-tenant feature.

Structs

CommandLlmClient

A shell-out LLM client. Clone-cheap: stores only the command string and timeout configuration.