Provider AI dan Kontrak Plugin

AIClient adalah satu-satunya objek yang dipakai agen untuk berbicara dengan model. Ia tidak memuat logika provider: seluruh pekerjaan didelegasikan ke instance BaseProvider yang dibuat factory get_provider saat konstruksi. AIClient.__init__ memanggil get_provider(config), menyalin provider.get_model_name() ke model_name, lalu mencatat satu baris log ai/ai_client.py:20-31¹.

Permukaan AIClient

AIClient hanya menyimpan config dan model_name miliknya sendiri; method generasi lainnya adalah pendelegasian tipis ke self.provider ai/ai_client.py:35-76⁷. Alias GeminiClient = AIClient dipertahankan untuk pemanggil lama ai/ai_client.py:163-164⁸.

get_token_report adalah pengecualian: ia membaca memory.token_ledger dan memory.get_token_summary(), bukan provider ai/ai_client.py:92-150⁵. Laporan itu ditutup dengan catatan bahwa biaya adalah estimasi dari ai.pricing pada config/guardian.yaml ai/ai_client.py:145-146⁹. Penulisan TokenUsage ke memory dilakukan pemanggil, misalnya BaseAgent._record_usage_and_step core/agent.py:267-288¹⁰; rincian ledger dan laporan ada di Sistem Multi-Agen dan Pelaporan, CVSS, dan Exporter.

Factory get_provider dan registry

graph LR
  CFG["config ai.provider"] --> GP["get_provider"]
  GP --> DISC["_discover_plugin_providers"]
  DISC --> TREE["PROVIDERS dict"]
  DISC --> EP["entry point group guardian.providers"]
  TREE --> MERGED["merged registry"]
  EP --> MERGED
  EP --> SKIP["WARNING: plugin ignored"]
  MERGED --> LOAD["importlib.import_module + getattr"]
  LOAD --> INST["provider_class(config, logger)"]
  INST --> CLIENT["AIClient.provider"]
  style GP fill:#f59e0b,color:#000
  style MERGED fill:#8b5cf6,color:#fff
  style INST fill:#2d7d46,color:#fff
  style SKIP fill:#dc2626,color:#fff
%% fig: Resolusi provider dari config ke instance
%% desc: get_provider menggabungkan registry in-tree dengan entry point guardian.providers, mengimpor kelas provider, lalu membuat instance-nya.

Registry in-tree memuat delapan nama: gemini, openai, claude, openrouter, requesty, ollama, openai_compatible, dan litellm ai/providers/__init__.py:19-29¹¹. Tiga nama terakhir sengaja dikirim in-tree tetapi mengikuti kontrak plugin yang sama ai/providers/__init__.py:25-28¹².

Nama provider dibaca dari ai.provider dan di-lowercase dengan default gemini. Nama yang tidak ada di registry ditolak sebelum impor apa pun:

ValueError: Unknown provider: <nama>. Available providers: <daftar terurut>

Pesan itu dirangkai dari sorted(registry.keys()) ai/providers/__init__.py:95-99¹³. Nilai registry berbentuk module.path.ClassName; get_provider memecahnya dengan rsplit(".", 1), memanggil importlib.import_module, mengambil kelas dengan getattr, lalu menjalankan provider_class(config, logger) ai/providers/__init__.py:101-111¹⁴. ImportError dipetakan ke RuntimeError dengan pesan Failed to import provider ..., kegagalan lain ke Failed to initialize provider ... ai/providers/__init__.py:113-119¹⁵.

Plugin ditemukan lewat grup entry point guardian.providers; hasil gabungan disimpan di _discovered_cache supaya entry point hanya dibaca sekali per proses ai/providers/__init__.py:31-33¹⁶. Penggabungan terjadi di _discover_plugin_providers ai/providers/__init__.py:35-73¹⁷. Bila nama plugin bertabrakan dengan nama in-tree, entri in-tree yang menang dan plugin dilewati dengan log WARNING ai/providers/__init__.py:59-69¹⁸. list_available_providers() mengembalikan nama terurut dari registry gabungan itu ai/providers/__init__.py:122-124¹⁹.

Satu panggilan generate_with_usage

sequenceDiagram
  autonumber
  participant Agent as BaseAgent
  participant AC as AIClient
  participant P as BaseProvider subclass
  participant B as backend
  Agent->>AC: generate_with_usage
  AC->>P: delegate call
  P->>P: _apply_rate_limit
  P->>B: ainvoke via _with_retry
  B-->>P: response and token usage
  P->>P: _enforce_token_budget
  P->>P: _estimate_cost
  P-->>AC: usage dict
  AC-->>Agent: usage dict
  Agent->>Agent: _record_usage_and_step
%% fig: Siklus satu panggilan generate_with_usage
%% desc: AIClient meneruskan panggilan ke provider, yang mengatur rate limit, memanggil backend, lalu mengembalikan dict usage berisi angka token dan biaya.

AIClient.generate_with_usage meneruskan prompt, system_prompt, dan context apa adanya ke self.provider.generate_with_usage ai/ai_client.py:55-76³. Kontrak balikannya delapan kunci: response, reasoning, prompt_tokens, completion_tokens, total_tokens, cost_usd, model, dan provider ai/providers/base_provider.py:119-143²⁰. Setiap nama kunci itu juga yang dibaca _record_usage_and_step saat membentuk TokenUsage core/agent.py:267-288¹⁰.

Setiap provider mengambil angka token dari sumber metadata backend-nya sendiri. openai membaca response_metadata["token_usage"] ai/providers/openai_provider.py:147-162²¹, claude membaca response_metadata["usage"] dengan input_tokens dan output_tokens ai/providers/claude_provider.py:147-162²², sedangkan gemini membaca usage_metadata dengan prompt_token_count dan candidates_token_count ai/providers/gemini_provider.py:148-163²³.

⚠️ Dua helper BaseProvider tidak dipakai semua provider. Hanya ollama, openai_compatible, dan litellm yang membungkus panggilan backend dengan _with_retry sekaligus memanggil _enforce_token_budget ai/providers/ollama_provider.py:152-157²⁴, ai/providers/openai_compatible_provider.py:152-161²⁵, ai/providers/litellm_provider.py:173-182. openai, claude, dan gemini memakai blok try/except yang mencatat error lalu me-raise ulang, tanpa retry dan tanpa budget ai/providers/openai_provider.py:129-165, ai/providers/claude_provider.py:129-165, ai/providers/gemini_provider.py:130-165. Jadi ai.token_budget dan ai.retry_attempts tidak berpengaruh pada tiga provider LangChain itu.

Kontrak BaseProvider

BaseProvider adalah ABC dengan enam method wajib: _initialize, generate, generate_sync, generate_with_usage, get_model_name, dan is_available ai/providers/base_provider.py:94-153³⁰.

Kemampuan vision bersifat opsional. Default supports_vision() mengembalikan False dan generate_with_images melempar NotImplementedError dengan pesan ... does not implement generate_with_images. Use a vision-capable provider (gpt-4o, claude-3.5-sonnet, gemini-1.5-pro). ai/providers/base_provider.py:157-187³⁷. Yang meng-override hanya openai untuk gpt-4o/gpt-4-turbo/vision ai/providers/openai_provider.py:177-180³⁸ dan claude untuk claude-3/claude-4/claude-sonnet/claude-opus ai/providers/claude_provider.py:177-180³⁹. provider lain mewarisi default dan gagal dengan pesan eksplisit, bukan degradasi senyap.

Retry, rate limit, dan token budget

Bila config tidak menyebut apa pun, retry memakai _DEFAULT_RETRY_ATTEMPTS = 4, _DEFAULT_RETRY_BASE_DELAY = 1.0 detik, dan _DEFAULT_RETRY_MAX_DELAY = 30.0 detik ai/providers/base_provider.py:17-19⁴⁰. Nilai itu bisa ditimpa lewat ai.retry_attempts, ai.retry_base_delay, dan ai.retry_max_delay ai/providers/base_provider.py:78-81⁴¹. Jeda tiap percobaan diacak penuh: sleep_for = random.uniform(0, min(delay, retry_max_delay)), lalu delay digandakan sampai batas maksimum ai/providers/base_provider.py:269-277⁴².

Rate limit dihitung per instance: _min_request_interval = 60.0 / self.rate_limit, dengan default rate_limit 60 sehingga jaraknya 1 detik ai/providers/base_provider.py:72-76⁴³. Config bawaan repository memakai rate_limit: 2, artinya jarak minimum 30 detik antar panggilan config/guardian.yaml:45⁴⁴. asyncio.Lock hanya mengunci satu proses, bukan seluruh klaster.

stateDiagram-v2
  [*] --> NoBudget: ai.token_budget unset
  NoBudget --> NoBudget: early return
  [*] --> UnderBudget
  UnderBudget --> Warned: ratio >= 0.8
  Warned --> Warned: warning sekali saja
  UnderBudget --> Exhausted: ratio >= 1.0
  Warned --> Exhausted: ratio >= 1.0
  Exhausted --> [*]: raise TokenBudgetExceeded
%% fig: Keadaan token budget per instance provider
%% desc: _enforce_token_budget menambah pemakaian kumulatif, memberi warning sekali di 80%, dan menghentikan workflow dengan TokenBudgetExceeded di 100%.

Tanpa ai.token_budget, _enforce_token_budget hanya menambah _token_used lalu kembali lebih awal ai/providers/base_provider.py:83-90⁴⁵, ai/providers/base_provider.py:289-292⁴⁶. Dengan budget, rasio di atas atau sama dengan 1.0 melempar TokenBudgetExceeded dengan pesan Token budget exhausted: used {terpakai:,} of {budget:,} ai/providers/base_provider.py:294-297⁴⁷. Warning 80% hanya sekali, dijaga flag _budget_warned ai/providers/base_provider.py:298-303⁴⁸. Exception ini sengaja tidak ditelan oleh provider, jadi workflow bisa berhenti bersih (lihat Engine Workflow DSL v2).

Perhitungan biaya dari ai.pricing

_compute_cost membaca config["ai"]["pricing"][model], menafsirkan prompt dan completion sebagai USD per 1 juta token, lalu menghitung cost = (prompt_tokens * prompt_rate + completion_tokens * completion_rate) / 1_000_000 dan membulatkannya dengan round(cost, 8) ai/providers/base_provider.py:39-56⁴⁹.

Model yang tidak terdaftar menghasilkan 0.0 plus satu warning, bukan kegagalan senyap:

No pricing entry for model '<model>' in config.ai.pricing — cost will be reported as $0.00. Add the model to guardian.yaml to track spend.

Peringatan itu dijaga himpunan _priced_warned sehingga hanya muncul sekali per model per instance ai/providers/base_provider.py:42-50⁵⁰, ai/providers/base_provider.py:89-90⁵¹.

Angka di atas disalin dari blok ai.pricing config/guardian.yaml:50-68⁵². ollama tidak memakai tabel ini untuk biaya: provider lokal itu selalu mengembalikan cost_usd: 0.0 ai/providers/ollama_provider.py:159-170⁵³, sementara openai_compatible memakai estimator kasar 4 karakter per token bila server tidak mengirim token_usage ai/providers/openai_compatible_provider.py:154-172⁵⁴.

Provider bawaan dan kemampuannya

Rujukan tiap baris: gemini ai/providers/gemini_provider.py:148-163²³, openai ai/providers/openai_provider.py:147-162²¹, claude ai/providers/claude_provider.py:147-162, ollama ai/providers/ollama_provider.py:141-170, openai_compatible ai/providers/openai_compatible_provider.py:149-172, dan litellm ai/providers/litellm_provider.py:173-193. Predikat retry litellm menambahkan kelas exception khas LiteLLM seperti litellm.exceptions.RateLimitError dan litellm.exceptions.Timeout di atas heuristik default ai/providers/litellm_provider.py:201-213. openrouter dan requesty juga terdaftar di registry dan mengikuti bentuk generate_with_usage yang sama ai/providers/__init__.py:19-29¹¹.

Menulis plugin lewat entry point guardian.providers

Plugin provider cukup mewarisi BaseProvider dan mengisi enam method wajib; helper _with_retry, _enforce_token_budget, _apply_rate_limit, dan _estimate_cost tersedia gratis bagi kelas turunan docs/PLUGIN_GUIDE.md:13-25⁵⁹.

# my_pkg/my_provider.py
from ai.providers.base_provider import BaseProvider

class MyProvider(BaseProvider):
    def __init__(self, config, logger):
        super().__init__(config, logger)
        self._initialize()

    async def generate_with_usage(self, prompt, system_prompt, context=None):
        await self._apply_rate_limit()
        # ... call your backend ...
        self._enforce_token_budget(total_tokens)
        return {
            "response": text,
            "reasoning": "",
            "prompt_tokens": pt,
            "completion_tokens": ct,
            "total_tokens": pt + ct,
            "cost_usd": self._estimate_cost(pt, ct),
            "model": self.get_model_name(),
            "provider": "my_provider",
        }

Pola itu persis yang ditunjukkan docs/PLUGIN_GUIDE.md:26-53⁶⁰. Pendaftarannya di pyproject.toml milik paket plugin:

[project.entry-points."guardian.providers"]
my_provider = "my_pkg.my_provider:MyProvider"

Baru setelah itu nama tersebut bisa dipakai dari config/guardian.yaml docs/PLUGIN_GUIDE.md:55-69⁶¹:

ai:
  provider: my_provider
  my_provider:
    api_key: ...

Nama plugin wajib berbeda dari kedelapan nama in-tree. Entri yang bertabrakan diabaikan dengan log WARNING, bukan ditimpa, jadi salah ketik nama plugin berakhir sebagai provider default alih-alih diam-diam mengganti provider inti docs/PLUGIN_GUIDE.md:102-106⁶².

⚠️ Plugin provider berjalan sebagai kode di dalam proses Guardian. Entry point adalah batas kepercayaan yang setara dengan pip install; pasang hanya plugin dari sumber tepercaya dan jalankan Guardian di dalam container untuk plugin eksperimental docs/PLUGIN_GUIDE.md:122-127⁶³.

Untuk kontrak plugin pada sisi tool, lihat Integrasi Tool dan Pemilihan Tool. Untuk penyusunan URL dasar dan kunci API pada guardian.yaml, lihat Instalasi, Konfigurasi, dan Deployment.