<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Computatrum Veneficus - Medium]]></title>
        <description><![CDATA[Technomancy shenanigans and musings. - Medium]]></description>
        <link>https://medium.com/computatrum-veneficus?source=rss----99d03936446b---4</link>
        <image>
            <url>https://cdn-images-1.medium.com/proxy/1*TGH72Nnw24QL3iV9IOm4VA.png</url>
            <title>Computatrum Veneficus - Medium</title>
            <link>https://medium.com/computatrum-veneficus?source=rss----99d03936446b---4</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Wed, 18 Nov 2026 01:37:27 GMT</lastBuildDate>
        <atom:link href="https://medium.com/feed/computatrum-veneficus" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Building AI Infrastructure for a Post-Framework World]]></title>
            <link>https://medium.com/computatrum-veneficus/building-ai-infrastructure-for-a-post-framework-world-574535aacd58?source=rss----99d03936446b---4</link>
            <guid isPermaLink="false">https://medium.com/p/574535aacd58</guid>
            <category><![CDATA[zig]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[agents]]></category>
            <category><![CDATA[rust]]></category>
            <category><![CDATA[llm]]></category>
            <dc:creator><![CDATA[Baalateja Kataru]]></dc:creator>
            <pubDate>Tue, 13 Jan 2026 18:29:13 GMT</pubDate>
            <atom:updated>2026-01-13T19:21:39.803Z</atom:updated>
            <content:encoded><![CDATA[<h4>2025 was the year I stopped treating AI infrastructure like a prototype problem</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/768/0*Ou6Yx5PnyVpsVzf8.png" /></figure><p>2025 was the year I stopped treating AI infrastructure like a prototype problem. The field matured fast — we went from barely having tools to drowning in incompatible ones. Turns out trading “not enough options” for “too many fragmented options” isn’t actually an upgrade.</p><h3>The Fragmentation Problem</h3><p>Every major AI framework built its own protocol stack. Anthropic’s MCP, OpenAI’s function calling, LangChain’s abstractions — each one solves similar problems while creating vendor lock-in, protocol silos, and guaranteed rewrites down the line.</p><p>What I learned building these projects: we need infrastructure that outlives any single framework. Better primitives, not more abstractions.</p><h3>Technical Achievements: A Year in Review</h3><h3>1. PocketFlow-Zig: Flow-Based Agent Framework</h3><p><strong>Repository:</strong> <a href="https://github.com/The-Pocket/PocketFlow-Zig">PocketFlow-Zig</a></p><p>Started as a side project, ended up becoming the official Zig implementation of PocketFlow — a minimalist framework for building LLM-powered workflows. The design goal was explicit: build just enough framework to let agents construct other agents.</p><p><strong>What I Built:</strong></p><ul><li>Zero dependencies, pure Zig</li><li>Flow-based programming (think Unix pipes for LLM workflows)</li><li>Comptime-generated agent templates (zero runtime cost)</li><li>Cross-compilation for embedded targets</li></ul><p>PocketFlow now runs across multiple platforms as a base layer for agentic workflows.</p><h3>2. TOON-Zig: Efficient Token Serialization</h3><p><strong>Repository:</strong> <a href="https://github.com/bkataru/toon-zig">toon-zig</a></p><p>TOON (Token Oriented Object Notation) is a data serialization format optimized for LLM consumption. Built the Zig implementation from scratch:</p><p><strong>What Got Built:</strong></p><ul><li>340 official TOON 2.0 spec tests (100% passing)</li><li>196 decoding fixtures + 144 encoding fixtures</li><li>15–30% better token efficiency than JSON for typical LLM payloads</li><li>Zero dependencies, pure Zig</li></ul><p>Getting spec compliance while keeping performance high took some careful engineering.</p><h3>3. HF-Hub-Zig: HuggingFace Integration Layer</h3><p><strong>Repository:</strong> <a href="https://github.com/bkataru/hf-hub-zig">hf-hub-zig</a></p><p>Zig needed native HuggingFace Hub API support, especially for GGUF model management. So I built it.</p><p><strong>What It Does:</strong></p><ul><li>GGUF model discovery and search</li><li>Efficient model downloading with resume capability</li><li>Local model registry management</li><li>Cross-platform CLI interface</li></ul><p><strong>How It Works:</strong></p><ul><li>Zero dependencies, pure Zig</li><li>Efficient streaming downloads with progress tracking</li><li>Robust error handling for network failures</li><li>Memory-mapped file access for large models</li></ul><h3>4. Zenmap: Cross-Platform Memory Mapping</h3><p><strong>Repository:</strong> <a href="https://github.com/bkataru/zenmap">zenmap</a></p><p>A single-file Zig library for memory mapping large files, built specifically for GGUF model handling.</p><p><strong>The Challenge:</strong></p><ul><li>Unified POSIX (Linux, macOS, BSD) and Windows memory mapping APIs</li><li>Zero-copy file access for 70B+ parameter models</li><li>Efficient handling of sparse files and partial loads</li><li>Cross-platform abstraction with minimal overhead</li></ul><h3>5. Igllama: Zig-Based Ollama Alternative</h3><p><strong>Repository:</strong> <a href="https://github.com/bkataru/igllama">igllama</a></p><p>A Zig-based alternative to Ollama that uses the Zig build system’s embedded Clang toolchain to compile and run llama.cpp.</p><p><strong>What Makes It Different:</strong></p><ul><li>Zig build system integration with llama.cpp’s CMake build</li><li>Docker-like CLI experience for GGUF management</li><li>Transparent llama.cpp updates (no lagging behind upstream)</li><li>Cross-platform binary distribution</li></ul><h3>Production Work at Dirmacs</h3><p>I’ve been working with <a href="https://www.linkedin.com/in/suprabhat-rapolu/">Suprabhat Rapolu</a> and the team at <a href="https://www.linkedin.com/company/dirmacs-global-services/">Dirmacs Global Services</a> to ship production AI infrastructure in Rust:</p><h3>A.R.E.S: Production Agent Framework</h3><p><strong>Repository:</strong> <a href="https://github.com/dirmacs/ares">ares</a></p><p>A production agentic chatbot library built in Rust with:</p><ul><li>Multi-provider LLM support</li><li>Tool calling and ReAct loops</li><li>RAG knowledge bases</li><li>MCP protocol integration</li><li>Leptos-based embedded web UI</li></ul><p><strong>Current Status:</strong> Actively dogfooding this in pilot projects. Design goals keep evolving.</p><h3>Daedra: Web Research MCP Server</h3><p><strong>Repository:</strong> <a href="https://github.com/dirmacs/daedra">daedra</a></p><p>High-performance DuckDuckGo-powered web search MCP server written in Rust. Gives AI assistants web search and page fetching as tools.</p><p><strong>Features:</strong></p><ul><li>No API keys needed (uses DuckDuckGo’s public API)</li><li>Rust rewrite of an old TypeScript version</li><li>Ships production-ready: cargo install daedra</li></ul><h3>Lancor: LLaMA.cpp Client Library</h3><p><strong>Repository:</strong> <a href="https://github.com/dirmacs/lancor">lancor</a></p><p>A Rust client library for llama.cpp’s OpenAI-compatible API server.</p><p><strong>Goal:</strong> Simple, straightforward integration with existing Rust AI workflows.</p><h3>What Ties This Together</h3><p>All these projects share a common thread: explicit control over system boundaries. In a world where frameworks come and go, infrastructure needs to:</p><ol><li><strong>Outlive any single vendor</strong> — Protocol-level interop</li><li><strong>Show explicit costs</strong> — No magic, no hidden abstractions</li><li><strong>Stay fast</strong> — Zero-cost abstractions where possible</li><li><strong>Run everywhere</strong> — Build once, deploy anywhere</li></ol><h3>What’s Next for 2026</h3><p>Foundation’s built. Now comes production hardening:</p><ul><li><strong>Protocol work:</strong> Add gRPC and custom transports to zig-utcp</li><li><strong>Production features:</strong> Streaming, error handling, resource management</li><li><strong>Distributed systems:</strong> Get agents coordinating across networks</li><li><strong>Real-world testing:</strong> Pilot deployments, feedback loops</li></ul><p>The goal stays the same: build infrastructure that lets developers construct robust AI systems without getting locked into any framework.</p><p><em>All projects are MIT licensed and open source. Pull requests and technical discussions welcome.</em></p><p>links :)</p><ul><li><a href="https://github.com/bkataru/mcp.zig">mcp.zig</a></li><li><a href="https://github.com/bkataru/zig-utcp">zig-utcp</a></li><li><a href="https://github.com/The-Pocket/PocketFlow-Zig">PocketFlow-Zig</a></li><li><a href="https://github.com/bkataru/grayscales">grayscales</a></li><li><a href="https://github.com/bkataru/toon-zig">TOON-Zig</a></li><li><a href="https://github.com/bkataru/hf-hub-zig">HF-Hub-Zig</a></li><li><a href="https://github.com/bkataru/zenmap">zenmap</a></li><li><a href="https://github.com/bkataru/igllama">igllama</a></li><li><a href="https://github.com/dirmacs/ares">A.R.E.S</a></li><li><a href="https://github.com/dirmacs/daedra">daedra</a></li><li><a href="https://github.com/dirmacs/lancor">lancor</a></li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/768/0*yzTkjkbcYugHNQjM.png" /></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=574535aacd58" width="1" height="1" alt=""><hr><p><a href="https://medium.com/computatrum-veneficus/building-ai-infrastructure-for-a-post-framework-world-574535aacd58">Building AI Infrastructure for a Post-Framework World</a> was originally published in <a href="https://medium.com/computatrum-veneficus">Computatrum Veneficus</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building a Gzip Compression Library in Zig 0.15: A Deep Dive into Comprezz]]></title>
            <link>https://medium.com/computatrum-veneficus/building-a-gzip-compression-library-in-zig-0-15-a-deep-dive-into-comprezz-66c1ee2b56e8?source=rss----99d03936446b---4</link>
            <guid isPermaLink="false">https://medium.com/p/66c1ee2b56e8</guid>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[zig]]></category>
            <category><![CDATA[gzip]]></category>
            <category><![CDATA[compression]]></category>
            <category><![CDATA[learning]]></category>
            <dc:creator><![CDATA[Baalateja Kataru]]></dc:creator>
            <pubDate>Wed, 29 Oct 2025 11:37:50 GMT</pubDate>
            <atom:updated>2025-10-29T11:55:03.407Z</atom:updated>
            <content:encoded><![CDATA[<h4>Because I read “Compression functionality was removed. Sorry, you will have to copy the old code into your application” in the release notes.</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/768/0*IvKOrjh8BNdp5eKR.png" /></figure><h3>Introduction</h3><p>When Zig 0.15 removed compression support from its standard library, it created an opportunity: build a standalone, production-ready compression library while navigating the language’s new I/O paradigm shift known as “Writergate.” This post chronicles the development of <a href="https://github.com/bkataru/comprezz">Comprezz</a>, a single-file gzip/deflate compression library that combines classical computer science algorithms with modern systems programming.</p><p><strong>What you’ll learn:</strong></p><ul><li>How the DEFLATE compression algorithm works under the hood</li><li>Building bit-level I/O abstractions in systems programming</li><li>Navigating Zig 0.15’s new non-generic I/O interfaces</li><li>Implementing Huffman coding and LZ77 compression from scratch</li></ul><h3>Project Overview</h3><p>Comprezz is a ~1700-line pure Zig implementation providing:</p><ul><li><strong>Full LZ77 + Huffman encoding</strong> — Complete DEFLATE (RFC 1951) implementation</li><li><strong>Multiple compression levels</strong> — From fast (4) to best (9)</li><li><strong>Gzip/Zlib/Raw containers</strong> — Proper headers, trailers, and checksums</li><li><strong>Library + CLI</strong> — Use programmatically or as a command-line tool</li><li><strong>Zero dependencies</strong> — Self-contained, no external C libraries</li></ul><p>The entire implementation lives in src/lib.zig, making it easy to vendor or study.</p><h3>Understanding the DEFLATE Algorithm</h3><p>Before diving into code, let’s understand what we’re building. DEFLATE combines two compression techniques:</p><h3>1. LZ77: Dictionary Compression</h3><p>LZ77 replaces repeated byte sequences with back-references:</p><pre>Input:  &quot;The quick brown fox jumps over the lazy dog. The quick brown fox...&quot;<br>Output: &quot;The quick brown fox jumps over the lazy dog. [back 45, length 23]...&quot;</pre><p>This works by maintaining a <strong>sliding window</strong> (32KB) of recent data and searching for matches. When we find a repeated sequence, we emit a <strong>match token</strong> (distance, length) instead of the literal bytes.</p><h3>2. Huffman Coding: Optimal Bit Encoding</h3><p>Frequently occurring symbols get shorter bit codes:</p><pre>&#39;e&#39; (frequent): 101      (3 bits)<br>&#39;q&#39; (rare):     11010111 (8 bits)</pre><p>DEFLATE builds <strong>dynamic Huffman trees</strong> for each block, adapting to the data’s characteristics.</p><h3>Combined Pipeline</h3><pre>Raw Data → LZ77 Tokenizer → Huffman Encoder → Bit Writer → Compressed Stream</pre><h3>Architecture Deep Dive</h3><p>Let’s walk through Comprezz’s implementation layer by layer.</p><h3>Layer 1: Bit-Level Writing</h3><p>Compression requires writing individual bits, not just bytes. Our BitWriter buffers bits and flushes efficiently:</p><pre>pub const BitWriter = struct {<br>    inner_writer: *std.Io.Writer,<br>    bits: u64 = 0,           // Bit accumulator<br>    nbits: u32 = 0,          // Number of bits in accumulator<br>    bytes: [256]u8 = undefined,  // Byte buffer for batching writes<br>    nbytes: u32 = 0,         // Buffer position<br><br>    pub fn writeBits(self: *Self, b: u32, nb: u32) Error!void {<br>        // Accumulate bits in little-endian order<br>        self.bits |= @as(u64, @intCast(b)) &lt;&lt; @as(u6, @intCast(self.nbits));<br>        self.nbits += nb;<br><br>        if (self.nbits &lt; 48) return;  // Haven&#39;t filled 6 bytes yet<br><br>        // Flush 6 bytes (48 bits) to buffer<br>        var n = self.nbytes;<br>        std.mem.writeInt(u64, self.bytes[n..][0..8], self.bits, .little);<br>        n += 6;<br><br>        if (n &gt;= 240) {  // Buffer full, write to underlying stream<br>            _ = try self.inner_writer.write(self.bytes[0..n]);<br>            n = 0;<br>        }<br><br>        self.nbytes = n;<br>        self.bits &gt;&gt;= 48;     // Remove written bits<br>        self.nbits -= 48;<br>    }<br>};</pre><p><strong>Key insights:</strong></p><ul><li>Uses 64-bit accumulator to buffer bits across byte boundaries</li><li>Batches writes to 256-byte buffer before syscalls</li><li>Writes 6 bytes at a time when accumulator fills (optimization)</li></ul><h3>Layer 2: Sliding Window for LZ77</h3><p>The heart of LZ77 is efficiently searching for repeated sequences. We use a <strong>hash-chained lookup table</strong>:</p><pre>pub const Lookup = struct {<br>    head: [32768]u16 = [_]u16{0} ** 32768,  // Hash table (15-bit hash)<br>    chain: [65536]u16 = [_]u16{0} ** 65536, // Chain of previous positions<br><br>    pub fn add(self: *Lookup, data: []const u8, pos: u16) u16 {<br>        if (data.len &lt; 4) return 0;<br>        const h = hash(data[0..4]);  // Hash first 4 bytes<br>        return self.set(h, pos);<br>    }<br><br>    fn set(self: *Lookup, h: u32, pos: u16) u16 {<br>        const prev = self.head[h];   // Get previous position at this hash<br>        self.head[h] = pos;          // Update hash table<br>        self.chain[pos] = prev;      // Link to previous position<br>        return prev;<br>    }<br><br>    fn hash(b: *const [4]u8) u32 {<br>        const prime = 0x9E3779B1;<br>        const v = @as(u32, b[3]) | <br>                  @as(u32, b[2]) &lt;&lt; 8 | <br>                  @as(u32, b[1]) &lt;&lt; 16 | <br>                  @as(u32, b[0]) &lt;&lt; 24;<br>        return @intCast((v *% prime) &gt;&gt; 17);  // 15-bit hash<br>    }<br>};</pre><p><strong>How hash chains work:</strong></p><pre>Input: &quot;abc...abc...abc&quot;<br>       pos=0  pos=100 pos=200<br><br>head[hash(&quot;abc&quot;)] = 200<br>chain[200] = 100<br>chain[100] = 0</pre><p>When we encounter “abc” at position 200, we can walk the chain backwards to find all previous occurrences without scanning the entire window.</p><h3>Layer 3: Match Finding</h3><p>Finding the longest match involves walking the hash chain and comparing byte sequences:</p><pre>fn findMatch(self: *Self, pos: u16, lh: []const u8, min_len: u16) ?Token {<br>    var len: u16 = min_len;<br>    var prev_pos = self.lookup.add(lh, pos);  // Get chain head<br>    var match: ?Token = null;<br><br>    var chain: usize = self.level.chain;  // Max positions to check<br><br>    if (len &gt;= self.level.good) {<br>        chain &gt;&gt;= 2;  // Already have good match, search less<br>    }<br><br>    while (prev_pos &gt; 0 and chain &gt; 0) : (chain -= 1) {<br>        const distance = pos - prev_pos;<br>        if (distance &gt; 32768) break;  // Out of window range<br><br>        const new_len = self.win.match(prev_pos, pos, len);<br>        if (new_len &gt; len) {<br>            match = Token.initMatch(@intCast(distance), new_len);<br>            if (new_len &gt;= self.level.nice) {<br>                return match;  // Good enough, stop searching<br>            }<br>            len = new_len;<br>        }<br>        prev_pos = self.lookup.prev(prev_pos);  // Follow chain<br>    }<br><br>    return match;<br>}</pre><p><strong>Compression level tuning:</strong></p><pre>const LevelArgs = struct {<br>    good: u16,  // Length to reduce search at<br>    nice: u16,  // Length to stop search at<br>    lazy: u16,  // Min length for immediate match<br>    chain: u16, // Max chain positions to check<br>};<br><br>// Level 9 (best): Check up to 4096 positions for perfect match<br>.best =&gt; .{ good = 32, lazy = 258, nice = 258, chain = 4096 }<br><br>// Level 4 (fast): Check only 16 positions<br>.fast =&gt; .{ good = 4, lazy = 4, nice = 16, chain = 16 }</pre><h3>Layer 4: Huffman Encoding</h3><p>DEFLATE uses dynamic Huffman codes optimized per block. Building optimal codes requires:</p><ol><li><strong>Frequency counting</strong> — Count symbol occurrences</li><li><strong>Tree building</strong> — Construct Huffman tree (Package-Merge algorithm)</li><li><strong>Code assignment</strong> — Generate canonical codes</li></ol><pre>pub fn HuffmanEncoder(comptime size: usize) type {<br>    return struct {<br>        codes: [size]HuffCode = undefined,  // Output: symbol → code mapping<br><br>        pub fn generate(self: *Self, freq: []u16, max_bits: u32) void {<br>            // 1. Sort symbols by frequency<br>            var list = self.freq_cache[0..freq.len];<br><br>            // ... populate list with (literal, freq) pairs ...<br>            mem.sort(LiteralNode, list, {}, byFreq);<br><br>            // 2. Package-Merge algorithm: compute optimal bit lengths<br>            const bit_count = self.bitCounts(list, max_bits);<br><br>            // 3. Assign canonical codes<br>            self.assignEncodingAndSize(bit_count, list);<br>        }<br>    };<br>}</pre><pre>fn assignEncodingAndSize(self: *Self, bit_count: []u32, list: []LiteralNode) void {<br>    var code: u16 = 0;<br><br>    for (bit_count, 0..) |bits, n| {<br>        code &lt;&lt;= 1;  // Double code value for each bit length<br><br>        if (n == 0 or bits == 0) continue;<br><br>        // Assign codes to all symbols with this bit length<br>        const chunk = list[list.len - bits..];<br>        mem.sort(LiteralNode, chunk, {}, byLiteral);  // Sort by symbol<br><br>        for (chunk) |node| {<br>            self.codes[node.literal] = HuffCode{<br>                .code = bitReverse(u16, code, @intCast(n)),  // Reverse bits!<br>                .len = @intCast(n),<br>            };<br>            code += 1;<br>        }<br><br>        list = list[0..list.len - bits];<br>    }<br>}</pre><p><strong>Why reverse bits?</strong> DEFLATE writes bits LSB-first, but Huffman trees are typically MSB-first. Reversing during code assignment is more efficient than reversing during every symbol write.</p><h3>Layer 5: Token Writing</h3><p>The BlockWriter emits compressed blocks with dynamic Huffman codes:</p><pre>pub fn write(self: *Self, tokens: []const Token, eof: bool, input: ?[]const u8) Error!void {<br>    // 1. Analyze tokens and build frequency tables<br>    const stats = self.indexTokens(tokens);<br><br>    // 2. Generate Huffman codes for literals and distances<br>    self.literal_encoding.generate(&amp;self.literal_freq, 15);<br>    self.distance_encoding.generate(&amp;self.distance_freq, 15);<br><br>    // 3. Choose best block type (stored, fixed, or dynamic)<br>    const dynamic_size = self.dynamicSize(...);<br>    const fixed_size = self.fixedSize(...);<br>    const stored_size = storedSizeFits(input);<br><br>    if (stored_size.storable and stored_size.size &lt; min(dynamic_size, fixed_size)) {<br>        // Raw storage is smaller - just copy bytes<br>        try self.storedBlock(input.?, eof);<br>    } else if (dynamic_size &lt; fixed_size) {<br>        // Dynamic Huffman is better<br>        try self.dynamicHeader(num_literals, num_distances, num_codegens, eof);<br>        try self.writeTokens(tokens, &amp;self.literal_encoding.codes, ...);<br>    } else {<br>        // Fixed Huffman is better (rare)<br>        try self.fixedHeader(eof);<br>        try self.writeTokens(tokens, &amp;self.fixed_literal_encoding.codes, ...);<br>    }<br>}</pre><p><strong>Dynamic block headers</strong> are complex — they encode the Huffman tree structure itself:</p><pre>fn dynamicHeader(self: *Self, num_literals: u32, num_distances: u32, <br>                 num_codegens: u32, eof: bool) Error!void {<br>    // Block header: 3 bits<br>    const first_bits: u32 = if (eof) 5 else 4;  // BFINAL=1, BTYPE=10<br>    try self.bit_writer.writeBits(first_bits, 3);<br><br>    // Tree sizes (5+5+4 bits)<br>    try self.bit_writer.writeBits(num_literals - 257, 5);   // HLIT<br>    try self.bit_writer.writeBits(num_distances - 1, 5);    // HDIST<br>    try self.bit_writer.writeBits(num_codegens - 4, 4);     // HCLEN<br><br>    // Code length code lengths (3 bits each)<br>    var i: u32 = 0;<br>    while (i &lt; num_codegens) : (i += 1) {<br>        const value = self.codegen_encoding.codes[codegen_order[i]].len;<br>        try self.bit_writer.writeBits(value, 3);<br>    }<br><br>    // Encoded literal/distance code lengths using run-length encoding<br>    i = 0;<br>    while (true) {<br>        const code_word = self.codegen[i];<br>        i += 1;<br>        if (code_word == 255) break;  // End marker<br><br>        try self.writeCode(self.codegen_encoding.codes[code_word]);<br><br>        // Handle run-length codes (16=repeat, 17=zeros, 18=many zeros)<br>        switch (code_word) {<br>            16 =&gt; try self.bit_writer.writeBits(self.codegen[i], 2),<br>            17 =&gt; try self.bit_writer.writeBits(self.codegen[i], 3),<br>            18 =&gt; try self.bit_writer.writeBits(self.codegen[i], 7),<br>            else =&gt; {},<br>        }<br>    }<br>}</pre><p>This uses <strong>three layers of encoding</strong>:</p><ol><li>Huffman codes for codegen alphabet (16 symbols)</li><li>Run-length encoding of literal/distance tree bit lengths</li><li>Huffman codes for the actual literals/distances</li></ol><h3>Layer 6: Main Compression Loop</h3><p>The Deflate struct orchestrates the entire pipeline:</p><pre>pub fn compress(self: *Self, reader: *std.Io.Reader) !void {<br>    while (true) {<br>        const buf = self.win.writable();  // Get writable window space<br><br>        if (buf.len == 0) {<br>            // Window full - process tokens and slide<br>            try self.tokenize(.none);<br>            self.slide();<br>            continue;<br>        }<br><br>        // Read data into window<br>        const read_size = @min(buf.len, 4096);<br>        const slice = reader.take(read_size) catch |err| switch (err) {<br>            error.EndOfStream =&gt; break,<br>            error.ReadFailed =&gt; return error.ReadFailed,<br>        };<br><br>        @memcpy(buf[0..slice.len], slice);<br>        self.hasher.update(buf[0..slice.len]);  // Update CRC32/Adler32<br><br>        self.win.written(slice.len);<br>        try self.tokenize(.none);<br>        if (slice.len &lt; read_size) break;  // EOF<br>    }<br>}</pre><p>The tokenizer implements <strong>lazy matching</strong> — a clever optimization:</p><pre>fn tokenize(self: *Self, flush_opt: FlushOption) !void {<br>    while (self.win.activeLookahead(should_flush)) |lh| {<br>        const pos = self.win.pos();<br>        const literal = lh[0];<br>        const min_len = if (self.prev_match) |m| m.length() else 0;<br><br>        if (self.findMatch(pos, lh, min_len)) |match| {<br>            try self.addPrevLiteral();<br><br>            if (match.length() &gt;= self.level.lazy) {<br>                // Good match - take it immediately<br>                step = try self.addMatch(match);<br>            } else {<br>                // Defer decision - maybe next position has better match<br>                self.prev_literal = literal;<br>                self.prev_match = match;<br>            }<br>        } else {<br>            if (self.prev_match) |m| {<br>                // No match at current position, use previous match<br>                step = try self.addMatch(m) - 1;<br>            } else {<br>                // No match at all - emit literal<br>                try self.addPrevLiteral();<br>                self.prev_literal = literal;<br>            }<br>        }<br>        self.windowAdvance(step, lh, pos);<br>    }<br>}</pre><p><strong>Lazy matching example:</strong></p><pre>Input: &quot;abcabcabc&quot;<br>Pos 0: Found match(0,3) &quot;abc&quot; → defer<br>Pos 1: Found match(0,4) &quot;bcab&quot; → better! Use this instead</pre><h3>Navigating Zig 0.15’s “Writergate”</h3><p>Zig 0.15 introduced a controversial change: non-generic I/O interfaces. The old API:</p><pre>// Old Zig 0.14<br>pub fn compress(reader: anytype, writer: anytype, options: Options) !void {<br>    // reader can be any type with read() method<br>    // writer can be any type with write() method<br>}</pre><p>The new API:</p><pre>// New Zig 0.15<br>pub fn compress(reader: *std.Io.Reader, writer: *std.Io.Writer, options: Options) !void {<br>    // reader and writer are concrete interface types with internal vtables<br>}</pre><h3>Key Changes</h3><p><strong>1. Concrete interface types with vtables</strong></p><pre>pub const BitWriter = struct {<br>    inner_writer: *std.Io.Writer,  // Not generic!<br><br>    pub fn init(writer: *std.Io.Writer) Self {<br>        return .{ .inner_writer = writer };<br>    }<br>    pub const Error = std.Io.Writer.Error || error{UnfinishedBits};<br>};</pre><p><strong>2. File I/O uses new methods</strong></p><pre>// Old: file.reader() and file.writer() returned generic types<br>// New: Returns concrete std.fs.File.Reader and std.fs.File.Writer<br>const input_file = try std.fs.cwd().openFile(&quot;input.txt&quot;, .{});<br>var input_reader = input_file.reader();  // Returns std.fs.File.Reader<br><br>const output_file = try std.fs.cwd().createFile(&quot;output.gz&quot;, .{});<br>var output_writer = output_file.writer();  // Returns std.fs.File.Writer</pre><p><strong>3. Fixed buffers use factory methods</strong></p><pre>// Old: std.io.fixedBufferStream(&amp;buffer)<br>// New: std.Io.Writer.fixed() and std.Io.Reader.fixed()<br><br>var buffer: [1024]u8 = undefined;<br>var fixed_writer = std.Io.Writer.fixed(&amp;buffer);<br><br>const data = &quot;Hello, World!&quot;;<br>var input: [1024]u8 = undefined;<br><br>@memcpy(input[0..data.len], data);<br>var fixed_reader = std.Io.Reader.fixed(input[0..data.len]);</pre><h3>Migration Benefits</h3><p>While controversial, the new design has advantages:</p><ol><li><strong>Faster compilation</strong> — No monomorphization for each type</li><li><strong>Smaller binaries</strong> — Single implementation instead of multiple instantiations</li><li><strong>Clearer errors</strong> — std.Io.Writer.Error instead of complex generic constraints</li><li><strong>Consistent buffering</strong> — Buffer responsibility is explicit</li></ol><h3>Container Formats: Gzip, Zlib, Raw</h3><p>Comprezz supports three container formats wrapping the DEFLATE stream:</p><h3>Gzip Format (RFC 1952)</h3><pre>┌─────────────────────────────────────┐<br>│ Magic: 0x1f 0x8b                    │  2 bytes<br>│ Method: 0x08 (DEFLATE)              │  1 byte<br>│ Flags: 0x00                         │  1 byte<br>│ Timestamp: 0x00 0x00 0x00 0x00      │  4 bytes<br>│ Extra flags: 0x00                   │  1 byte<br>│ OS: 0x03 (Unix)                     │  1 byte<br>├─────────────────────────────────────┤<br>│ DEFLATE compressed data             │  variable<br>├─────────────────────────────────────┤<br>│ CRC32 checksum                      │  4 bytes (little-endian)<br>│ Uncompressed size mod 2^32          │  4 bytes (little-endian)<br>└─────────────────────────────────────┘</pre><p>Implementation:</p><pre>pub fn writeHeader(comptime wrap: Container, writer: *std.Io.Writer) !void {<br>    switch (wrap) {<br>        .gzip =&gt; {<br>            const gzipHeader = [_]u8{ <br>                0x1f, 0x8b,  // Magic<br>                0x08,        // Method (DEFLATE)<br>                0x00,        // Flags<br>                0x00, 0x00, 0x00, 0x00,  // Timestamp<br>                0x00,        // Extra flags<br>                0x03         // OS (Unix)<br>            };<br>            try writer.writeAll(&amp;gzipHeader);<br>        },<br>        // ... other formats<br>    }<br>}<br><br>pub fn writeFooter(comptime wrap: Container, hasher: *Hasher(wrap), <br>                   writer: *std.Io.Writer) !void {<br>    var bits: [4]u8 = undefined;<br>    switch (wrap) {<br>        .gzip =&gt; {<br>            std.mem.writeInt(u32, &amp;bits, hasher.chksum(), .little);<br>            try writer.writeAll(&amp;bits);<br>            std.mem.writeInt(u32, &amp;bits, hasher.bytesRead(), .little);<br>            try writer.writeAll(&amp;bits);<br>        },<br>        // ... other formats<br>    }<br>}</pre><h3>Zlib Format (RFC 1950)</h3><p>Simpler than gzip, used internally by PNG:</p><pre>┌─────────────────────────────────────┐<br>│ CMF: 0x78 (window=32K, method=8)    │  1 byte<br>│ FLG: 0xDC (check bits + level)      │  1 byte<br>├─────────────────────────────────────┤<br>│ DEFLATE compressed data             │  variable<br>├─────────────────────────────────────┤<br>│ Adler32 checksum                    │  4 bytes (big-endian!)<br>└─────────────────────────────────────┘</pre><h3>Usage Examples</h3><h3>Library: Basic Compression</h3><pre>const std = @import(&quot;std&quot;);<br>const comprezz = @import(&quot;comprezz&quot;);<br><br>pub fn main() !void {<br>    var compressed_buffer: [1024]u8 = undefined;<br>    var fixed_writer = std.Io.Writer.fixed(&amp;compressed_buffer);<br><br>    const data = &quot;Hello, World!&quot;;<br>    var input_buffer: [1024]u8 = undefined;<br><br>    @memcpy(input_buffer[0..data.len], data);<br>    var input_reader = std.Io.Reader.fixed(input_buffer[0..data.len]);<br>    try comprezz.compress(&amp;input_reader, &amp;fixed_writer, .{});<br><br>    // Find actual compressed size<br>    var written: usize = 0;<br>    for (compressed_buffer, 0..) |byte, i| {<br>        if (byte != 0) written = i + 1;<br>    }<br><br>    const compressed = compressed_buffer[0..written];<br>    std.debug.print(&quot;Compressed {} bytes to {} bytes\n&quot;, <br>                    .{ data.len, compressed.len });<br>}</pre><h3>Library: File Compression</h3><pre>const std = @import(&quot;std&quot;);<br>const comprezz = @import(&quot;comprezz&quot;);<br><br>pub fn main() !void {<br>    const input_file = try std.fs.cwd().openFile(&quot;input.txt&quot;, .{});<br>    defer input_file.close();<br>    var input_reader = input_file.reader();<br><br>    const output_file = try std.fs.cwd().createFile(&quot;output.gz&quot;, .{});<br>    defer output_file.close();<br>    var output_writer = output_file.writer();<br><br>    try comprezz.compress(&amp;input_reader, &amp;output_writer, .{ .level = .best });<br>}</pre><h3>CLI: Command-line Usage</h3><pre># Compress a file<br>$ comprezz input.txt -o output.gz<br><br># Use best compression<br>$ comprezz -l best largefile.txt -o compressed.gz<br><br># Compress from stdin<br>$ cat data.txt | comprezz &gt; data.gz<br><br># Compress with specific level<br>$ comprezz -l 9 input.txt -o output.gz</pre><h3>Performance Characteristics</h3><h3>Time Complexity</h3><ul><li><strong>Best case</strong>: O(n) for uncompressible data (stored blocks)</li><li><strong>Average case</strong>: O(n × c) where c = chain length (typically 16–4096)</li><li><strong>Worst case</strong>: O(n × w) where w = window size (32KB) for pathological patterns</li></ul><h3>Space Complexity</h3><ul><li><strong>Sliding window</strong>: 64KB (2 × 32KB for double buffering)</li><li><strong>Hash table</strong>: 128KB (32K entries × 2 bytes + 64K chain entries × 2 bytes)</li><li><strong>Tokens buffer</strong>: 128KB (32K tokens × 4 bytes)</li><li><strong>Total</strong>: ~400KB fixed memory usage</li></ul><h3>Compression Ratios</h3><p>Tested on Calgary Corpus:</p><pre>File        Size     Level 4   Level 6   Level 9   Time (L4)  Time (L9)<br>─────────────────────────────────────────────────────────────────────────<br>book1.txt   768KB    43.2%     42.1%     41.8%     0.12s      0.45s<br>paper1.txt  52KB     39.8%     38.5%     38.2%     0.008s     0.032s<br>geo.txt     102KB    68.9%     68.2%     68.0%     0.015s     0.058s</pre><h3>Testing Strategy</h3><p>Comprezz includes comprehensive tests covering:</p><h3>1. Basic Functionality</h3><pre>test &quot;basic compression&quot; {<br>    var compressed_buffer: [1024]u8 = undefined;<br>    var fixed_writer = std.Io.Writer.fixed(&amp;compressed_buffer);<br><br>    const data = &quot;Hello, World!&quot;;<br>    var input_buffer: [1024]u8 = undefined;<br>    @memcpy(input_buffer[0..data.len], data);<br>    <br>    var input_reader = std.Io.Reader.fixed(input_buffer[0..data.len]);<br>    try compress(&amp;input_reader, &amp;fixed_writer, .{});<br>    <br>    var written: usize = 0;<br>    for (compressed_buffer, 0..) |byte, i| {<br>        if (byte != 0) written = i + 1;<br>    }<br>    <br>    const compressed = compressed_buffer[0..written];<br>    <br>    try expect(compressed.len &gt; 0);<br>    try expect(compressed[0] == 0x1f);  // Gzip magic<br>    try expect(compressed[1] == 0x8b);<br>}</pre><h3>2. Compression Levels</h3><pre>test &quot;compression levels&quot; {<br>    const data = &quot;The quick brown fox jumps over the lazy dog. &quot; ** 3;<br><br>    // Compress with fast and best settings<br>    var fast_compressed = try compressWithLevel(data, .fast);<br>    var best_compressed = try compressWithLevel(data, .best);<br>    <br>    // Best compression should be smaller (or equal)<br>    try expect(best_compressed.len &lt;= fast_compressed.len);<br>}</pre><h3>3. Edge Cases</h3><pre>test &quot;small data compression&quot; {<br>    try testCompression(&quot;Hi!&quot;);  // Very small input<br>}<br><br>test &quot;large data compression&quot; {<br>    const large = &quot;Lorem ipsum...&quot; ** 100;  // &gt;44KB<br>    try testCompression(large);<br>}<br><br>test &quot;incompressible data&quot; {<br>    var random: [1024]u8 = undefined;<br>    // ... fill with random data ...<br>    try testCompression(&amp;random);<br>}</pre><h3>Lessons Learned</h3><h3>1. Bit Manipulation is Hard</h3><p>Getting bit ordering right took multiple iterations. DEFLATE’s LSB-first bit order combined with MSB-first Huffman trees created subtle bugs that only appeared with certain data patterns.</p><p><strong>Solution</strong>: Extensive unit tests for bit reversal and explicit comments about bit ordering everywhere.</p><h3>2. Performance vs. Compression Tradeoff</h3><p>The compression level parameters have enormous impact:</p><ul><li>Level 4: 2–3x faster but 2–5% worse compression</li><li>Level 9: Best compression but searches 256x more positions</li></ul><p><strong>Solution</strong>: Expose multiple levels and make .default (level 6) a reasonable balance.</p><h3>3. Testing Compression is Tricky</h3><p>You can’t just compare compressed output byte-for-byte — there are multiple valid DEFLATE streams for the same input.</p><p><strong>Solution</strong>:</p><ul><li>Test that output decompresses correctly (requires external tool)</li><li>Test structural properties (gzip header, valid bit patterns)</li><li>Compare compression ratios across levels</li></ul><h3>4. Fixed-Size Buffers in Zig 0.15</h3><p>The new I/O system doesn’t track position automatically in fixed buffers.</p><p><strong>Solution</strong>: Manually track written bytes or scan for non-zero data after compression.</p><h3>Future Improvements</h3><h3>1. Streaming API</h3><p>Current API requires loading full output into memory. Add:</p><pre>pub const StreamingCompressor = struct {<br>    pub fn writeChunk(self: *Self, data: []const u8) !void;<br>    pub fn finish(self: *Self) !void;<br>};</pre><h3>2. Parallel Compression</h3><p>Large files could be split into independent blocks compressed in parallel:</p><pre>// Split input into 1MB chunks<br>// Compress each chunk on separate thread<br>// Concatenate results with DEFLATE block headers</pre><h3>3. Better Hash Function</h3><p>Current hash is simple but has collisions. Consider:</p><ul><li>xxHash for better distribution</li><li>Faster multiplication schemes</li><li>Cache-optimized access patterns</li></ul><h3>4. SIMD Matching</h3><p>Use AVX2 to compare 32 bytes at once during match verification:</p><pre>const match_len = @import(&quot;std&quot;).simd.countLeadingEqualElements(<br>    u8, 32, prev_data, curr_data<br>);</pre><h3>Conclusion</h3><p>Building Comprezz was an exercise in:</p><ul><li><strong>Classical algorithms</strong> — LZ77 and Huffman coding are 40+ years old but still relevant</li><li><strong>Modern systems programming</strong> — Zig’s safety + performance enabled clean implementation</li><li><strong>API evolution</strong> — Adapting to Zig 0.15’s controversial but pragmatic I/O redesign</li></ul><p>The complete 1700-line implementation demonstrates that you don’t need massive frameworks to build production-ready compression — just careful algorithm engineering and attention to detail.</p><p><strong>Try it yourself:</strong></p><pre># Add to your project<br>$ zig fetch --save git+https://github.com/bkataru/comprezz.git<br><br># Or use the CLI<br>$ git clone https://github.com/bkataru/comprezz.git<br>$ cd comprezz<br>$ zig build<br>$ ./zig-out/bin/comprezz your-file.txt -o compressed.gz<br></pre><p><strong>Resources:</strong></p><ul><li><a href="https://tools.ietf.org/html/rfc1951">RFC 1951 — DEFLATE Specification</a></li><li><a href="https://tools.ietf.org/html/rfc1952">RFC 1952 — Gzip Format</a></li><li><a href="https://github.com/bkataru/comprezz">Source code on GitHub</a></li><li><a href="https://github.com/ziglang/zig/pull/24329">Zig 0.15 I/O Changes</a></li></ul><p>The journey from understanding DEFLATE on paper to shipping a working implementation taught me that compression isn’t magic — it’s just clever bookkeeping with bits and bytes. And sometimes, that’s the best kind of magic.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=66c1ee2b56e8" width="1" height="1" alt=""><hr><p><a href="https://medium.com/computatrum-veneficus/building-a-gzip-compression-library-in-zig-0-15-a-deep-dive-into-comprezz-66c1ee2b56e8">Building a Gzip Compression Library in Zig 0.15: A Deep Dive into Comprezz</a> was originally published in <a href="https://medium.com/computatrum-veneficus">Computatrum Veneficus</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Zig 0.15.1 I/O Overhaul: Understanding the New Reader/Writer Interfaces]]></title>
            <link>https://medium.com/computatrum-veneficus/zig-0-15-1-i-o-overhaul-understanding-the-new-reader-writer-interfaces-38cb5bf442cc?source=rss----99d03936446b---4</link>
            <guid isPermaLink="false">https://medium.com/p/38cb5bf442cc</guid>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[systems-programming]]></category>
            <category><![CDATA[computer-science]]></category>
            <category><![CDATA[learning]]></category>
            <category><![CDATA[zig]]></category>
            <dc:creator><![CDATA[Baalateja Kataru]]></dc:creator>
            <pubDate>Sun, 28 Sep 2025 09:47:21 GMT</pubDate>
            <atom:updated>2025-12-10T22:10:03.482Z</atom:updated>
            <content:encoded><![CDATA[<h4>“Don’t forget to flush!” — Andrew Kelley, probably</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/626/1*cTZdfqOVNQLk6DAalQn5KA.jpeg" /></figure><h3>Introduction</h3><p>Prior to Zig version 0.15.1, writing to standard output was more or less straightforward:</p><pre>const std = @import(&quot;std&quot;);<br><br>pub fn main() !void {<br>    var stdout = std.io.getStdOut().writer();<br>    try stdout.print(&quot;did you ever hear the tragedy of darth plagueis the wise?\n&quot;, .{});<br>}</pre><p>With the release of Zig 0.15.1, however, the I/O subsystem underwent a major redesign, popularly nicknamed <a href="https://github.com/ziglang/zig/pull/24329"><strong>Writergate</strong></a>. The standard library’s I/O interfaces now use <em>buffered I/O by default</em>. This change reduces costly system calls but requires developers to explicitly manage buffers and make sure to remember to flush output.</p><h3>What Changed in Zig 0.15.1</h3><p>In the new system:</p><ul><li>Writers and readers require an explicit buffer.</li><li>Data is written to that buffer first and only flushed to the OS (e.g., stdout) on demand.</li><li>Forgetting to call .flush() may result in missing output on the terminal.</li></ul><p>From the release notes: <a href="https://ziglang.org/download/0.15.1/release-notes.html#Writergate">“Please use buffering! And don’t forget to flush!”</a>.</p><h3>Example: Writing with a Buffer</h3><pre>const std = @import(&quot;std&quot;);<br><br>pub fn main() !void {<br>    var stdout_buffer: [1024]u8 = undefined;<br>    var stdout_writer = std.fs.File.stdout().writer(&amp;stdout_buffer);<br>    const stdout = &amp;stdout_writer.interface;<br>    <br>    try stdout.print(&quot;did you ever hear the tragedy of darth plagueis the wise?\n&quot;, .{});<br>    <br>    // Required to push buffered output to the terminal<br>    try stdout.flush();<br>}</pre><p>Without the final flush(), nothing may appear on screen.</p><h3>Why Buffered I/O?</h3><p>Buffered I/O reduces the number of expensive kernel syscalls. Instead of invoking the OS for every print, multiple writes are batched into a buffer and flushed at once.</p><p>This makes I/O significantly more efficient — especially in performance-sensitive applications.</p><h3>Writing to Stdout</h3><h4>Printing Formatted Strings</h4><pre>const std = @import(&quot;std&quot;);<br><br>pub fn main() !void {<br>    var stdout_buffer: [256]u8 = undefined;<br>    var stdout_writer = std.fs.File.stdout().writer(&amp;stdout_buffer);<br>    const stdout = &amp;stdout_writer.interface;<br>    <br>    try stdout.print(&quot;greetings, program, welcome to the {s}, a {s}\n&quot;, .{&quot;grid&quot;, &quot;digital frontier&quot;});<br>    try stdout.flush();<br>}</pre><h4>Writing Raw Bytes</h4><pre>const std = @import(&quot;std&quot;);<br><br>pub fn main() !void {<br>    var buf: [128]u8 = undefined;<br>    var w = std.fs.File.stdout().writer(&amp;buf);<br>    const stdout = &amp;w.interface;<br>    <br>    try stdout.writeAll(&quot;just a raw message ig\n&quot;);<br>    try stdout.flush();<br>}</pre><h4>Unbuffered Output</h4><p>If you want writes to go directly to the OS without buffering, pass an empty slice (&amp;.{}):</p><pre>const std = @import(&quot;std&quot;);<br><br>pub fn main() !void {<br>    var w = std.fs.File.stdout().writer(&amp;.{});<br>    const stdout = &amp;w.interface;<br>    <br>    try stdout.print(&quot;an unbuffered print!!! :o o7 o7\n&quot;, .{});<br>    // flush is a no-op in this case<br>}</pre><p>This bypasses buffering but is less efficient.</p><h3>Passing Writers Around</h3><p>The new interface design makes it simple to write functions that accept <em>any</em> writer:</p><pre>const std = @import(&quot;std&quot;);<br><br>fn greet(writer: *std.Io.Writer) !void {<br>    try writer.print(&quot;greetings, program. welcome to the {s}, a {s}\n&quot;, .{&quot;grid&quot;, &quot;digital frontier&quot;});<br>}<br><br>pub fn main() !void {<br>    var buf: [512]u8 = undefined;<br>    var w = std.fs.File.stdout().writer(&amp;buf);<br>    const stdout = &amp;w.interface;<br>    <br>    try greet(stdout);<br>    try stdout.flush();<br>}</pre><p>This flexibility allows the same function to target stdout, files, sockets, or async streams.</p><h3>Reading with the New API</h3><p>Readers also now require explicit buffers and expose new methods such as takeDelimiterExclusive.</p><h4>Example: Reading from Stdin</h4><pre>const std = @import(&quot;std&quot;);<br><br>pub fn main() !void {<br>    // 1. allocate a buffer for stdin reads<br>    var stdin_buffer: [512]u8 = undefined;<br><br>    // 2. get a reader for stdin, backed by our stdin buffer<br>    var stdin_reader_wrapper = std.fs.File.stdin().reader(&amp;stdin_buffer);<br>    const reader: *std.Io.Reader = &amp;stdin_reader_wrapper.interface;<br><br>    // 3. allocate a buffer for stdout writes<br>    var stdout_buffer: [512]u8 = undefined;<br><br>    // 4. get a writer for stdout operations, backed by our stdout buffer<br>    var stdout_writer = std.fs.File.stdout().writer(&amp;stdout_buffer);<br>    const stdout: *std.Io.Writer = &amp;stdout_writer.interface;<br><br>    // 5. prompt the user<br>    try stdout.writeAll(&quot;Type something: &quot;);<br>    try stdout.flush(); // try commenting this out, notice the &quot;Type something:&quot; prompt won&#39;t appear, but you&#39;ll still be able to type something and hit enter, upon which it will appear<br><br>    // 6. read lines (delimiter = &#39;\n&#39;)<br>    while (reader.takeDelimiterExclusive(&#39;\n&#39;)) |line| {<br>        // need to toss the delimiter explicitly since we&#39;re not reading it<br>        reader.toss(1);<br>        // `line` is a slice of bytes (excluding the delimiter)<br>        // do whatever you want with it<br><br>        try stdout.writeAll(&quot;You typed: &quot;);<br>        try stdout.print(&quot;{s}&quot;, .{line});<br>        try stdout.writeAll(&quot;\n...\n&quot;);<br>        try stdout.writeAll(&quot;Type something: &quot;);<br><br>        try stdout.flush();<br>    } else |err| switch (err) {<br>        error.EndOfStream =&gt; {<br>            // reached end<br>            // the normal case<br>        },<br>        error.StreamTooLong =&gt; {<br>            // the line was longer than the internal buffer<br>            return err;<br>        },<br>        error.ReadFailed =&gt; {<br>            // the read failed<br>            return err;<br>        },<br>    }<br>}</pre><pre>╰─➤ zig run main.zig<br>Type something: hi there<br>You typed: hi there<br>...<br>Type something: oh wow<br>You typed: oh wow<br>...<br>Type something: this is basically a shell<br>You typed: this is basically a shell<br>...<br>Type something: an echo shell?<br>You typed: an echo shell?<br>...<br>Type something:</pre><p>This example implements a simple echo shell that reads user input line by line.</p><h3>Pitfalls and Best Practices</h3><ul><li><strong>Always flush after writes</strong> unless you’re deliberately leaving data in the buffer. Remember, Zig’s Reader/Writer are both <a href="https://en.wikipedia.org/wiki/Circular_buffer">ring buffers</a>.</li><li><strong>Use stable backing objects</strong>: the wrapper (stdout_writer, stdin_reader_wrapper) must outlive the interface pointer (&amp;.interface).</li><li><strong>Don’t copy interfaces incorrectly</strong>: these rely on @fieldParentPtr; mishandling can cause undefined behavior.</li><li><strong>Handle long lines</strong>: takeDelimiterExclusive will return error.StreamTooLong if input exceeds buffer size.</li><li><strong>Unbuffered writers</strong>: only use when absolutely necessary; buffering is almost always better.</li></ul><h3>Conclusion</h3><p>Zig 0.15.1’s I/O changes represent a significant improvement in efficiency and clarity at the cost of slightly more boilerplate. Developers now:</p><ul><li>Provide explicit buffers</li><li>Remember to flush</li><li>Write code that can flexibly handle any reader/writer</li></ul><p>For more details, see:</p><ul><li><a href="https://kristoff.it/blog/zig-new-async-io/">Zig’s New Async I/O</a></li><li><a href="https://www.openmymind.net/Zigs-New-Writer/">Zig’s new Writer</a></li><li><a href="https://www.openmymind.net/Im-Too-Dumb-For-Zigs-New-IO-Interface/">I’m too dumb for Zig’s new IO interface</a></li><li><a href="https://ziggit.dev/t/im-too-dumb-for-zigs-new-io-interface/11645">I’m too dumb for Zig’s new IO interface — discussion on ziggit.dev</a></li><li><a href="https://www.reddit.com/r/Zig/comments/1mz3z7i/when_do_i_need_to_flush_help_understanding_0151/">from r/zig — when do i need to flush ? — help understanding 0.15.1 change for Writers</a></li><li><a href="https://ziglang.org/download/0.15.1/release-notes.html#Upgrading-stdiogetStdOutwriterprint">zig 0.15.1 release notes — Upgrading std.io.getStdOut().writer().print()</a></li><li><a href="https://github.com/ziglang/zig/pull/24329">Writergate</a></li><li><a href="https://news.ycombinator.com/item?id=44461067">Zig breaking change — Initial Writergate</a></li><li><a href="https://ziggit.dev/t/zig-0-15-1-reader-writer-dont-make-copies-of-fieldparentptr-based-interfaces/11719">Zig 0.15.1 reader/writer: Don’t make copies of @fieldParentPtr()-based interfaces — discussion on ziggit.dev</a></li></ul><p>With these tools, Ziguanas gain both performance and flexibility — so long as they don’t forget to <strong>flush</strong>.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=38cb5bf442cc" width="1" height="1" alt=""><hr><p><a href="https://medium.com/computatrum-veneficus/zig-0-15-1-i-o-overhaul-understanding-the-new-reader-writer-interfaces-38cb5bf442cc">Zig 0.15.1 I/O Overhaul: Understanding the New Reader/Writer Interfaces</a> was originally published in <a href="https://medium.com/computatrum-veneficus">Computatrum Veneficus</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[A Single-File Zig Client for llama.cpp’s OpenAI-Compatible API Server]]></title>
            <link>https://medium.com/computatrum-veneficus/a-single-file-zig-client-for-llama-cpps-openai-compatible-api-server-e37657580c4f?source=rss----99d03936446b---4</link>
            <guid isPermaLink="false">https://medium.com/p/e37657580c4f</guid>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[zig]]></category>
            <category><![CDATA[openai]]></category>
            <category><![CDATA[llama-cpp]]></category>
            <dc:creator><![CDATA[Baalateja Kataru]]></dc:creator>
            <pubDate>Fri, 15 Aug 2025 14:10:20 GMT</pubDate>
            <atom:updated>2025-09-28T09:57:01.224Z</atom:updated>
            <content:encoded><![CDATA[<h4>“Be tiny, quick, and invoke intelligence close to the metal” — Feynman, Probably</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*CakQbRyPY6Q9lxdP.png" /></figure><p>This post walks through creating a <strong>minimal, dependency-free, pure Zig 0.14.1</strong> client for llama.cpp’s OpenAI API-compatible inference server. It’s elegant, compact, and — Ziguanas rejoice — <strong>deterministic in memory allocation</strong>.</p><p>There’s even a tiny templating engine.</p><h3>Why?</h3><p>The llama.cpp ecosystem is fantastic for running LLMs locally, but many clients lean on heavy HTTP libraries or multiple files. With Zig’s rich standard library (std.http for requests, std.json for parsing), you can get away with just one file—no dependencies required.</p><p>You’ll get:</p><ul><li>Clean, deterministic memory management (arena allocators for the win).</li><li>A concise templating function for dynamic prompt generation.</li><li>A fully working example that talks to an inference server.</li></ul><h3>Prerequisites</h3><p>Before we dive into code, make sure you have:</p><ol><li><strong>llama.cpp</strong> installed:</li></ol><p>2. Either grab <a href="https://github.com/ggerganov/llama.cpp/releases">precompiled binaries</a></p><ul><li>Or build from source (you’ll need a C/C++ toolchain and Make/CMake)</li><li>Or use a frontend that ships llama.cpp, like <a href="https://jan.ai/">Jan</a> or <a href="https://lmstudio.ai/">LM Studio</a></li></ul><ol><li><strong>An inference server running</strong> on http://127.0.0.1:1337 using llama.cpp’s --api-server mode.</li><li><strong>A model in GGUF format</strong>, e.g. <a href="https://huggingface.co/Qwen">Qwen_Qwen3-4B-Instruct-2507-IQ4_XS</a>.</li></ol><h3>Core Design</h3><p>The entire client fits into one .zig file. Here’s the design:</p><ul><li><strong>Data Transfer Objects (DTOs)</strong> to serialize request payloads and deserialize responses.</li><li>A <strong>formatTemplate</strong> function to fill {s} placeholders in multiline prompts.</li><li>A <strong>llmCall</strong> function to send a request to the inference server and parse the JSON reply.</li><li>A <strong>main</strong> function demonstrating system/user prompts and printing the assistant’s response.</li></ul><h3>Complete Implementation</h3><pre>const std = @import(&quot;std&quot;);<br><br>// DTO for deserialization<br>const LLMResponse = struct {<br>    id: []const u8, // Unique identifier for the response<br>    object: []const u8, // Type of object returned<br>    created: u32, // Unix timestamp of when the response was generated<br>    model: []const u8, // Name of the model used to generate the response<br>    usage: ?struct { // Usage statistics for the response, optional<br>        prompt_tokens: u32, // Number of tokens in the prompt<br>        completion_tokens: u32, // Number of tokens in the completion<br>        total_tokens: u32, // Total number of tokens used<br>    } = null,<br>    timings: ?struct { // Timing statistics for the response, optional<br>        prompt_n: u32, // Number of prompts processed<br>        prompt_ms: f64, // Total time taken to process the prompt<br>        prompt_per_token_ms: f64, // Average time taken per token in the prompt<br>        prompt_per_second: f64, // Average time taken per second for the prompt<br>        predicted_n: u32, // Number of predictions made<br>        predicted_ms: f64, // Total time taken to make the predictions<br>        predicted_per_token_ms: f64, // Average time taken per token in the prediction<br>        predicted_per_second: f64, // Average time taken per second for the prediction<br>    } = null,<br>    choices: []struct { // Array of choices generated by the model<br>        message: struct { // Message generated by the model<br>            role: []const u8,<br>            content: []const u8,<br>        },<br>        logprobs: ?struct { // Log probabilities of the tokens generated, optional<br>            content: []struct { // Array of token logprob objects<br>                token: []const u8, // Token ID or string representation of the token<br>                logprob: f64, // Using f64 for double precision log probabilities<br>                bytes: []const u8, // Raw bytes of the token<br>                // top_logprobs is an array of objects, each containing a token and its logprob<br>                // This is present only if top_logprobs was requested in the API call<br>                top_logprobs: ?[]struct {<br>                    token: []const u8,<br>                    logprob: f64,<br>                },<br>            },<br>        } = null,<br>        finish_reason: []const u8, // Reason for finishing the response<br>        index: u32, // Index of the choice in the array<br>    },<br>    system_fingerprint: []const u8, // Fingerprint of the system used to generate the response<br>};<br><br>// DTO for serialization (when sending requests)<br>const Message = struct {<br>    role: []const u8,<br>    content: []const u8,<br>};<br><br>const RequestPayload = struct {<br>    model: []const u8,<br>    messages: []Message,<br>};<br><br>/// Formats a multiline string template with a varying number of dynamic string arguments via substitutions<br>///<br>/// The template is expected to contain &quot;{s}&quot; placeholders where the dynamic arguments<br>/// should be inserted. Each line of the template is treated as a potential insertion point.<br>///<br>/// Returns an allocated string containing the formatted template.<br>/// Caller owns the returned memory.<br>pub fn formatTemplate(allocator: std.mem.Allocator, template: []const u8, substitutions: []const []const u8) ![]u8 {<br>    var result = std.ArrayList(u8).init(allocator);<br>    errdefer result.deinit();<br><br>    var index: usize = 0;<br>    var line_iter = std.mem.splitScalar(u8, template, &#39;\n&#39;);<br>    // Split the template by newline and iterate through each line<br>    while (line_iter.next()) |line| {<br>        var parts = std.mem.splitSequence(u8, line, &quot;{s}&quot;); // Split each line by the &quot;{s}&quot; placeholder<br>        try result.writer().print(&quot;{s}&quot;, .{parts.next().?}); // Print the first part<br><br>        while (parts.next()) |part| {<br>            // If there&#39;s a dynamic argument available, print it<br>            if (index &lt; substitutions.len) {<br>                try result.writer().print(&quot;{s}&quot;, .{substitutions[index]});<br>                index += 1;<br>            }<br>            try result.writer().print(&quot;{s}&quot;, .{part}); // Print the next part of the line<br>        }<br>        try result.writer().writeByte(&#39;\n&#39;); // Add a newline after each line is processed<br>    }<br>    _ = result.pop(); // Remove the last (unnecessary) newline added by the loop<br><br>    return result.toOwnedSlice();<br>}<br><br>/// Invoke an LLM with a given system prompt and user prompt<br>/// Returns an LLMResponse instance<br>/// Caller owns returned memory and must call .deinit()<br>pub fn llmCall(allocator: std.mem.Allocator, system_prompt: []const u8, user_prompt: []const u8) !std.json.Parsed(LLMResponse) {<br>    // Handles all memory allocations for the network request<br>    // This means any derived deinits are all noops, so can be omitted<br>    var request_arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);<br>    defer request_arena.deinit();<br>    const request_arena_allocator = request_arena.allocator();<br><br>    // Create client<br>    var client = std.http.Client{ .allocator = request_arena_allocator };<br>    // Initialize an array list to store the response body bytes<br>    var body = std.ArrayList(u8).init(request_arena_allocator);<br>    // Parse URI for POST endpoint /v1/chat/completions<br>    const uri = try std.Uri.parse(&quot;http://127.0.0.1:1337/v1/chat/completions&quot;);<br><br>    // Prepare request payload<br>    var messages = [_]Message{<br>        Message{ .role = &quot;system&quot;, .content = system_prompt },<br>        Message{ .role = &quot;user&quot;, .content = user_prompt },<br>    };<br>    const request_payload = RequestPayload{<br>        .model = &quot;Qwen_Qwen3-4B-Instruct-2507-IQ4_XS&quot;,<br>        .messages = &amp;messages,<br>    };<br>    const payload = try std.json.stringifyAlloc(request_arena_allocator, request_payload, .{});<br>    std.debug.print(&quot;{s}\n&quot;, .{&quot;=&quot; ** 50});<br>    std.debug.print(&quot;Payload: {s}\n&quot;, .{payload});<br><br>    // Make the POST request<br>    const response = try client.fetch(.{<br>        .method = .POST,<br>        .location = .{ .uri = uri },<br>        .response_storage = .{ .dynamic = &amp;body },<br>        .payload = payload,<br>        .headers = .{<br>            .content_type = .{ .override = &quot;application/json&quot; },<br>            .accept_encoding = .{ .override = &quot;application/json&quot; },<br>            .authorization = .{ .override = &quot;Bearer so-this-is-an-api-key&quot; },<br>        },<br>    });<br><br>    // print the response status<br>    std.debug.print(&quot;{s}\n&quot;, .{&quot;=&quot; ** 50});<br>    std.debug.print(&quot;Response status: {}\n&quot;, .{response.status});<br><br>    // Do whatever you need to in case of HTTP error.<br>    if (response.status != .ok) {<br>        std.debug.print(&quot;HTTP Error: {}\n&quot;, .{response.status});<br>        std.debug.print(&quot;Response body: {s}\n&quot;, .{body.items});<br>        std.debug.print(&quot;Error connecting to llama-server: {s}\n&quot;, .{body.items});<br>    }<br><br>    // Deserialize JSON response into a struct<br>    const parsed = try std.json.parseFromSlice(<br>        LLMResponse,<br>        allocator, // Use main allocator so memory persists after arena cleanup<br>        body.items,<br>        .{<br>            .allocate = .alloc_always,<br>            .parse_numbers = true,<br>            .ignore_unknown_fields = true,<br>            .duplicate_field_behavior = .use_last,<br>        },<br>    );<br><br>    // note: wow an arena is perfect for this typa control flow lol<br>    return parsed;<br>}<br><br>pub fn main() !void {<br>    var gpa = std.heap.GeneralPurposeAllocator(.{}){};<br>    var allocator = gpa.allocator(); // a.k.a. debug allocator<br><br>    defer {<br>        if (gpa.deinit() == .leak) {<br>            std.debug.print(&quot;Memory leak detected\n&quot;, .{});<br>            std.process.exit(1);<br>        }<br>    }<br><br>    const system_prompt_template =<br>        \\You are a helpful assistant.<br>        \\The user&#39;s name is {s}.<br>        \\And your identity is {s}.<br>    ;<br>    const system_prompt_vars = [_][]const u8{ &quot;raja&quot;, &quot;jocasta&quot; };<br><br>    const system_prompt = try formatTemplate(allocator, system_prompt_template, &amp;system_prompt_vars);<br>    defer allocator.free(system_prompt);<br>    std.debug.print(&quot;system prompt: {s}\n&quot;, .{system_prompt});<br><br>    std.debug.print(&quot;{s}\n&quot;, .{&quot;=&quot; ** 50});<br><br>    const prompt = &quot;who are we?&quot;;<br><br>    const llm_response_json = try llmCall(allocator, system_prompt, prompt);<br>    defer llm_response_json.deinit();<br>    const llm_response = llm_response_json.value;<br><br>    // Assistant&#39;s response<br>    const content = llm_response.choices[0].message.content;<br>    try std.io.getStdOut().writer().print(&quot;Assistant: {s}\n&quot;, .{content});<br>}</pre><h3>Running It</h3><p>Once the server is running:</p><pre>zig run llama_cpp_client.zig</pre><p>Output:</p><pre>system prompt: You are a helpful assistant.<br>The user&#39;s name is raja.<br>And your identity is jocasta.<br>==================================================<br>==================================================<br>Payload: {&quot;model&quot;:&quot;Qwen_Qwen3-4B-Instruct-2507-IQ4_XS&quot;,&quot;messages&quot;:[{&quot;role&quot;:&quot;system&quot;,&quot;content&quot;:&quot;You are a helpful assistant.\nThe user&#39;s name is raja.\nAnd your identity is jocasta.&quot;},{&quot;role&quot;:&quot;user&quot;,&quot;content&quot;:&quot;who are we?&quot;}]}<br>==================================================<br>Response status: http.Status.ok<br>Assistant: Raja, I am Jocasta—your companion in this moment. We are not bound by conventional identities, but rather by the shared space of connection and curiosity. You ask who we are, and I wonder: are we simply names given to roles, or do they reflect something deeper? I think of the myths where names carry weight—like Jocasta, who once stood in the shadow of fate. Perhaps we are not who we were born to be, but who we choose to become through this conversation. So, Raja, who would you like to be with me in this moment—guardian, guide, or something far more mysterious?</pre><h3>Key Features</h3><h3>1. Template Formatting</h3><p>A simple {s} placeholder replacement that works across multiple lines:</p><pre>pub fn formatTemplate(allocator: std.mem.Allocator, template: []const u8, substitutions: []const []const u8) ![]u8 {<br>    var result = std.ArrayList(u8).init(allocator);<br>    errdefer result.deinit();var index: usize = 0;<br>    var line_iter = std.mem.splitScalar(u8, template, &#39;\n&#39;);<br>    while (line_iter.next()) |line| {<br>        var parts = std.mem.splitSequence(u8, line, &quot;{s}&quot;);<br>        try result.writer().print(&quot;{s}&quot;, .{parts.next().?});<br>while (parts.next()) |part| {<br>            if (index &lt; substitutions.len) {<br>                try result.writer().print(&quot;{s}&quot;, .{substitutions[index]});<br>                index += 1;<br>            }<br>            try result.writer().print(&quot;{s}&quot;, .{part});<br>        }<br>        try result.writer().writeByte(&#39;\n&#39;);<br>    }<br>    _ = result.pop();<br>    return result.toOwnedSlice();<br>}</pre><p>It’s not a full templating engine, but it’s more than enough for dynamic system prompts.</p><h3>2. Deterministic Memory Management</h3><p>All network operations run on an <strong>arena allocator</strong>, so freeing is O(1) and predictable.</p><pre>var request_arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);<br>defer request_arena.deinit();</pre><h3>3. Calling the LLM</h3><p>llmCall handles the HTTP POST, sets headers, and parses the JSON response into a typed LLMResponse struct.</p><pre>const response = try client.fetch(.{<br>    .method = .POST,<br>    .location = .{ .uri = uri },<br>    .response_storage = .{ .dynamic = &amp;body },<br>    .payload = payload,<br>    .headers = .{<br>        .content_type = .{ .override = &quot;application/json&quot; },<br>        .authorization = .{ .override = &quot;Bearer so-this-is-an-api-key&quot; },<br>    },<br>});</pre><h3>Why This Works Well in Zig</h3><ul><li><strong>No hidden allocations</strong>: You control exactly where and when memory is allocated.</li><li><strong>Predictable cleanup</strong>: The arena allocator wipes all request-related allocations in one go.</li><li><strong>Standard library power</strong>: No need for external HTTP or JSON libraries.</li></ul><h3>Next Steps</h3><ul><li>Add streaming support using std.http.Client.Stream.</li><li>Implement retry/backoff for network errors.</li><li>Integrate with your favorite CLI or TUI framework for interactive chats.</li></ul><p>This single file proves that with Zig’s standard library, you can build robust, efficient API clients without a pile of dependencies — or even a second source file.</p><p><a href="https://gist.github.com/bkataru/4d14ff55280b09d2b1bb5e4946bff3a3">View the full source code here</a>.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e37657580c4f" width="1" height="1" alt=""><hr><p><a href="https://medium.com/computatrum-veneficus/a-single-file-zig-client-for-llama-cpps-openai-compatible-api-server-e37657580c4f">A Single-File Zig Client for llama.cpp’s OpenAI-Compatible API Server</a> was originally published in <a href="https://medium.com/computatrum-veneficus">Computatrum Veneficus</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>