# C Header Libraries The following libraries are *highly* experimental and should be treated as such. The intent of this repository is archival in nature. While I do use many of the following libraries in my projects, they are not production ready. Please feel free to create issues, and pull requests are always welcome. ## ann.h - Artificial Neural Network This library provides an implementation of a fully connected, artificial neural network with backpropagation. The entirety of the ANN is stored in a single memory allocation, allowing for ease in persisting models and training via external methods. ### Activation Functions The activation function for hidden layers can be chosen independently from that used for the output layer. - Identity - Binary - Sigmoid - RELU - ELU - LRELU - Tanh ## bin.h - Flat File Block Storage This library is an experiment in storing ordered numerical data as binary "flat files". The contained data must be of a fixed block size. The primary goal of the library is to provide a simple method of persisting and caching data that is time-series in nature. The resulting files should be short lived. ### Format The file header contains two 64 bit unsigned integers, block count and block size. The rest of the file contains the block data. Each block must possess a numerical key/index as the first element. Prior to using the library, a ```typedef [numerical_type] bin_key_t``` must be declared in the implementation file. **Operations:** read, write, insert, append, search, and fuzzy search This is a naive library, and as such, does not provide input validation. If data is placed out of order, *there it will remain.* ## buffer.h - Dynamic Buffer A dynamically resizing buffer with embedded metadata. Stores capacity, element count, and element size preceding the data pointer. Automatically doubles capacity when usage exceeds 80%, and halves when below 20% (minimum capacity of 32). ## clio.h - Pseudo-TUI Layout A minimal layout layer over escape.h: escape.h owns styling (SGR, cursor motion, clear, color), clio.h owns layout — where text goes, how it wraps and clips, and how a composed frame reaches the terminal. Apps compose frames into an in-memory cell grid (canvas); `clio_flush` diffs the canvas against the last flushed frame and blits only changed rows through escape.h. Non-tty output (pipes, CI) falls back to plain text lines so piped output stays clean. Also provides a pure chunk-fed key decoder (testable without a tty), raw-mode key reading with a bounded queue, and a single-line editor (`clio_readline`) that renders into the canvas. No global state; each `clio_term` is independent. **Dependencies:** escape.h (styling layer — the `esc_*` functions need one defining TU with `ESCAPE_IMPLEMENTATION`) and type.h. ## direct.h - Computation Graph A computation graph library with topological update ordering. Nodes are connected via edges and evaluated in dependency order using DFS. Uses a generation counter to avoid re-evaluating unchanged nodes. Provides basic arithmetic node functions (add, subtract) as examples. ## dotagents.h - .agents Protocol (read-only) Parses and resolves the two-layer `.agents/` directory convention (global `~/.agents/` plus workspace `./.agents/`, workspace winning on conflicts): AGENTS.md guidelines, system prompt, `mcp.json`, `models.json` presets, `speakmcp-settings.json`, `layouts/ui.json`, skills, sub-agent profiles, repeat tasks, and persistent memories. Read-only — it never writes. Load never fails: missing layers and malformed files become warnings, never hard errors. Output is id-sorted for stable diffs. **Dependencies:** frontmatter.h and libc. ## escape.h - ANSI Escape Codes This library provides utility functions and macros for an assortment of ANSI escape codes, including cursor movement, screen clearing, text formatting, and color output. Each operation is available as both a macro (string literal) and a function (writes to stdout or a given FILE*). ## frontmatter.h - Markdown Frontmatter Parser Parses a markdown document with an optional `---` fenced frontmatter block into typed values: `key: value` lines yielding strings (quotes stripped), booleans, integers, and lists (CSV or JSON array). Includes a small embedded JSON value type — parse, serialize, lookup, and shallow merge with ownership transfer (`fm_json_merge_owned`). An unterminated fence means the whole text is body. **Operations:** `parse_frontmatter`, `doc_get`, `doc_free`, `fm_list_items`, `fm_json_parse` / `fm_json_serialize` / `fm_json_get` / `fm_json_merge_owned`. **Dependencies:** libc only. Header-only: all functions are `static inline`, safe to include in any number of translation units. ## flat.h - Directory Traversal This library provides a simple wrapper for traversing POSIX file systems. The intention for this library is to be used alongside bin.h, for the purpose of traversing hierarchical directory structures. Provides both POSIX (dirent.h) and Windows (FindFirstFileA) implementations. ## genetic.h - Genetic Algorithm An implementation of a genetic algorithm. The library exposes a single function for creating a new generation of individuals. The function is "generic", meaning that the respective operations for crossover, mutation, and fitness are passed as function pointers. ### Algorithm Overview **1. Crossover** - Determine the selection cutoff for the population. - Replace all unfit individuals by performing a crossover operation with two randomly selected fit individuals. **2. Mutation** - Determine the number of mutation operations, and perform those on randomly selected individuals. **3. Fitness** - Sort the population by ascending fitness, in preparation for the next generation. ## interpolate.h - 1D Interpolation Macros A collection of interpolation and easing macros inspired by "Math for Game Programmers: Fast and Funky 1D Nonlinear Transformations". Provides namespaced `INTERP_*` macros for collision safety, legacy unprefixed aliases guarded by `#ifndef`, and function wrappers for debuggability. ## llm.h - LLM Provider Protocol Layer Header-only protocol layer for LLM chat endpoints: OpenAI-compatible (`/chat/completions`), Anthropic (`/v1/messages`), and Ollama (`/api/chat`). Request assembly (messages, tools, per-provider shaping), HTTP POST with stop-cancellation, SSE and NDJSON streaming with live delta emission, response and error-body parsing, and `Retry-After` handling. Pure protocol — no application state: messages arrive as borrowed `llm_message` arrays, tools as a pre-built `"tools":[...]` fragment, and tool execution, session access, and emit formatting are supplied by the caller. **Dependencies:** curl, cJSON, libc only. Header-only: all functions are `static inline`, safe to include in any number of translation units. ## pool.h - Memory Pool A free-list based memory pool. The pool has a fixed size after allocation. **Note:** The size of a block must be greater than or equal to ```sizeof(void *)``` ## pushdown.h - Pushdown Automata An implementation of a stack-based pushdown automata with 65+ operations. Instructions execute sequentially until an END marker, supporting arithmetic, trigonometry, stack manipulation (Forth-style), and comparison operations. Designed for use with stack.h. ## stack.h - Stack Implementation A generic dynamic stack with automatic resizing. Requires the user to define ```typedef stack_value_t``` before inclusion. Provides both simple variants (return zero on empty) and ```_ok``` variants (return status code) for pop and peek operations. ## test.h - Test Utilities A minimal test framework providing ```ASSERT```, ```ASSERT_FLOAT_EQ```, and ```ASSERT_STR_EQ``` macros. Tracks failure count and prints results. Not a library for distribution — intended for the test suite only. ## type.h - Type Aliases Common type aliases used across the libraries: ```i8```, ```i16```, ```i32```, ```i64```, ```u8```, ```u16```, ```u32```, ```u64```, ```f32```, ```f64```. ## ufo.h - Universal Function Originator An implementation of the symbolic regression technique known as a Universal Function Originator. The originating paper can be found [here](https://doi.org/10.1016/j.asoc.2020.106417). Uses a single-allocation design for easy persistence and serialization. ## uri.h - URI Builder A simple, and likely incomplete, implementation of a "builder" pattern to generate URIs as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). The URIs are stored internally as separate components, enabling sequential URIs to be generated with ease.