DEV Community: Kiell Tampubolon

From DNS Security Trainer to ICANN87 Fellow: What a Cybersecurity Engineer Looks for in Bali

Kiell Tampubolon — Thu, 15 Oct 2026 15:30:21 +0000

In July 2024 I sat in a training room in Nusa Dua with a laptop and too many DNS diagrams. PANDI, the registry that runs Indonesia's .id domain, was running a Training of Trainer program, and some of the instructors came from ICANN. We started at "how does a name turn into an IP address" and ended at DNSSEC signatures and chains of trust. I went home with a notebook full of drawings and a habit I still have: I can't look at a phishing link anymore without wondering who registered that domain, and when.

Next week I'm going back to the same stretch of coast. ICANN87, ICANN's Annual General Meeting, runs from 17 to 22 October 2026 at the Bali International Convention Centre in Nusa Dua, and I'll be there as one of PANDI's fellows.

I'm excited about it, the kind of excited where you read meeting schedules for fun. So before I land, I want to write down what I hope to learn and what I want to give back, and check myself against it afterwards.

The internet's address book has a meeting

Most people in my classes have never heard of ICANN, and that's fine. Every time you open a website, send an email or let an AI agent fetch a URL, something has to turn a name into an address. That something is DNS. ICANN coordinates the top of that system: the root zone, the rules for top-level domains, and the policy work that decides how names are handed out and what happens when they're abused.

The part that surprised me when I first learned it is who writes those rules. No single company or government does. Governments, registries like PANDI, registrars, security advisors and ordinary internet users each have a seat, and they work things out in open meetings. ICANN87 is one of those meetings, and the Annual General Meeting is the biggest one of the year.

Simplified: who runs which layer of the DNS, and who shapes the rules

Where I'm coming from

I'm not a policy person. My day job is security engineering, and a lot of it happens at the receiving end of DNS problems. When a suspicious email comes in, one of the first things I look at is the sender's domain. How old is it? Does it copy a real brand with one letter swapped? Did it even exist last month? Lookalike domains are a big part of the phishing I triage, so I've spent a lot of time on the abuse side of the DNS without ever seeing how the people who run it think about the problem.

Outside work, I've been a .id Academy trainer with PANDI since 2024, running bootcamps at UNIMA in Manado and ITEBA in Batam. The rooms are a mix of students, lecturers and people who just bought a .id domain for their small business. And these days a growing part of my work is AI agent and MCP security, which brings DNS back in a way I didn't expect. An agent that browses or calls tools resolves domain names too, and it trusts the answer the same way a browser does, often with no human looking at the link first.

Two years from a DNS classroom in Nusa Dua to ICANN87 in Nusa Dua

What I'm looking for in Bali

First, DNS abuse from the policy side. I know what abuse looks like in an inbox. I know much less about how registries and registrars decide what counts as abuse, how fast they're expected to act, and where it gets hard, like false positives or taking down a domain that turns out to be legitimate. I want to hear that argument from people who deal with it every day.

Second, DNSSEC in real deployments. In the ToT we learned how DNSSEC signs DNS answers so a resolver can tell if someone tampered with them. ICANN meetings usually include a DNSSEC and security workshop, and I want operators' stories about what breaks in practice. My students ask me that question and right now I only have textbook answers.

Here's the kind of check I want every student to be able to run on their own domain:

# Is the zone signed? RRSIG records in the answer mean yes.
dig +dnssec SOA .

# Does my resolver validate? Look for the "ad" flag in the header.
dig +dnssec icann.org A

Third, AI agents as DNS clients. This one is a hunch more than a plan. Agents are turning into heavy DNS users without anyone deciding that on purpose. I'm curious whether people in the ICANN community are already talking about it, and if they aren't, whether there's a useful paper in it.

What I want to give back

PANDI asks each fellow to turn the week into a contribution, written up as a paper. I like that a lot. It gives the week a deliverable, and I work better with one. My rough plan is a loop: listen, connect what I hear to what I see at work, write it up for PANDI, turn it into .id Academy material, and publish the open parts here.

The plan for the week, and what happens after it

I haven't locked the paper topic yet. I'm leaning toward the place where my two worlds overlap: what DNS abuse looks like from a defender's inbox, and what Indonesian domain owners and trainers can realistically do about it. If the AI agent thread turns out to have legs, that could become its own piece.

The classroom part matters most to me. When I teach in Manado or Batam, students rarely ask about root servers. They ask how to tell if a link is safe, or what to do when someone makes a fake copy of their campus website. If I can walk back into those rooms with better answers, and with names of the people and processes that handle these problems, the week will have been worth it.

If you'll be there

If you're at ICANN87, in Nusa Dua or online, and you work on DNS abuse, DNSSEC or anything where AI agents meet the DNS, I'd like to talk. I'll be the one taking too many notes. I'll post what I learn after the meeting, including whatever this post got wrong.

From DNS Security Trainer to ICANN87 Fellow: What a Cybersecurity Engineer Looks for in Bali

Kiell Tampubolon — Thu, 15 Oct 2026 15:08:16 +0000

The internet's address book has a meeting

Simplified: who runs which layer of the DNS, and who shapes the rules

Where I'm coming from

Two years from a DNS classroom in Nusa Dua to ICANN87 in Nusa Dua

What I'm looking for in Bali

Here's the kind of check I want every student to be able to run on their own domain:

# Is the zone signed? RRSIG records in the answer mean yes.
dig +dnssec SOA .

# Does my resolver validate? Look for the "ad" flag in the header.
dig +dnssec icann.org A

What I want to give back

The plan for the week, and what happens after it

If you'll be there

Cara Bypass Rate Limit API Secara Etis Pakai Local Proxy

Kiell Tampubolon — Tue, 13 Oct 2026 15:35:13 +0000

Cerita di balik masalah

Kamu sedang menyambungkan automation ke sebuah API. Script jalan lancar lima menit pertama, lalu mulai muntah 429. Kamu tambah delay, tetap kena. Kamu bagi proses jadi beberapa worker, kena lagi.

Rate limit itu bukan musuh. Itu cara penyedia API melindungi infrastrukturnya dan menjaga kualitas layanan untuk semua orang. Masalahnya, banyak client menulis ulang logika penanganan limit yang sama di setiap project: retry di sini, sleep di sana, dan satu worker nakal yang merusak semuanya.

Solusi yang rapi: taruh satu komponen di tengah, yaitu local proxy. Semua request dari aplikasimu lewat proxy ini, dan proxy yang menangani rate limit secara terpusat.

Kapan kita butuh proxy lokal

Tiga situasi di mana proxy lokal masuk akal:

Retry backoff. Kamu tidak mau setiap service punya logika retry sendiri. Satu tempat, satu kebijakan.
Queueing. Saat limit hampir habis, request antre dulu, bukan langsung gagal.
Multi endpoint pooling. Kalau penyedia API memberi beberapa key atau endpoint, proxy bisa memutar beban antar keduanya. Catatan penting: rotasi key untuk menghindari limit adalah pelanggaran ToS di banyak layanan. Gunakan pooling hanya kalau ToS mengizinkan, misalnya beberapa akun organisasi yang memang sah.

Arsitekturnya sederhana

+--------+     +-------------+     +--------------+
| Client | --> | Local Proxy | --> | Upstream API |
+--------+     +-------------+     +--------------+
                     |
              +------+------+
              | Token bucket |
              | Queue        |
              | Retry logic  |
              | Cache        |
              +--------------+

Client hanya tahu satu alamat: proxy. Proxy yang tahu kapan harus menahan, kapan harus mencoba ulang, dan kapan boleh langsung lewat.

Implementasi minimal dengan Python

Ini versi kecil pakai FastAPI dan httpx, sekitar 60 baris:

import asyncio, time
import httpx
from fastapi import FastAPI, Request, Response

UPSTREAM = "https://api.example.com"
RATE = 5          # request per detik
_app = FastAPI()
_bucket_last = 0.0
_lock = asyncio.Lock()

async def acquire():
    global _bucket_last
    async with _lock:
        now = time.monotonic()
        wait = (1 / RATE) - (now - _bucket_last)
        if wait > 0:
            await asyncio.sleep(wait)
        _bucket_last = time.monotonic()

@_app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE"])
async def proxy(path: str, request: Request):
    await acquire()
    async with httpx.AsyncClient(base_url=UPSTREAM, timeout=30) as c:
        r = await c.request(
            request.method, f"/{path}",
            content=await request.body(),
            headers={k: v for k, v in request.headers.items()
                     if k.lower() not in ("host", "content-length")},
            params=request.query_params,
        )
    if r.status_code == 429:
        retry_after = float(r.headers.get("retry-after", "2"))
        await asyncio.sleep(retry_after)
        return await proxy(path, request)   # retry sekali lagi
    return Response(content=r.content, status_code=r.status_code,
                    headers=dict(r.headers))

Jalankan dengan uvicorn proxy:app --port 8080, lalu arahkan semua client ke http://localhost:8080. Selesai. Logika limit kini hidup di satu tempat.

Versi Node.js juga ringkas, tapi polanya sama: middleware yang menghitung token, queue yang menahan request, dan retry yang menghormati header Retry-After.

Tips etis

Bagian paling penting dari artikel ini. Proxy lokal adalah alat untuk jadi client yang lebih baik, bukan untuk lolos dari aturan.

Hormati ToS. Baca ketentuan layanan sebelum membangun apa pun. Kalau ToS melarang rotasi akun atau key, jangan lakukan. Kalau melarang scraping, jangan scraping.
Hormati Retry-After. Kalau server memberi tahu kapan boleh mencoba lagi, patuhi angkanya. Jangan paksa.
Cache respons. Rate limit paling murah adalah yang tidak perlu dikirim. Cache GET dengan TTL wajar, invalidasi saat ada write.
Exponential backoff dengan jitter. Jangan retry semua worker di detik yang sama. Tambahkan noise acak supaya tidak terjadi thundering herd.
Circuit breaker. Kalau upstream terus gagal, berhenti menghantam. Tandai circuit terbuka selama beberapa detik, lempar error yang jujur ke caller, lalu coba lagi pelan-pelan.
Pantau konsumsi limitmu sendiri. Banyak API mengembalikan sisa kuota di header (X-RateLimit-Remaining dan teman-temannya). Simpan nilai itu di proxy dan perlambat sebelum 429 datang, bukan sesudah.

Penutup

Rate limit bukan teka-teki untuk dipecahkan dengan trik. Ia sinyal dari server soal ritme yang wajar. Local proxy membuat codebase-mu mengikuti ritme itu secara otomatis: satu tempat untuk throttle, retry, dan cache, tanpa menyebar logika ke tiap service.

Cara Bypass Rate Limit API Secara Etis Pakai Local Proxy

Kiell Tampubolon — Tue, 13 Oct 2026 15:28:41 +0000

Cerita di balik masalah

Kamu sedang menyambungkan automation ke sebuah API. Script jalan lancar lima menit pertama, lalu mulai muntah 429. Kamu tambah delay, tetap kena. Kamu bagi proses jadi beberapa worker, kena lagi.

Solusi yang rapi: taruh satu komponen di tengah, yaitu local proxy. Semua request dari aplikasimu lewat proxy ini, dan proxy yang menangani rate limit secara terpusat.

Kapan kita butuh proxy lokal

Tiga situasi di mana proxy lokal masuk akal:

Retry backoff. Kamu tidak mau setiap service punya logika retry sendiri. Satu tempat, satu kebijakan.
Queueing. Saat limit hampir habis, request antre dulu, bukan langsung gagal.
Multi endpoint pooling. Kalau penyedia API memberi beberapa key atau endpoint, proxy bisa memutar beban antar keduanya. Catatan penting: rotasi key untuk menghindari limit adalah pelanggaran ToS di banyak layanan. Gunakan pooling hanya kalau ToS mengizinkan, misalnya beberapa akun organisasi yang memang sah.

Arsitekturnya sederhana

+--------+     +-------------+     +--------------+
| Client | --> | Local Proxy | --> | Upstream API |
+--------+     +-------------+     +--------------+
                     |
              +------+------+
              | Token bucket |
              | Queue        |
              | Retry logic  |
              | Cache        |
              +--------------+

Client hanya tahu satu alamat: proxy. Proxy yang tahu kapan harus menahan, kapan harus mencoba ulang, dan kapan boleh langsung lewat.

Implementasi minimal dengan Python

Ini versi kecil pakai FastAPI dan httpx, sekitar 60 baris:

import asyncio, time
import httpx
from fastapi import FastAPI, Request, Response

UPSTREAM = "https://api.example.com"
RATE = 5          # request per detik
_app = FastAPI()
_bucket_last = 0.0
_lock = asyncio.Lock()

async def acquire():
    global _bucket_last
    async with _lock:
        now = time.monotonic()
        wait = (1 / RATE) - (now - _bucket_last)
        if wait > 0:
            await asyncio.sleep(wait)
        _bucket_last = time.monotonic()

@_app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE"])
async def proxy(path: str, request: Request):
    await acquire()
    async with httpx.AsyncClient(base_url=UPSTREAM, timeout=30) as c:
        r = await c.request(
            request.method, f"/{path}",
            content=await request.body(),
            headers={k: v for k, v in request.headers.items()
                     if k.lower() not in ("host", "content-length")},
            params=request.query_params,
        )
    if r.status_code == 429:
        retry_after = float(r.headers.get("retry-after", "2"))
        await asyncio.sleep(retry_after)
        return await proxy(path, request)   # retry sekali lagi
    return Response(content=r.content, status_code=r.status_code,
                    headers=dict(r.headers))

Jalankan dengan uvicorn proxy:app --port 8080, lalu arahkan semua client ke http://localhost:8080. Selesai. Logika limit kini hidup di satu tempat.

Versi Node.js juga ringkas, tapi polanya sama: middleware yang menghitung token, queue yang menahan request, dan retry yang menghormati header Retry-After.

Tips etis

Bagian paling penting dari artikel ini. Proxy lokal adalah alat untuk jadi client yang lebih baik, bukan untuk lolos dari aturan.

Hormati ToS. Baca ketentuan layanan sebelum membangun apa pun. Kalau ToS melarang rotasi akun atau key, jangan lakukan. Kalau melarang scraping, jangan scraping.
Hormati Retry-After. Kalau server memberi tahu kapan boleh mencoba lagi, patuhi angkanya. Jangan paksa.
Cache respons. Rate limit paling murah adalah yang tidak perlu dikirim. Cache GET dengan TTL wajar, invalidasi saat ada write.
Exponential backoff dengan jitter. Jangan retry semua worker di detik yang sama. Tambahkan noise acak supaya tidak terjadi thundering herd.
Circuit breaker. Kalau upstream terus gagal, berhenti menghantam. Tandai circuit terbuka selama beberapa detik, lempar error yang jujur ke caller, lalu coba lagi pelan-pelan.
Pantau konsumsi limitmu sendiri. Banyak API mengembalikan sisa kuota di header (X-RateLimit-Remaining dan teman-temannya). Simpan nilai itu di proxy dan perlambat sebelum 429 datang, bukan sesudah.

Penutup

Cara Bypass Rate Limit API Secara Etis Pakai Local Proxy

Kiell Tampubolon — Tue, 13 Oct 2026 15:15:23 +0000

Cerita di balik masalah

Kamu sedang menyambungkan automation ke sebuah API. Script jalan lancar lima menit pertama, lalu mulai muntah 429. Kamu tambah delay, tetap kena. Kamu bagi proses jadi beberapa worker, kena lagi.

Solusi yang rapi: taruh satu komponen di tengah, yaitu local proxy. Semua request dari aplikasimu lewat proxy ini, dan proxy yang menangani rate limit secara terpusat.

Kapan kita butuh proxy lokal

Tiga situasi di mana proxy lokal masuk akal:

Retry backoff. Kamu tidak mau setiap service punya logika retry sendiri. Satu tempat, satu kebijakan.
Queueing. Saat limit hampir habis, request antre dulu, bukan langsung gagal.
Multi endpoint pooling. Kalau penyedia API memberi beberapa key atau endpoint, proxy bisa memutar beban antar keduanya. Catatan penting: rotasi key untuk menghindari limit adalah pelanggaran ToS di banyak layanan. Gunakan pooling hanya kalau ToS mengizinkan, misalnya beberapa akun organisasi yang memang sah.

Arsitekturnya sederhana

+--------+     +-------------+     +--------------+
| Client | --> | Local Proxy | --> | Upstream API |
+--------+     +-------------+     +--------------+
                     |
              +------+------+
              | Token bucket |
              | Queue        |
              | Retry logic  |
              | Cache        |
              +--------------+

Client hanya tahu satu alamat: proxy. Proxy yang tahu kapan harus menahan, kapan harus mencoba ulang, dan kapan boleh langsung lewat.

Implementasi minimal dengan Python

Ini versi kecil pakai FastAPI dan httpx, sekitar 60 baris:

import asyncio, time
import httpx
from fastapi import FastAPI, Request, Response

UPSTREAM = "https://api.example.com"
RATE = 5          # request per detik
_app = FastAPI()
_bucket_last = 0.0
_lock = asyncio.Lock()

async def acquire():
    global _bucket_last
    async with _lock:
        now = time.monotonic()
        wait = (1 / RATE) - (now - _bucket_last)
        if wait > 0:
            await asyncio.sleep(wait)
        _bucket_last = time.monotonic()

@_app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE"])
async def proxy(path: str, request: Request):
    await acquire()
    async with httpx.AsyncClient(base_url=UPSTREAM, timeout=30) as c:
        r = await c.request(
            request.method, f"/{path}",
            content=await request.body(),
            headers={k: v for k, v in request.headers.items()
                     if k.lower() not in ("host", "content-length")},
            params=request.query_params,
        )
    if r.status_code == 429:
        retry_after = float(r.headers.get("retry-after", "2"))
        await asyncio.sleep(retry_after)
        return await proxy(path, request)   # retry sekali lagi
    return Response(content=r.content, status_code=r.status_code,
                    headers=dict(r.headers))

Jalankan dengan uvicorn proxy:app --port 8080, lalu arahkan semua client ke http://localhost:8080. Selesai. Logika limit kini hidup di satu tempat.

Versi Node.js juga ringkas, tapi polanya sama: middleware yang menghitung token, queue yang menahan request, dan retry yang menghormati header Retry-After.

Tips etis

Bagian paling penting dari artikel ini. Proxy lokal adalah alat untuk jadi client yang lebih baik, bukan untuk lolos dari aturan.

Hormati ToS. Baca ketentuan layanan sebelum membangun apa pun. Kalau ToS melarang rotasi akun atau key, jangan lakukan. Kalau melarang scraping, jangan scraping.
Hormati Retry-After. Kalau server memberi tahu kapan boleh mencoba lagi, patuhi angkanya. Jangan paksa.
Cache respons. Rate limit paling murah adalah yang tidak perlu dikirim. Cache GET dengan TTL wajar, invalidasi saat ada write.
Exponential backoff dengan jitter. Jangan retry semua worker di detik yang sama. Tambahkan noise acak supaya tidak terjadi thundering herd.
Circuit breaker. Kalau upstream terus gagal, berhenti menghantam. Tandai circuit terbuka selama beberapa detik, lempar error yang jujur ke caller, lalu coba lagi pelan-pelan.
Pantau konsumsi limitmu sendiri. Banyak API mengembalikan sisa kuota di header (X-RateLimit-Remaining dan teman-temannya). Simpan nilai itu di proxy dan perlambat sebelum 429 datang, bukan sesudah.

Penutup

Cara Bypass Rate Limit API Secara Etis Pakai Local Proxy

Kiell Tampubolon — Tue, 13 Oct 2026 13:10:09 +0000

Cara Bypass Rate Limit API Secara Etis Pakai Local Proxy

Cerita di balik masalah

Kamu sedang menyambungkan automation ke sebuah API. Script jalan lancar lima menit pertama, lalu mulai muntah 429. Kamu tambah delay, tetap kena. Kamu bagi proses jadi beberapa worker, kena lagi.

Solusi yang rapi: taruh satu komponen di tengah, yaitu local proxy. Semua request dari aplikasimu lewat proxy ini, dan proxy yang menangani rate limit secara terpusat.

Kapan kita butuh proxy lokal

Tiga situasi di mana proxy lokal masuk akal:

Retry backoff. Kamu tidak mau setiap service punya logika retry sendiri. Satu tempat, satu kebijakan.
Queueing. Saat limit hampir habis, request antre dulu, bukan langsung gagal.
Multi endpoint pooling. Kalau penyedia API memberi beberapa key atau endpoint, proxy bisa memutar beban antar keduanya. Catatan penting: rotasi key untuk menghindari limit adalah pelanggaran ToS di banyak layanan. Gunakan pooling hanya kalau ToS mengizinkan, misalnya beberapa akun organisasi yang memang sah.

Arsitekturnya sederhana

Client hanya tahu satu alamat: proxy. Proxy yang tahu kapan harus menahan, kapan harus mencoba ulang, dan kapan boleh langsung lewat.

Implementasi minimal dengan Python

Ini versi kecil pakai FastAPI dan httpx, sekitar 60 baris:

import asyncio, time
import httpx
from fastapi import FastAPI, Request, Response

UPSTREAM = "https://api.example.com"
RATE = 5          # request per detik
_app = FastAPI()
_bucket_last = 0.0
_lock = asyncio.Lock()

async def acquire():
    global _bucket_last
    async with _lock:
        now = time.monotonic()
        wait = (1 / RATE) - (now - _bucket_last)
        if wait > 0:
            await asyncio.sleep(wait)
        _bucket_last = time.monotonic()

@_app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE"])
async def proxy(path: str, request: Request):
    await acquire()
    async with httpx.AsyncClient(base_url=UPSTREAM, timeout=30) as c:
        r = await c.request(
            request.method, f"/{path}",
            content=await request.body(),
            headers={k: v for k, v in request.headers.items()
                     if k.lower() not in ("host", "content-length")},
            params=request.query_params,
        )
    if r.status_code == 429:
        retry_after = float(r.headers.get("retry-after", "2"))
        await asyncio.sleep(retry_after)
        return await proxy(path, request)   # retry sekali lagi
    return Response(content=r.content, status_code=r.status_code,
                    headers=dict(r.headers))

Jalankan dengan uvicorn proxy:app --port 8080, lalu arahkan semua client ke http://localhost:8080. Selesai. Logika limit kini hidup di satu tempat.

Versi Node.js juga ringkas, tapi polanya sama: middleware yang menghitung token, queue yang menahan request, dan retry yang menghormati header Retry-After.

Tips etis

Bagian paling penting dari artikel ini. Proxy lokal adalah alat untuk jadi client yang lebih baik, bukan untuk lolos dari aturan.

Hormati ToS. Baca ketentuan layanan sebelum membangun apa pun. Kalau ToS melarang rotasi akun atau key, jangan lakukan. Kalau melarang scraping, jangan scraping.
Hormati Retry-After. Kalau server memberi tahu kapan boleh mencoba lagi, patuhi angkanya. Jangan paksa.
Cache respons. Rate limit paling murah adalah yang tidak perlu dikirim. Cache GET dengan TTL wajar, invalidasi saat ada write.
Exponential backoff dengan jitter. Jangan retry semua worker di detik yang sama. Tambahkan noise acak supaya tidak terjadi thundering herd.
Circuit breaker. Kalau upstream terus gagal, berhenti menghantam. Tandai circuit terbuka selama beberapa detik, lempar error yang jujur ke caller, lalu coba lagi pelan-pelan.
Pantau konsumsi limitmu sendiri. Banyak API mengembalikan sisa kuota di header (X-RateLimit-Remaining dan teman-temannya). Simpan nilai itu di proxy dan perlambat sebelum 429 datang, bukan sesudah.

Penutup

Bangun dia untuk menjadi tetangga yang baik di internet. API-mu, dan tim SRE penyedia layanannya, akan berterima kasih.

Best Open-Source Structured Data Extraction Models for Financial Reports

Kiell Tampubolon — Tue, 13 Oct 2026 02:30:34 +0000

Quick answer: Among open-weight models with a commercial licence and a size a single team can serve, Qwen3.8-27B is the strongest general extractor, and NuExtract3 is the best purpose-built one. Qwen3.5-4B and Qwen3-4B-Instruct-2507 cover stable, high-volume schemas cheaply, and GLiNER2 and NuNER_Zero tag entities on CPU. SIE serves the document models you put into production, on Cloud or in your cluster, behind one API.

The segment table came back clean. Four operating segments, each with a revenue figure, a period and a unit, and the schema validator passed every row. Then someone added the segments up and got a number larger than consolidated revenue. The model had read the "Intersegment eliminations" row as a positive figure, so the eliminations were added back instead of taken away. JSON validators are the most relaxed reviewers in finance. They check that a number is a number and ask nothing about its sign, its scale or which row it came from.

This ranking covers open-weight models with a licence that permits commercial use, turning report text or page images into fields such as revenue, period, unit, scale and segment. It assumes the text is already available: for EDGAR filings that means the HTML of the filing itself, and OCR only for PDF-only sources, which the companion list of open OCR models covers. Hosted frontier models are not ranked, but they get a direct comparison after the list.

One point before the models. For a US filer's face statements, you may not need a model at all. The SEC's XBRL APIs return tagged facts in base units. What those APIs leave out is where models earn their place: untagged tables in MD&A and EX-99.1 earnings releases, non-US annual reports that exist only as PDF, and the segment detail discussed below.

1. Qwen3.8-27B

Model card: Qwen/Qwen3.8-27B on Hugging Face

Qwen3.8-27B is a 27.8B dense model from Qwen with native vision-language input, licensed Apache-2.0, so commercial use is permitted. It reads page images directly, so a PDF page can go in without a separate OCR step when the layout allows.

It ranks first on evidence and capability together. Its card reports 91.1 on OmniDocBench v1.5, the strongest document-parsing figure among the generative models here. It takes text and images in one request, it can produce structured output under a JSON-schema grammar when the serving layer supports it, and it has a native context of 262,144 tokens, extensible to one million, which fits a full 10-K section with room for the schema. Thinking mode is on by default. For extraction, switch it off per request, or every field pays for reasoning you did not ask for.

The limit is size. Self-hosting a 27B model needs a large GPU, and the card reports no finance-specific extraction score.

Deployment shape: open weights. It is priced on SIE Cloud as Qwen/Qwen3.8-27B-FP8; the self-hosted catalog carries the previous generation, Qwen3.6-27B, also Apache-2.0 at 27.8B. It suits schemas that need judgement: segment tables, footnoted adjustments, and fields that depend on reading two rows together.

2. NuExtract3

Model card: numind/NuExtract3 on Hugging Face

NuExtract3 from NuMind is built for one job: filling a JSON template from a document. It is a 4B-parameter fine-tune of Qwen3.5-4B, released under Apache-2.0, so commercial use is permitted. It reads text and images, handles multilingual documents, and runs with a 131,072-token context in the vLLM configuration its card gives. NuMind also publishes quantised builds, including FP8 and GGUF.

The template language is its strength. You describe the fields, and the model returns null or an empty array when a value is absent. In finance that matters: a model that abstains on a missing segment figure is easier to trust than one that invents a plausible number. It also offers reasoning and non-reasoning modes, and it can convert pages to Markdown with tables as HTML.

The numbers are NuMind's. On its internal benchmark of about 600 documents, described as including invoices, movie posters and floor plans, the card reports 0.651 for NuExtract3 against 0.417 for its base, Qwen3.5-4B. On ExtractBench, the card reports a mean of 82.35. Neither set is described as covering financial filings.

Deployment shape: open weights you serve yourself, for example with vLLM, as the card shows. It suits teams that want template extraction with abstention from a model sized for one GPU.

3. Qwen3.5-4B

Model card: Qwen/Qwen3.5-4B on Hugging Face

Qwen3.5-4B is a small generative model, 4.66B parameters in its weights, licensed Apache-2.0, so commercial use is permitted. It shares the family's 262,144-token context and, like Qwen3.8, thinks by default unless you disable it.

Its place here is cost. For a dozen fields pulled from the same report section each period, a 4B model on a small GPU is often enough, and at volume the saving is the reason to test it. The card also reports an OmniDocBench v1.5 result; the rank here rests on size and cost. Whether it is accurate enough is a question only your evaluation set can answer, so test it on the hardest filers you cover, not the tidiest.

Deployment shape: open weights, in SIE's self-hosted catalog, and runnable locally. On SIE Cloud, priced extraction runs on Qwen3.8-27B (FP8). The 4B runs self-hosted or locally. It suits high-volume, stable schemas.

4. Qwen3-4B-Instruct-2507

Model card: Qwen/Qwen3-4B-Instruct-2507 on Hugging Face

Qwen3-4B-Instruct-2507 is an earlier 4B generation, licensed Apache-2.0, so commercial use is permitted. Its card is plain about the difference that matters: it supports only non-thinking mode. Context is 262,144 tokens natively.

That makes it the predictable choice. With no thinking tokens, latency per field is steady, which suits an extraction service with a response-time budget, and output length is easier to cap. It is older than Qwen3.5-4B, so expect the newer model to edge it on harder pages. Running both on the same evaluation set is cheap and tells you whether the gap matters for your schema.

Deployment shape: open weights, in SIE's self-hosted catalog, and runnable locally. It suits teams that value consistent latency over the last point of accuracy.

5. GLiNER2 Large

Model card: fastino/gliner2-large-v1 on Hugging Face

GLiNER2 from Fastino is an encoder model, 486M parameters in its large weights, licensed Apache-2.0, so commercial use is permitted. Its card describes entity recognition, classification, structured extraction and relation extraction in a single forward pass, and calls it CPU first.

Speed is the draw. For fields that are named things rather than computed ones, such as company name, auditor, segment label or fiscal year-end, a schema-driven encoder is fast and cheap. It does not generate text and does not reason across tables, so a subtotal that must be checked against two rows is beyond it.

Deployment shape: open weights that run on CPU; in SIE's self-hosted catalog; and priced on SIE Cloud at $0.186 per million input tokens, as listed on 2026-09-30. It suits the first pass of a pipeline, tagging entities and routing pages before a generative model handles the numbers.

6. NuNER_Zero

Model card: numind/NuNER_Zero on Hugging Face

NuNER_Zero from NuMind is a 449M zero-shot entity tagger, licensed MIT, so commercial use is permitted. You pass the labels as input, and it finds the spans.

It ranks last because its job is the smallest. It tags spans and nothing more: no schema, and no sense of what a number means. For the simplest fields, such as the company, the auditor or a date, that is enough, and a model this size is cheap to run on every document. Its card has not been updated since February 2025.

Deployment shape: open weights; in SIE's catalog for self-hosting or local use, and on SIE Cloud. It suits a light entity pass before heavier extraction.

How these compare with hosted APIs

Hosted frontier models are a separate serving path from the open weights above. OpenAI Structured Outputs guarantees responses that adhere to a supplied JSON schema, and Gemini and Claude offer schema-constrained output too. Prompt caching and batch pricing, about half the list price, cut the cost of stable prompts.

OpenAI gpt-6.1-sol costs $2 per million input tokens and $10 per million output, and gpt-6-astra $10 and $50. OpenAI also ships open-weight gpt-oss models under Apache-2.0, but the frontier GPT family is hosted only. Google Gemini reads PDFs natively, pages as images, including tables and charts, in documents up to 1,000 pages. Gemini 3.8 Flash is $0.75 and $3.75 at a promotional price through 2026-12-31, and Gemini 3.1 Pro Preview is $2 and $12. Anthropic Claude Sonnet 5.5 costs $2 and $10, with a one-million-token window at standard pricing.

The cost is structural. Documents go to the provider's service. Regional data residency and zero-retention terms exist, and Azure OpenAI, Vertex AI and Bedrock run inside your cloud tenancy, but the model does not run in your own cluster. Per-token cost also scales with volume. Open models run on SIE, on Cloud or in your own cluster, with weights you pin.

Schema adherence, from any provider, still only guarantees the shape. The eliminations row in the opening example would have passed strict JSON-schema output, because the error was a sign, not a type.

How to run these models

Superlinked SIE is an inference layer for task-specific models. It serves the document models you put into production, next to the OCR models and embedders a reporting pipeline also needs. It runs in three modes: managed on SIE Cloud, priced per use with no GPUs to run; self-hosted in your own VPC or Kubernetes cluster, the same engine under Apache 2.0; and locally for development.

On Cloud, as priced on 2026-09-30, Qwen3.8-27B (FP8) backs doc field extraction and structured output at $0.72 per million tokens in and $0.72 out, GLiNER2 Large is $0.186 per million input tokens, and NuNER_Zero is available. Qwen3.6-27B, Qwen3.5-4B and Qwen3-4B-Instruct-2507 sit in the model catalog for self-hosted and local use. The SDK's extract call takes a model ID and a list of labels, and the documentation covers generate for the Qwen models, so comparing two candidates on one evaluation set needs no second serving stack.

Honest take: SIE serves the document models you put into production, on SIE Cloud or in your own cluster, behind one API. OCR, extraction, embeddings and reranking share that client. On Cloud, Qwen3.8-27B (FP8) backs field extraction and structured output, with GLiNER2 and NuNER_Zero beside it, and Superlinked runs the GPUs. Self-host the same Apache 2.0 engine on your own GPUs, and the open weights in the catalog, including the Qwen extractors, run under the same model IDs. You point one SDK at a gold set, swap the model ID, and keep the schema, the labels and the serving path stable.

How we ranked them

No benchmark decides this order, because none of the ranked models publishes a financial-report extraction score. The order rests on four criteria: the range of fields a model can handle, from entity labels to computed figures; fit for schema-bound output, including abstention; the publisher's evidence, such as OmniDocBench v1.5 or template-extraction scores, read as attributed claims; and size and cost to run. Licence was a gate, not a score: every entry permits commercial use. Where a model runs is reported in each entry's deployment line and played no part in the order.

Frequently asked questions

How do we get segment revenue when companyfacts does not have it?

companyfacts, companyconcept and frames include only facts that use a non-custom taxonomy and apply to the entire filing entity, so segment and other dimensional facts are excluded, as are company extension tags. Read them from the filing's own inline XBRL instead: each ix:nonFraction points to a contextRef, and that context carries the axis and member, such as StatementBusinessSegmentsAxis and the segment's member. Extract by axis and member, keep the eliminations member separate with its sign, and check that segments plus eliminations equal the consolidated fact.

How do we stop thousands-versus-millions scale errors?

Make scale a field. Extract the unit and the scale statement ("in thousands", "in millions") as values next to every figure, then normalise in code, never in the prompt. In inline XBRL the scale is markup: a figure displayed as "78,678" carries scale="6" on its ix:nonFraction element, so it means 78,678 million, and decimals (for example -6) states the rounding precision, which is the right tolerance when you match. The JSON APIs return base units with no scale attribute, so compare against those.

Should we fine-tune or prompt?

Prompt first. With a typed schema, a few examples and thinking switched off, the models above often clear the bar on stable sections, and you learn where they fail. Fine-tune only when the evaluation shows a consistent error you cannot prompt away, such as a filer layout the model keeps misreading.

Where to start

Start with the schema, not the model. For fields that need judgement, test Qwen3.8-27B; for strict templates with abstention, NuExtract3; for stable high-volume sections, Qwen3.5-4B; for entity fields, GLiNER2. SIE serves the document models you put into production, on Cloud or in your cluster, behind one API. The SIE Cloud page lists the priced models and a first request you can point at your own reports.

Membangun Local API Proxy dengan Token Bucket untuk Rate Limit v2

Kiell Tampubolon — Wed, 07 Oct 2026 09:56:11 +0000

Membangun Local API Proxy dengan Token Bucket untuk Rate Limit v2

Banyak layanan API menerapkan rate limit untuk melindungi server. Ketika aplikasi melebihi batas, respons 429 Too Many Requests muncul. Solusi klasik retry dengan exponential backoff tetap membiarkan burst request ke upstream. Pendekatan lebih baik: local proxy yang menampung request, mengatur keluar ritmis, dan menyimpan cache.

Arsitektur Proxy Lokal

Penjelasan Alur

Client kirim request ke Local Proxy (bukan langsung upstream).
Proxy cek Token Bucket: token ada ? lepas ke upstream; tidak ada ? masuk Request Queue.
Retry Manager tangani 429 dengan header Retry-After + jitter.
Cache Store simpan respons GET sukses; request identik berikutnya ambil dari cache.

Implementasi Minimal (FastAPI + httpx)

# proxy.py
import asyncio
import time
import hashlib
from collections import deque
from fastapi import FastAPI, Request, Response
import httpx

app = FastAPI()
UPSTREAM = "https://api.example.com"
RATE = 10
BURST = 20
CACHE_TTL = 300

class TokenBucket:
    def __init__(self, rate: float, burst: int):
        self.rate = rate
        self.burst = burst
        self.tokens = float(burst)
        self.last = time.monotonic()
        self.lock = asyncio.Lock()

    async def take(self) -> bool:
        async with self.lock:
            now = time.monotonic()
            self.tokens = min(self.burst, self.tokens + (now - self.last) * self.rate)
            self.last = now
            if self.tokens >= 1:
                self.tokens -= 1
                return True
            return False

bucket = TokenBucket(RATE, BURST)
cache: dict[str, tuple[bytes, float]] = {}

async def forward(req: Request) -> Response:
    key = f"{req.method}:{req.url.path}:{req.query_params}"
    if req.method == "GET" and key in cache:
        cached, ts = cache[key]
        if time.time() - ts < CACHE_TTL:
            return Response(content=cached, media_type="application/json")

    async with httpx.AsyncClient(base_url=UPSTREAM, timeout=10) as client:
        while True:
            if await bucket.take():
                break
            await asyncio.sleep(0.1)

        upstream_req = client.build_request(
            req.method, req.url.path,
            params=req.query_params,
            headers=dict(req.headers),
            content=await req.body()
        )
        resp = await client.send(upstream_req)

        if resp.status_code == 429:
            retry = int(resp.headers.get("Retry-After", "1"))
            await asyncio.sleep(retry + 0.1 * (hash(key) % 10))
            continue

        if req.method == "GET" and resp.status_code == 200:
            cache[key] = (resp.content, time.time())

        return Response(
            content=resp.content,
            status_code=resp.status_code,
            media_type=resp.headers.get("content-type")
        )

@app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE"])
async def proxy(path: str, request: Request):
    return await forward(request)

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

Menjalankan Proxy

pip install fastapi httpx uvicorn
uvicorn proxy:app --port 8000

Arahkan client ke http://localhost:8000/... sebagai pengganti upstream.

Checklist Produksi

[ ] Tambahkan metrics (Prometheus) untuk bucket & queue
[ ] Implementasikan circuit breaker jika upstream gagal
[ ] Gunakan Redis untuk cache & bucket terdistribusi
[ ] Tambahkan authentication (API key) pada proxy
[ ] Tulis unit & integration test untuk retry logic

Kesimpulan

Dengan local proxy token-bucket, aplikasi tidak khawatir 429. Proxy menyerap burst, atur throughput, kurangi beban upstream lewat caching. Cocok untuk microservices, scraper, integrasi pihak ketiga.

Test Article

Kiell Tampubolon — Wed, 07 Oct 2026 09:48:59 +0000

Test

Test content

Membangun Local API Proxy dengan Token Bucket untuk Menangani Rate Limit

Kiell Tampubolon — Wed, 07 Oct 2026 09:34:23 +0000

Membangun Local API Proxy dengan Token Bucket untuk Menangani Rate Limit

Banyak layanan API menerapkan rate limit untuk melindungi server dari beban berlebih. Ketika aplikasi melebihi batas, respons 429 Too Many Requests muncul dan proses terhenti.

Solusi klasik adalah retry dengan exponential backoff, namun pendekatan itu tetap membiarkan burst request sampai ke upstream. Pendekatan yang lebih baik: local proxy yang menampung request, mengatur keluar secara ritmis, dan menyimpan cache respons.

Artikel ini menunjukkan arsitektur dan implementasi minimal menggunakan Python (FastAPI + httpx).

Arsitektur Proxy Lokal

<svg width="500" height="250" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 500 250">
  <!-- Client -->
  <rect x="20" y="80" width="100" height="50" rx="5" fill="#2563eb"/>
  <text x="70" y="110" text-anchor="middle" fill="white" font-size="14" font-family="system-ui, sans-serif">Client</text>
  <!-- Arrow 1 -->
  <path d="M120 105 L180 105" stroke="#475569" stroke-width="2" marker-end="url(#arrow)"/>
  <!-- Local Proxy -->
  <rect x="180" y="40" width="140" height="170" rx="8" fill="#fef3c7" stroke="#f59e0b" stroke-width="2"/>
  <text x="250" y="65" text-anchor="middle" fill="#92400e" font-size="14" font-weight="600" font-family="system-ui, sans-serif">Local Proxy</text>
  <text x="250" y="85" text-anchor="middle" fill="#92400e" font-size="11" font-family="system-ui, sans-serif">Token Bucket</text>
  <text x="250" y="105" text-anchor="middle" fill="#92400e" font-size="11" font-family="system-ui, sans-serif">Request Queue</text>
  <text x="250" y="125" text-anchor="middle" fill="#92400e" font-size="11" font-family="system-ui, sans-serif">Retry Manager</text>
  <text x="250" y="145" text-anchor="middle" fill="#92400e" font-size="11" font-family="system-ui, sans-serif">Cache Store</text>
  <!-- Arrow 2 -->
  <path d="M320 105 L380 105" stroke="#475569" stroke-width="2" marker-end="url(#arrow)"/>
  <!-- Upstream API -->
  <rect x="380" y="80" width="100" height="50" rx="5" fill="#16a34a"/>
  <text x="430" y="110" text-anchor="middle" fill="white" font-size="14" font-family="system-ui, sans-serif">Upstream API</text>
  <!-- Arrow definition -->
  <defs>
    <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto" markerUnits="strokeWidth">
      <path d="M0,0 L0,6 L9,3 z" fill="#475569"/>
    </marker>
  </defs>
</svg>

Penjelasan Alur

Client mengirim request ke Local Proxy (bukan langsung ke upstream).
Proxy memeriksa Token Bucket: apakah token tersedia? Jika ya, request dilepaskan ke upstream; jika tidak, request masuk Request Queue.
Retry Manager menangani respons 429 dari upstream dengan membaca header Retry-After dan menambahkan jitter.
Cache Store menyimpan respons GET yang berhasil; request identik berikutnya disajikan dari cache tanpa menghitung ke bucket.

Implementasi Minimal (FastAPI + httpx)

# proxy.py
import asyncio
import time
import hashlib
from collections import deque
from fastapi import FastAPI, Request, Response
import httpx

app = FastAPI()
UPSTREAM = "https://api.example.com"
RATE = 10          # request per second
BURST = 20         # bucket capacity
CACHE_TTL = 300    # seconds


class TokenBucket:
    def __init__(self, rate: float, burst: int):
        self.rate = rate
        self.burst = burst
        self.tokens = float(burst)
        self.last = time.monotonic()
        self.lock = asyncio.Lock()

    async def take(self) -> bool:
        async with self.lock:
            now = time.monotonic()
            self.tokens = min(self.burst, self.tokens + (now - self.last) * self.rate)
            self.last = now
            if self.tokens >= 1:
                self.tokens -= 1
                return True
            return False


bucket = TokenBucket(RATE, BURST)
cache: dict[str, tuple[bytes, float]] = {}


async def forward(req: Request) -> Response:
    key = f"{req.method}:{req.url.path}:{req.query_params}"

    # Cache hit untuk GET
    if req.method == "GET" and key in cache:
        cached, ts = cache[key]
        if time.time() - ts < CACHE_TTL:
            return Response(content=cached, media_type="application/json")

    async with httpx.AsyncClient(base_url=UPSTREAM, timeout=10) as client:
        while True:
            if await bucket.take():
                break
            await asyncio.sleep(0.1)

        upstream_req = client.build_request(
            req.method,
            req.url.path,
            params=req.query_params,
            headers=dict(req.headers),
            content=await req.body()
        )
        resp = await client.send(upstream_req)

        if resp.status_code == 429:
            retry = int(resp.headers.get("Retry-After", "1"))
            await asyncio.sleep(retry + 0.1 * (hash(key) % 10))
            continue

        if req.method == "GET" and resp.status_code == 200:
            cache[key] = (resp.content, time.time())

        return Response(
            content=resp.content,
            status_code=resp.status_code,
            media_type=resp.headers.get("content-type")
        )


@app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE"])
async def proxy(path: str, request: Request):
    return await forward(request)


if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

Menjalankan Proxy

pip install fastapi httpx uvicorn
uvicorn proxy:app --port 8000

Sekarang arahkan client ke http://localhost:8000/... sebagai pengganti upstream asli.

Checklist Produksi

[ ] Tambahkan metrics (Prometheus) untuk mengamati bucket & queue
[ ] Implementasikan circuit breaker jika upstream terus gagal
[ ] Gunakan Redis untuk cache & bucket terdistribusi
[ ] Tambahkan authentication (API key) pada proxy
[ ] Tulis unit & integration test untuk retry logic

Kesimpulan

Dengan local proxy token-bucket, aplikasi tidak lagi perlu khawatir soal 429. Proxy menyerap burst, mengatur throughput, dan mengurangi beban upstream lewat caching. Pola ini cocok untuk microservices, scraper, dan integrasi pihak ketiga.

Artikel ini dipublikasikan otomatis melalui pipeline Writer → Designer → Reviewer → Publisher.

Panduan API Rate‑Limit: Membangun Local Proxy dengan Token Bucket

Kiell Tampubolon — Wed, 07 Oct 2026 09:27:27 +0000

Panduan API Rate‑Limit: Membangun Local Proxy dengan Token Bucket

Banyak layanan API menerapkan rate limit untuk melindungi server dari overload. Ketika aplikasi Anda melebihi batas, respons 429 Too Many Requests muncul dan proses terhenti. Solusi klasik adalah retry dengan exponential backoff, tetapi pendekatan itu masih membiarkan burst request sampai ke upstream.

Pendekatan yang lebih baik: local proxy yang menampung request, mengatur keluar secara ritmis, dan menyimpan cache respons. Artikel ini menunjukkan arsitektur dan implementasi minimal menggunakan Python (FastAPI + httpx).

Arsitektur Proxy Lokal

<svg width="500" height="250" xmlns="http://www.w3.org/2000/svg">
  <rect x="20" y="80" width="100" height="50" rx="5" fill="#4a90d9"/>
  <text x="70" y="110" text-anchor="middle" fill="white" font-size="14">Client</text>
  <path d="M120 105 L180 105" stroke="#666" stroke-width="2" marker-end="url(#arrow)"/>
  <rect x="180" y="50" width="140" height="110" rx="5" fill="#f5a623"/>
  <text x="250" y="75" text-anchor="middle" fill="white" font-size="14">Local Proxy</text>
  <text x="250" y="95" text-anchor="middle" fill="white" font-size="11">Token Bucket</text>
  <text x="250" y="115" text-anchor="middle" fill="white" font-size="11">Request Queue</text>
  <text x="250" y="135" text-anchor="middle" fill="white" font-size="11">Retry Manager</text>
  <text x="250" y="155" text-anchor="middle" fill="white" font-size="11">Cache Store</text>
  <path d="M320 105 L380 105" stroke="#666" stroke-width="2" marker-end="url(#arrow)"/>
  <rect x="380" y="80" width="100" height="50" rx="5" fill="#7ed321"/>
  <text x="430" y="110" text-anchor="middle" fill="white" font-size="14">Upstream API</text>
  <defs>
    <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto" markerUnits="strokeWidth">
      <path d="M0,0 L0,6 L9,3 z" fill="#666"/>
    </marker>
  </defs>
</svg>

Penjelasan alur:

Client mengirim request ke Local Proxy (bukan langsung ke upstream).
Proxy memeriksa Token Bucket: apakah token tersedia? Jika ya, request dilepaskan ke upstream; jika tidak, request masuk Request Queue.
Retry Manager menangani respons 429 dari upstream dengan membaca header Retry-After dan menambahkan jitter.
Cache Store menyimpan respons GET yang berhasil; request identik berikutnya disajikan dari cache tanpa menghitung ke bucket.

Implementasi Minimal (FastAPI + httpx)

# proxy.py
import asyncio, time, hashlib, json
from collections import deque
from fastapi import FastAPI, Request, Response, HTTPException
import httpx

app = FastAPI()
UPSTREAM = "https://api.example.com"
RATE = 10          # request per second
BURST = 20         # bucket capacity
CACHE_TTL = 300    # seconds

class TokenBucket:
    def __init__(self, rate, burst):
        self.rate = rate
        self.burst = burst
        self.tokens = burst
        self.last = time.monotonic()
        self.lock = asyncio.Lock()
    async def take(self):
        async with self.lock:
            now = time.monotonic()
            self.tokens = min(self.burst, self.tokens + (now - self.last) * self.rate)
            self.last = now
            if self.tokens >= 1:
                self.tokens -= 1
                return True
            return False

bucket = TokenBucket(RATE, BURST)
queue = deque()
cache = {}

async def forward(req: Request):
    key = f"{req.method}:{req.url.path}:{req.query_params}"
    if req.method == "GET" and key in cache:
        cached, ts = cache[key]
        if time.time() - ts < CACHE_TTL:
            return Response(content=cached, media_type="application/json")
    async with httpx.AsyncClient(base_url=UPSTREAM, timeout=10) as client:
        while True:
            if await bucket.take():
                break
            await asyncio.sleep(0.1)
        upstream_req = client.build_request(req.method, req.url.path, params=req.query_params, headers=dict(req.headers), content=await req.body())
        resp = await client.send(upstream_req)
        if resp.status_code == 429:
            retry = int(resp.headers.get("Retry-After", "1"))
            await asyncio.sleep(retry + 0.1 * (hash(key) % 10))
            continue
        if req.method == "GET" and resp.status_code == 200:
            cache[key] = (resp.content, time.time())
        return Response(content=resp.content, status_code=resp.status_code, media_type=resp.headers.get("content-type"))

@app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE"])
async def proxy(path: str, request: Request):
    return await forward(request)

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

Menjalankan Proxy

pip install fastapi httpx uvicorn
uvicorn proxy:app --port 8000

Sekarang arahkan client ke http://localhost:8000/... sebagai pengganti upstream asli.

Checklist Produksi

[ ] Tambahkan metrics (Prometheus) untuk mengamati bucket & queue.
[ ] Implementasikan circuit breaker jika upstream terus gagal.
[ ] Gunakan Redis untuk cache & bucket terdistribusi.
[ ] Tambahkan authentication (API key) pada proxy.
[ ] Tulis unit & integration test untuk retry logic.

Kesimpulan

Dengan local proxy token‑bucket, aplikasi Anda tidak lagi perlu khawatir soal 429. Proxy menyerap burst, mengatur throughput, dan mengurangi beban upstream lewat caching. Pola ini cocok untuk microservices, scraper, dan integrasi pihak ketiga.

Artikel ini dipublikasikan otomatis melalui pipeline Writer → Designer → Reviewer → Publisher.

Wiring a Third-Party Decision Model Into Claude Code, and What I Wouldn't Let It Do by Default

Kiell Tampubolon — Mon, 05 Oct 2026 07:03:31 +0000

TL;DR

Downloaded a vendor's "paste this into your agent" setup guide for Jev, a fast/cheap decision model. Had Claude Code build the integration live instead of just reading about it.

Secured the real API key into gitignored storage before a single test call.

Caught the docs-fetching tool hallucinating the API endpoint (doubled path, 404), fixed it with a stricter re-fetch.

Built a reusable client, two on-demand skills, and a message-size router hook, pipe-tested through every branch, shipped off by default.

Closed the loop by having Jev itself pick this article's title. 0.99 confidence, under a second, a fraction of a cent.

I downloaded a setup guide for something called Jev: a model that promises "10x the power at 100x less cost" when you pair it with Claude. I didn't read it first. I opened Claude Code, told it to read the PDF, and asked for a plan I could run in that same session. What came back wasn't a plan to review later. It was a working integration, a real paid API call, a caught hallucination, and a question about how much of a vendor's own instructions I should let an agent follow without looking.

What Jev actually is

Jev (typesafe/jev-1.13, from TypeSafe AI) isn't a language model in the usual sense. It doesn't write anything. You send it a piece of text plus one or more typed questions, and it answers in one of three shapes: choice (pick one option), score (place it on a scale), or noul (the probability a yes/no statement is true), each with a confidence number attached.

A fictional sales email, three questions, one real call through OpenRouter (a service that proxies API access to many AI models behind one key): sales, a 2.97-3 lead score at 0.97-1.0 confidence, 0.75-0.78 probability it needed a same-day reply. Under a second. About two cents per thousand calls.

The guide's own benchmark backs this up at scale, run against 100 made-up emails for a fictional agency, recorded 21 September 2026:

Model	Time	Cost	Lead score exactly right	Hot leads found
Jev	3.6s	$0.0032	89/100	15/15
Claude Haiku 4.5 (thinking off)	11.1s	$0.061	84/100	15/15
Claude Fable 5.1 (effort low)	38.7s	$0.76	97/100	15/15

Fable was the most accurate. Jev beat Haiku on both speed and accuracy, at a fraction of the cost of either. None of them missed a hot lead. That's the actual pitch: Jev for volume, Claude for anything that needs writing or real reasoning.

Reading the prompt before running it

The guide's core step is a block literally labeled "copy-paste, the main prompt." Paste it into your agent and it asks for your OpenRouter API key, makes a live test call, and saves the setup as a reusable skill. The PDF contains text written to become my instructions the moment I follow the guide's own suggestion to paste it in.

I didn't paste it in. I read the guide, pulled out what I actually needed, and wrote my own version instead of executing the vendor's copy verbatim. To be fair to it: the guide wasn't reckless. It tells the agent to ask before sending anything private, and its message-router feature defaults to off specifically because turning it on means every message passes through OpenRouter to TypeSafe. The point isn't that this guide was careless. It's that I didn't know that until I'd actually read it, and anything built to be pasted straight into an agent is worth that read every time, regardless of how it turns out.

Three things that happened in order

Secured the key first. The real key arrived in plain text in chat. Before any test call, it went into a gitignored .env file, with a backup encrypted into the personal notes repo's existing SECRETS/ convention (age ciphertext only, private key never committed). Only then did I make a live call. Secure it, then use it, not the other way around.
Caught a hallucinated endpoint. Jev launched after my training cutoff, so I fetched live docs instead of relying on memory. The first fetch described the API endpoint as https://openrouter.ai/api/v1/api/alpha/decisions, base URL and path merged wrong. I called it. 404. A stricter re-fetch, asking for the path quoted verbatim instead of summarized, gave the real one: POST https://openrouter.ai/api/alpha/decisions.
Built and pipe-tested before trusting it. A Node client, two on-demand skills, and a message-size router wired as a real UserPromptSubmit hook, not just described in a doc.

The fix for a hallucinated endpoint isn't "don't trust docs-fetching tools." It's that a summarizer asked to describe an API reference page can merge a base URL with a path wrong, and the only way to catch it is to make the call and read the actual status code.

What got built

A Node client (askJev({state, questions})) that calls the verified endpoint and returns the answer with its confidence.
Two on-demand skills: one for calling Jev directly, one with ready-made recipes for sorting a pile of text (inbox leads, support-ticket urgency and churn risk, supplier-invoice fraud signals). Both carry the guide's own rule: under roughly 60% confidence, the item goes to a pile for a human to judge, never straight to action.
A message-size router, a real hook that fires on every message submitted to Claude Code, not something I only wrote about. Pipe-tested directly before trusting it: off, it produces no output at all. A slash command or short reply gets skipped before any call runs. A genuinely ambiguous message (0.38 confidence) gets classified internally but the note stays suppressed, a shaky verdict is worse than no verdict. A real self-contained task got sized correctly at 0.96 confidence, cost logged to a running total. It ships off by default, because the workspace it lives in holds personal and security-incident material I don't want leaving the machine by default.

The honest limit

Claude Code doesn't have a real per-message model switch, and a hook can't create one. What the router actually does is add a note: this looks like a SONNET-sized job, or an OPUS-sized one. Acting on that note is still a judgment call, made by Claude or by me, not an automatic handoff. Calling it a "router" oversells it slightly, and I'd rather say that plainly than let the name imply more control than the mechanism has.

A small, honest test of the whole thing

Three titles for this article, and I didn't want to pick. So I had Jev decide, the same way it would decide between three email categories: one choice question, three options, one call.

Picked at 0.99 confidence, for $0.000025, in under a second. The whole pitch in miniature: a cheap, fast, structured judgment call, made by something that only ever answers in multiple choice, never in prose.

If you're wiring any brand-new third-party model into an agentic coding tool: read the vendor material yourself before letting an agent execute it verbatim, secure any credential the moment it exists, verify a live API against a real request and its actual status code rather than a summarized doc, and keep anything that touches every message you type off by default until you've decided you actually want it on.