OpenRouter 를 standarda-core 에 붙였다: .env 만 채우면 쓴다

standarda-core 에 OpenRouter LLM 백엔드가 추가됐다. 덕분에 프로젝트는 붙이는 코드를 따로 짤 필요 없이 .env 에 값만 채우면 OpenRouter 를 쓸 수 있다.

1. 무엇이 바뀌었나: OpenRouter 가 core 로 들어왔다

standarda-core 에 get_openrouter_llm() 백엔드 팩토리가 추가됐다. core 에는 이미 get_openai_llm(), get_anthropic_llm(), get_google_llm() 이 있었고, OpenRouter 팩토리가 같은 파일(standarda_core/llm.py)에 하나 더 자리 잡은 것이다.

원래는 한 프로젝트가 로컬에 두고 쓰던 로직이었는데, 다른 프로젝트에서도 같은 요구가 생기자 순수 팩토리만 떼어 core 로 올렸다. 두 곳 이상에서 필요해지면 core 로 승격하는 이 흐름은 프롬프트 캐싱 승격과 같고, 그 이력은 standarda 변경 이력 추적의 changelog 에 남는다.

정리하면 OpenRouter 를 붙이는 코드는 이제 core 안에 다 들어가 있고, 프로젝트가 할 일은 값을 채우는 것뿐이다.

2. 쓰는 법 = .env 에 값 채우기

이 백엔드가 읽는 설정은 모두 .env 에 있다. standarda-template 의 .env.example 과 .env.production.example 에도 OpenRouter 블록을 미리 넣어 뒀으므로(PR #67, 2026-08-18), 새 프로젝트라면 빈 칸만 채우면 된다.

OPENROUTER_API_KEY=            # OpenRouter 에서 발급한 키
OPENROUTER_MODEL=openai/gpt-5.1   # provider/model 형식 (기본값 없음, 필수)
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_TEMPERATURE=0.3
OPENROUTER_INCLUDE_USAGE=true   # 응답에 실비(USD) 포함

3. 코드에서는 한 줄

설정을 채웠다면 호출부는 다른 provider 팩토리와 다르지 않다.

from standarda_core.llm import get_openrouter_llm

llm = get_openrouter_llm()
if llm is None:
    raise RuntimeError("OpenRouter LLM 초기화 실패: .env 의 OPENROUTER_API_KEY 를 확인하세요.")
response = llm.invoke("...")

provider 와 model, 실비 집계 여부는 기본적으로 .env 가 정하고, 필요하면 코드에서 인자로 덮어쓴다(§4). core 팩토리로 만들기 때문에 LangSmith 트레이싱도 자동으로 이어진다(프로젝트 규칙상 LLM 은 항상 core 팩토리로 만든다, CLAUDE.md ## Code Patterns > LLM Calls).

Q. 키만 채우면 바로 되나?

A. OPENROUTER_API_KEY 와 OPENROUTER_MODEL 이 함께 있어야 한다. 키가 없으면 팩토리가 None 을 돌려주므로 호출부에서 if llm is None: 으로 걸러야 하고, 모델이 없으면 기본값이 없어 ValueError 가 난다.

4. 모델은 .env 기본값, 코드로 덮어쓸 수 있다

.env 의 OPENROUTER_MODEL 은 고정값이 아니라 기본값이다. get_openrouter_llm() 이 인자를 받고 인자가 env 보다 우선하므로, 한 프로세스 안에서 호출마다 다른 모델을 쓰고 싶다면 그 자리에서 바꿔 주면 된다.

# .env 의 OPENROUTER_MODEL 을 무시하고 이 호출만 다른 모델로
llm = get_openrouter_llm(model="anthropic/claude-sonnet-4", temperature=0)

우선순위는 인자로 넘긴 model, 없으면 .env 의 OPENROUTER_MODEL, 그것도 없으면 ValueError 순이다. model 말고 api_key, base_url, temperature, max_tokens, include_usage 같은 값도 마찬가지로 인자가 env 를 덮는다(전체 시그니처는 standarda_core/llm.py 의 get_openrouter_llm 에 있다).

5. 기존 프로젝트에 붙이려면

붙이는 절차는 세 단계다.

1. requirements.txt 의 standarda-core 태그를 @v0.18.0 이상으로 올린다. OpenRouter 가 처음 들어온 버전이 v0.18.0 이고, 현재 최신은 v0.27.0 이니 새로 붙인다면 최신 태그를 쓴 뒤 pip install -r requirements.txt 한다.

text standarda-core @ git+https://github.com/popupstudio-ai/standarda-core.git@v0.27.0 2. .env 에 OPENROUTER_* 값을 채운다. 3. .env.example 에 블록이 없으면 sync-from-template로 최신 예시를 받아 온다.

이후 from standarda_core.llm import get_openrouter_llm 로 가져다 쓰면 된다.

마무리

• 핵심 정리: OpenRouter 는 이제 standarda-core 의 백엔드 팩토리(get_openrouter_llm)로 들어와 있다. 프로젝트는 붙이는 코드를 새로 짜지 않고, .env 에 OPENROUTER_* 값을 채운 다음 get_openrouter_llm() 한 줄로 가져다 쓰면 된다.
• 주의 사항: OPENROUTER_API_KEY(없으면 None)와 OPENROUTER_MODEL(없으면 ValueError)이 둘 다 있어야 한다. 하나라도 비면 동작하지 않는다.
• 다음 시간: 같은 core 승격 계열인 프롬프트 캐싱에 이어, 공용 로직을 언제 core 로 올리고 어떻게 전파하는지를 standarda 변경 이력 추적과 연결한다.