{"id":50656332,"url":"https://github.com/TheApeMachine/caramba","last_synced_at":"2026-06-24T21:00:41.178Z","repository":{"id":357066060,"uuid":"1234839491","full_name":"TheApeMachine/caramba","owner":"TheApeMachine","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-09T12:53:49.000Z","size":39630,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T14:23:27.470Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheApeMachine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-10T17:54:03.000Z","updated_at":"2026-06-09T12:56:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/TheApeMachine/caramba","commit_stats":null,"previous_names":["theapemachine/caramba"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/TheApeMachine/caramba","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheApeMachine%2Fcaramba","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheApeMachine%2Fcaramba/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheApeMachine%2Fcaramba/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheApeMachine%2Fcaramba/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheApeMachine","download_url":"https://codeload.github.com/TheApeMachine/caramba/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheApeMachine%2Fcaramba/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34749211,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-08T00:00:39.465Z","updated_at":"2026-06-24T21:00:41.156Z","avatar_url":"https://github.com/TheApeMachine.png","language":"TypeScript","funding_links":[],"categories":["Server Implementations"],"sub_categories":["🧪 Experimental Implementations"],"readme":"![Header image of the caramba logo, a rainbow C shape, with the most notable features mentioned](header1.png)\n\n# 🌈 caramba\n\n**A substrate for A.I. research.**\n\n**Caramba** is a comprehensive machine learning research stack built to guide you through the entire lifecycle of A.I. development. Whether you want to rapidly prototype a new concept or dive deep into low-level hardware optimization, Caramba provides a dedicated environment tailored to your exact workflow. \n\nOperating on the core philosophy that **a manifest is a model**, Caramba allows you to define complex architectures entirely via YAML files instead of writing code. It acts as a complete laboratory, seamlessly taking you from your initial idea to a heavily optimized, fully profiled pipeline.\n\n**Core Capabilities:**\n\n* 📝 **Fully Manifest-Driven:** Declare your topology in simple YAML. Caramba goes far beyond standard layers and operations, allowing you to easily express sophisticated, non-standard mathematical primitives and advanced custom architectures.\n* 🚀 **Flexibility \u0026 Optimization:** Dedicated to high performance, Caramba gives you the tools to choose your level of abstraction. Move fast to iterate on high-level ideas, or drop down for granular, low-level control over compute and memory.\n* 🔬 **Sophisticated Inspection:** Deeply understand your network's behavior. Caramba is equipped with advanced inspection and profiling tooling, bringing clarity to every step of the end-to-end research process.\n* 🤖 **Integrated A.I. Collaboration:** Supercharge your workflow with a built-in A.I. assistant and virtual research team. Caramba is built from the ground up to support both human team collaboration and agentic brainstorming.\n* 🔐 **Zero-Compromise Privacy:** Working with proprietary or sensitive data? Caramba can operate entirely in an optional \"local-only\" mode, ensuring your research and intellectual property never leave your secure environment.\n\n## ✨ Features\n\n- [x] Compute Primitives\n  - [x] Activation (ReLU, LeakyReLU, SELU, Sigmoid, Tanh, GeLU, Swish, SwiGLU)\n  - [x] Attention (SDPA, MQA, GQA, sliding window, softmax)\n  - [x] Convolution (Conv1D, Conv2D, Conv3D, ConvTranspose2D)\n  - [x] Embedding (token, RoPE, ALiBi, tied)\n  - [x] Math (matmul, add/mul/pow/atan2/mod, exp/log, rmsnorm, layernorm, groupnorm, softmax, logsumexp, dropout, sin, cos)\n  - [x] Pooling (avg, max, adaptive avg, adaptive max)\n  - [x] Projection (linear, fused QKV, tied embedding)\n  - [x] Shape (reshape, transpose, gather, scatter, where, masked fill, concat, split, view_as_heads, merge_heads, last_token, nearest upsample)\n  - [x] Masking (causal mask, apply mask)\n  - [x] Active Inference (free energy, expected free energy, belief update, precision weighting)\n  - [x] Energy-Based Model Blocks (Boltzmann distribution, EBM free energy, Langevin step, contrastive phase)\n  - [x] Causal Inference (do-calculus, backdoor, frontdoor, CATE, IV, counterfactual, DAG factorization)\n  - [x] Hawkes Process (intensity, kernel matrix, simulate, log-likelihood)\n  - [x] Markov Blanket (partition, mutual information, internal/active flow)\n  - [x] Predictive Coding (prediction, prediction error, representation/weight updates)\n  - [x] VSA (bind, bundle, permute, inverse permute, similarity)\n- [x] Multiple Compute Backends\n  - [x] CPU (Go native; **amd64** and **arm64** only — 32-bit `GOARCH=386` is not supported)\n  - [x] SIMD/Assembly\n    - [ ] AVX-512 (amd64)\n    - [x] AVX2 (amd64)\n    - [x] SSE2 (amd64)\n    - [x] NEON (arm64)\n  - [x] CUDA\n  - [x] METAL\n  - [x] XLA\n- [x] Optimizers (SGD, Adam, AdamW, AdaMax, AdaGrad, AdaDelta, RMSProp, Lion, LARS, LAMB, L-BFGS, Hebbian)\n- [ ] Training Models\n- [ ] Fine-tuning Models\n- [x] Manifest Compiler (verify, canonicalize, CSE, algebraic simplify, fusion, DCE, memory planning, cost scheduling)\n- [x] SafeTensors architecture manifests (`from_safetensors`, config-driven registry lookup, direct tensor binding)\n- [x] Hugging Face Hub Asset Resolver (revision-pinned, content-addressed, Xet CAS)\n- [x] Provenance Ledger (signed by `pkg/notary`)\n- [x] Streaming Chat Runtime (KV cache, sampling, `qpool` startup events)\n- [x] Diffusion Pipeline (FlowMatch Euler, prompt encoder + denoiser + VAE decoder)\n- [ ] Supported Pre-trained Models\n  - [x] [openai-community/gpt2](https://huggingface.co/openai-community/gpt2)\n  - [x] [meta-llama/Llama-3.2-1B-Instruct](https://huggingface.co/meta-llama/Llama-3.2-1B-Instruct) (Gated model, requires request for access)\n  - [ ] [meta-llama/Llama-4-Scout-17B-16E](https://huggingface.co/meta-llama/Llama-4-Scout-17B-16E)\n  - [x] [black-forest-labs/FLUX.2-klein-4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B)\n  - [ ] [google/gemma-4-31B-it](https://huggingface.co/google/gemma-4-31B-it)\n  - [ ] [ibm-granite/granite-4.1-8b](https://huggingface.co/ibm-granite/granite-4.1-8b)\n  - [ ] [Qwen/Qwen3-Coder-Next](https://huggingface.co/Qwen/Qwen3-Coder-Next)\n  - [ ] [stabilityai/stable-diffusion-3-medium](https://huggingface.co/stabilityai/stable-diffusion-3-medium)\n  - [ ] [meituan-longcat/LongCat-AudioDiT-3.5B](https://huggingface.co/meituan-longcat/LongCat-AudioDiT-3.5B)\n  - [ ] [facebook/ijepa_vith16_1k](https://huggingface.co/facebook/ijepa_vith16_1k)\n  - [ ] [facebook/vjepa2-vitg-fpc64-256](https://huggingface.co/facebook/vjepa2-vitg-fpc64-256)\n- [ ] Visual Node-Graph Architecture Builder\n- [ ] ModelScope deep inspection tools\n- [ ] Layer Surgery tools\n- [ ] Hyperparameter Tuner\n- [ ] Distributed Training\n- [ ] Integrated Benchmarking Suite\n- [ ] Deeply Integrated A.I. Assistant and Research Team\n- [ ] Ergonomic WYSIWYG LaTeX Paper Editor\n- [ ] Multi-User/Team Collaboration\n\n## 🚀 Quick start\n\n```bash\ngo install github.com/theapemachine/caramba@latest\n\ncaramba serve\n```\n\nThe above command brings up just the HTTP API, which means you still have to bring up the data stores yourself.\n\nAlternatively you could grab the `docker-compose.yml` from this repository to make this process much easier.\n\n`caramba research \u003cname\u003e` lays out a project as a directory under version control:\n\n```\nresearch/project/my-ablation-study/\n├── manifest/\n│   ├── architecture/   # the architectures under comparison\n│   └── operation/      # custom operations specific to this study\n└── paper/              # write-up\n```\n\nConfiguration lives in [cmd/asset/config.yml](cmd/asset/config.yml) and is loaded through [pkg/config](pkg/config). The resolver tries `--config`, then `./cmd/asset/config.yml`, `./config.yml`, `$HOME/.caramba/config.yml`, and finally the binary's embedded default. Data-store clients (`pkg/store/*`) read `store.qdrant`, `store.neo4j`, `store.elasticsearch`, and `store.deeplake` from that file (secrets may use `${...}` expansion); they do not call `os.Getenv` directly.\n\n→ [Getting Started](./docs/getting-started.md)\n\n## Building for a specific backend\n\n```bash\n# CPU — Go + AVX2/SSE2/NEON. Always available.\ngo build ./pkg/backend/compute/cpu/...\n\n# CUDA — Linux, NVIDIA CUDA toolkit\nCGO_ENABLED=1 go build -tags \"cgo cuda\" ./pkg/backend/device/cuda/...\n\n# Metal — macOS, Xcode command-line tools (darwin + cgo selects Metal automatically)\ngo generate ./pkg/backend/device/metal\nCGO_ENABLED=1 go build -tags cgo ./pkg/backend/device/metal/...\n\n# XLA via PJRT — configure compute.xla in cmd/asset/config.yml first\ngo build -tags \"cgo xla\" ./pkg/backend/device/xla/...\n```\n\n```go\ntype Runner interface {\n    Execute(\n        ctx context.Context,\n        graph *ir.Graph,\n        targets []*ir.Node,\n    ) (map[string]tensor.Tensor, error)\n\n    Location() tensor.Location\n    Close() error\n}\n```\n\nBackend kernels upload values once into a resident tensor store and only download at real boundaries. The executor releases owned dependencies after their last graph consumer; the host arena reuses released spans. Host-staged dispatch is restricted to the host backend, so Metal, CUDA, and XLA paths cannot silently route through CPU slices.\n\n→ [Compute Backends](./docs/compute.md)\n\n## 💾 Repository layout\n\n```\ncmd/                Cobra CLI: serve, chat, image, research\n  asset/config.yml  The single config source\npkg/\n  manifest/         YAML → IR compiler, registry, lowering\n  runtime/          Manifest runtime programs, state, ops, schedulers, graph bridge\n  backend/\n    compute/        Runner interface + cpu/, cuda/, metal/, xla/\n    api/            HTTP server\n  hub/              Hugging Face cache, Xet CAS\n  tokenizer/        ByteLevel BPE\n  model/            Weight binding, SafeTensors loader\n  notary/           Identity + provenance ledger\n  store/            S3, Elasticsearch, Neo4j, Qdrant, DeepLake\n  config/           Single config gateway\nfrontend/           Vite + React + Flume node editor\ndocs/               Long-form documentation\nAGENTS.md           Backend implementation contract — required reading for kernel work\n```\n\n---\n\n## 🔬 Testing\n\nEvery code file has a `_test.go` mirror. Tests are GoConvey-style (\"Given X, it should Y\", nested). Backend kernels run parity tests against the scalar reference at `N ∈ {1, 7, 64, 1024, 8192}` with tight ULP bounds — the tolerance is a contract, not a knob.\n\n```bash\ngo test ./...\nCGO_ENABLED=1 go test -tags cgo            ./pkg/backend/device/metal/...\nCGO_ENABLED=1 go test -tags \"cgo cuda\"     ./pkg/backend/device/cuda/...\n              go test -tags \"cgo xla\"      ./pkg/backend/device/xla/...\n```\n\n---\n\n## 📓 Documentation\n\n| Document                                                       | What's inside                                                                                     |\n|----------------------------------------------------------------|---------------------------------------------------------------------------------------------------|\n| [Getting Started](./docs/getting-started.md)                   | Install, first chat, first study                                                                  |\n| [Architecture](./docs/architecture.md)                         | System design, IR, executor                                                                       |\n| [Manifest \u0026 Governance](./docs/manifest.md)                    | Manifest grammar, compiler pipeline, examples                                                     |\n| [Compute Backends](./docs/compute.md)                          | CPU/SIMD, CUDA, Metal, XLA in depth                                                               |\n| [Backend inventory](./docs/backend-inventory.md)               | `device.Backend` methods ↔ `ir.RequiredOperationIDs()`                                            |\n| [CPU dispatch matrix](./docs/cpu-dispatch-matrix.md)           | Per-domain scalar / AVX-512 / AVX2 / SSE2 / NEON registration                                     |\n| [Device backend matrix](./docs/device-backend-matrix.md)       | Metal / CUDA / XLA kernel registrations, dtypes, required-op coverage                             |\n| [Backend coverage matrix](./docs/backend-coverage.md)          | Combined T1.2–T1.4 registration snapshot and R1 execution-target summary                          |\n| [Backend compliance audit](./docs/backend-compliance-audit.md) | T1.6 machine checks: forbidden phrasing, cross-ISA calls, amd64 scalar tails, loose test epsilons |\n| [Operations](./docs/operations.md)                             | Operation library, SIMD kernels, custom ops                                                       |\n| [Frontend \u0026 Visualization](./docs/frontend.md)                 | Node editor, microscope tooling                                                                   |\n| [The Notary](./docs/notary.md)                                 | Identity, ledger, custody model                                                                   |\n| [Agents](./docs/agents.md)                                     | Conversational ingress, LLM providers                                                             |\n| [AGENTS.md](./AGENTS.md)                                       | Backend implementation contract for contributors                                                  |\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTheApeMachine%2Fcaramba","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTheApeMachine%2Fcaramba","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTheApeMachine%2Fcaramba/lists"}