GitHub Weekly Trending Repositories

cloudflare/computer

Give your agent a computer 👾

Cloudflare Computer

Cloudflare Computer is a virtual filesystem that lives inside a Durable Object. The Durable Object holds the authoritative state in SQLite and exposes one pluggable execution surface through workspace.runtime. Three backends ship today:

Container projects the SQLite state into a sandbox container as a real FUSE mount. A sandbox-side daemon (computerd) mounts the state as a filesystem and syncs changes back over a capnweb RPC channel. Full Linux userland, real binaries, real network.
Isolate shell runs just-bash in a Dynamic Worker. It reaches the authoritative Workspace over Workers RPC, so there is no second store or sync round trip.
Isolate JavaScript runs an ECMAScript module in a fresh Dynamic Worker with structured input/results, durable relative imports, configured libraries, Workspace-backed node:fs/promises, and trusted ws:git and ws:artifacts modules.

A Workspace may register multiple backends under stable IDs. workspace.runtime.exec(source, { backend }) is the single execution entry point; the selected backend defines whether source is a shell command or an ECMAScript module. Backends connect lazily on first use.

Workspace can also be constructed without a backend at all, giving callers the filesystem on its own.

Important

PREVIEW ONLY This package is provided as a preview for feedback only. APIs are unstable and the design is subject to change.

Suitable for experiments, exploration and prototypes. It is NOT suitable for production use at this time.

The specification under docs/ is forward-looking — read it for intent, not as description of the code today.

Using it

If you want to build on Cloudflare Computer, install @cloudflare/computer and follow that package's README — it has the installation steps, the entrypoint map, and worked examples of the fs and runtime surfaces.

To contribute feedback, see CONTRIBUTING.md. Approved collaborators should follow COLLABORATORS.md for setup, build, and test instructions.

Examples

The examples/ directory holds runnable consumers of the public surface. Each is a Worker workspace with its own README.

examples/container — runs computerd inside a container, mounts a workspace, and talks to a Durable Object over capnweb. A write / read / exec HTTP surface.
examples/worker-shell — same HTTP surface as the container example, but the shell runs just-bash in a Dynamic Worker loaded through env.LOADER. No container.
examples/worker-javascript — mirrors worker-shell, but exec evaluates an ECMAScript module in a Dynamic Worker instead of running a shell command.
examples/egress — sends one URL through the container, Worker shell, and Worker JavaScript backends with matching none, all, or custom egress policies.
examples/think — a @cloudflare/think chat agent that uses the workspace as its working directory, reachable from a terminal.
examples/think-compare-runtimes — a web UI that runs the same agent task against the container and worker runtimes side by side.
examples/tutorial — a step-by-step build: one endpoint, one agent that writes a markdown recipe card on the host and runs pandoc on it in the container to produce a PDF.
examples/artifacts — generates a Worker project in a workspace and publishes it to Cloudflare Artifacts as a clone-ready repo.
examples/assets — turns a prompt into an image with Workers AI, writes it to the workspace, and returns a shareable link through @cloudflare/computer/assets.

Repository layout

The repo is a small monorepo. Each package has its own README with package-specific status and usage notes.

packages/dofs (@cloudflare/dofs) — Durable Object SQLite-backed virtual filesystem, sync protocol building blocks, and a @platformatic/vfs provider for Node.
packages/rpc (@cloudflare/computer-rpc) — capnweb wire types and server/client helpers shared between the Durable Object and computerd.
packages/computerd (@cloudflare/computerd) — the computerd daemon: a FUSE mount plus HTTP/WebSocket RPC server that runs inside the sandbox container.
packages/computer (@cloudflare/computer) — the top-level Computer package consumed by Durable Objects. Work in progress.
packages/computer-computerd-linux-x64 — private Docker image context for the prebuilt computerd linux-x64 binary. The image, not an npm package, is the release artifact.

Performance

computerd's FUSE mount beats real disk on metadata-heavy work and trails it on large sequential I/O. See docs/19_performance.md for the full fs-bench numbers, a cloudflare/sandbox-sdk npm install comparison, and how to reproduce them.

Documentation

docs/ — design specification. Forward-looking; treat as intent.
docs/19_performance.md — filesystem benchmarks.

Contributing

We accept bug reports, fix proposals, feature requests, and design proposals through issues and discussions. We do not accept unsolicited pull requests. See CONTRIBUTING.md for the public contribution paths.

Approved collaborators should follow COLLABORATORS.md for setup, formatting, testing, commit message, and pull request conventions.

If you're working in this repo as an agent, start with AGENTS.md and the skills under .agents/skills/.

License

MIT. See LICENSE.

huangruiteng/loopx

Lightweight loop engineering state kernel for long-running AI agent teams. Agent-loop agnostic across Codex, Claude Code, and other coding agents, with durable goals, quota-aware auto-wake, executable todos, evidence logs, and verifiable handoffs.

LoopX

The open, provider-neutral, stateful control plane for long-running agents.

_{Keep objectives, gates, todos, evidence, quota, and handoffs stable while Codex, Claude Code, Cursor, or your own runtime executes bounded turns.}

Public website · Docs · Developer Book · Try LoopX · See real loops · How it works · User manual · 简体中文

把会干活的 Agent，接成可管理、可复盘、可持续改进的数字员工。

Open and provider-neutral, LoopX is a lightweight state kernel and local-first control plane for loop engineering. It keeps long-running work reviewable, restartable, and easier to hand off across turns, tools, and agents without replacing the runtime that performs the work.

Loop engineering for long-running AI agents and peer agent teams.

Keep the loop moving. Keep the judgment human.

Learn LoopX

Developer Book - the curated bilingual path from control-plane foundations to project onboarding and developer contributions. 中文版 · English
Getting started - install, connect a project, and run your first governed loop. Guide
Docs - the full reference and operations site. LoopX Docs

Why LoopX

An agent can finish a task in one session. Long-running work is harder: objectives change, owner decisions appear, evidence goes stale, agents hand work to peers, and a scheduler can keep spending after no useful transition remains. Chat memory and a timer are not enough to govern that.

LoopX keeps the durable control state in one compact layer:

objective / issue / project
   │
   ▼
LoopX state: objective + gates + todos + scope + evidence + quota
   │
   ├─ human judgment needed? ── yes ─▶ ask a concrete question and wait
   │
   ├─ safe fallback available? ──────▶ run one bounded agent slice
   │
   ▼
Codex / Claude Code / Cursor / shell agent executes one turn
   │
   ▼
write evidence + handoff + next todo ─▶ quota decides the next tick

Agent runtimes execute the work. LoopX governs the state that lets engineering, research, discovery, and operations loops continue across runs. It is not another agent framework or a provider-specific orchestration runtime.

A useful mental model is an agent-native Kanban for long-running work. Cards carry identity, authority, evidence, and continuation. Moves are validated operators such as claim, gate, monitor, and writeback. The board is a projection; LoopX state remains the source of truth.

Registered agents are peers. Claims, leases, task boundaries, capabilities, and typed continuation decide who acts next; no durable leader identity is required.

LoopX is useful when you run:

multi-day engineering, research, benchmark, or experiment objectives;
issue and PR loops that must preserve scope, evidence, and review state;
recurring heartbeat or monitor work;
projects with owner, safety, publication, or private-data gates;
peer-agent teams where ownership, leases, and handoff matter;
creator, research, or operations workflows whose progress must remain legible to a non-engineering operator.

LoopX is not an autonomous production controller. Dangerous permissions, publishing, production writes, and final ownership stay with the human.

Evidence

These are not one-turn demos. The public OpenViking contribution sequence and the redacted, owner-run Auto ML showcase each span 200+ hours of elapsed loop lifetime across many bounded turns, decisions, and evidence updates. Elapsed lifetime is wall-clock project time. It is not 200 hours of continuous model execution or a claim of unattended production autonomy. Open each visual to inspect the public-safe graph, evidence branches, and decisions preserved across turns.

Open-Source Issue Fix

200+ hour public contribution arc: PR delivery and reusable fix knowledge evolve together.

LoopX's creator uses this path as an OpenViking contributor. The represented public contribution sequence spans more than 200 elapsed hours from its first PR creation to the latest represented review or update. The Issue-Fix capability keeps rolling repository context, revision-stamped fix knowledge, and reviewer-facing preferences separate; linked PRs plus current checkout source and tests remain authoritative.

Auto ML Experiment

Redacted owner-run showcase: a 200+ hour experiment arc keeps hypotheses, matched evidence, invalid lineages, running replicates, and promote/stop gates visible in one graph.

The redacted public-safe graph preserves decision lineage across that 200+ hour elapsed window. It is an owner-run showcase, not a claim of continuous compute, independent reproduction, a production result, or company or employer endorsement. The redacted image is not sufficient to reproduce the underlying experiment independently.

Auto Research

Reproducible public KNN demo: proposer, executor, and evaluator/promoter agents iterate in parallel while todo, quota, evidence, and targeted wake remain visible.

This screenshot comes from LoopX's built-in exact-KNN demo. The public task, editable and protected files, deterministic CPU evaluator, and dev/held-out commands all live in this repository. Follow the showcase walkthrough or the command path to reproduce the workflow; it is a demo result, not a production research claim.

Used In Real Projects

Independent user · >13h C++ accuracy run. The user reported that a multi-stage task stayed aligned, triggered public research, adopted a public code-memory tool, and improved final precision. Read the evidence boundary.
Independent user · 4d unattended run. The user reported four days without human intervention, useful ongoing work, and a periodic report surface. Read the redacted case.
Independent user · 7 merged PRs. A LoopX-attributed Engine refactor is visible in a public issue and seven merged PRs; attribution and the reported 1B+ token scale remain user reports. Inspect the case.

These are the three strongest current cases, not the full inventory. Browse the complete Showcase catalog for contributor cases, creator dogfooding, reproducible demos, and explicit evidence-strength labels.

More inspectable surfaces:

the public homepage for the product narrative, quick start, and long-running evidence;
the complete Showcase catalog and its bilingual hosted index;
the cross-runtime implementation review demo;
the public user manual.

Try LoopX

Requirements: Python 3.11+, curl, tar, and a macOS or Linux shell. Git is only needed for contributor clone/canary workflows. The Python package has no runtime dependencies outside the standard library.

Install without cloning:

curl -fsSL https://huangruiteng.github.io/loopx/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
loopx doctor

Then connect from your project root:

cd /path/to/your-project
loopx connect
loopx status

If the project has not been initialized and connect tells you state is missing, use the guided path:

loopx start-goal --guided --project . --goal-text "Your long-running objective"

LoopX should reuse existing state rather than overwrite it. Keep .loopx/, .codex/goals/, and .local/ ignored.

Start From Your Agent

Host	Recommended start	Loop driver
Codex App	Ask the agent to connect this project to LoopX, run `loopx doctor`, preserve existing state, and report the current gate and next todo. Then use `$loopx <complex task>` or choose `loopx` from `/skills`.	Codex App heartbeat automation, refreshed from `quota should-run.scheduler_hint`
Codex App over SSH	`loopx agent-onboard --agent-type codex-app-ssh --project .`	The returned visible `/goal <task_body>`
Codex CLI	Start `codex` in the project, ask it to connect and diagnose LoopX, then use `$loopx <complex task>` or `/skills`.	Visible `/goal <task_body>`; no hidden headless execution by default
Claude Code	Install the opt-in adapter, then run `/loopx <task>` followed by `/loop`.	Native Claude Code `/loop` gated by LoopX
OpenCode	Install the static command facade; opt in to `--with-goal-bridge` for recurring goals.	OpenCode command facade and explicit goal bridge
Pi	Install the opt-in goal extension with `loopx slash-commands --install --surface pi`, then use `/loopx <task>` from a trusted Pi session.	Visible Pi goal extension gated by LoopX quota (`loopx_goal_activate` + `agent_settled` continuation)
Cursor, shell, or custom runner	Use the installer and `loopx doctor`; connect manually or call LoopX from your runner.	Your shell, scheduler, or runner

The exact, copy-ready setup messages and host recovery paths live in Getting Started. Host integrations can inspect the Codex App host command registry contract, the Codex CLI packaged install path, or the Claude Code adapter.

For custom runners, start with the minimal custom runtime example (python3 examples/custom-runtime-minimal-cli-turn-smoke.py), then the full Embed LoopX in Your Agent Runner guide and the worker bridge install contract. The core tick is deliberately small:

loopx quota should-run      # should this registered agent act now?
loopx todo claim            # who owns this slice?
loopx todo update           # what changed?
loopx refresh-state         # what should the next turn see?
loopx quota spend-slot      # account for a completed, validated slice

First-Run Feedback

If LoopX works for you, a one-minute public issue helps us learn what a real first run looks like. It is optional, contains no telemetry, and should not include logs, paths, credentials, internal project names, or goal contents:

loopx first-run-report prints the same prefilled link locally without sending anything.

A successful connection has:

loopx doctor passing;
.loopx/registry.json and a projected active goal state;
loopx status showing the current objective, concrete user gate, and next agent todo;
a visible loop driver or an exact activation instruction;
local runtime state ignored rather than committed.

Clone-based install is only for contributors who want the live canary wrapper:

git clone https://github.com/huangruiteng/loopx ~/loopx
~/loopx/scripts/install-local.sh
loopx doctor

Capabilities

LoopX folds its control-plane mechanics into five questions:

Question	What LoopX keeps visible
What is the objective?	The active goal, explicit scope, and current authority.
What happens next?	Ordered user and agent todos, ownership, claims, and leases.
What needs human judgment?	Concrete user gates instead of a vague "waiting for owner."
What evidence changed?	Compact run history, validation, blockers, and accepted writeback.
May the loop continue?	Quota, capabilities, safe fallback, scheduler hints, and stop conditions.

Control-Plane Surface

Surface	What it does	Start with
Goal state and status	Tracks active state, todos, claims, gates, evidence, run history, and first-screen attention.	`loopx status`, `loopx diagnose`, `loopx review-packet`
Quota and interaction contract	Decides whether a turn should deliver, ask, wait, self-repair, or stay quiet.	`loopx quota should-run`, quota allocation
Agent runtime bridges	Keeps Codex App, Codex CLI, Claude Code, and generic workers aligned with the same guard.	`loopx heartbeat-prompt`, `loopx codex-cli-bootstrap-message`, `loopx worker-bridge`
Operator surfaces	Renders compact status without making the browser the state authority.	`loopx serve-status`, dashboard
External projections	Projects todos and gates into collaboration surfaces while LoopX remains authoritative.	`loopx lark-kanban`, Lark Kanban adapter
Domain capabilities	Packages repeatable work lanes such as issue fixing, content operations, value connector planning, ML experiment advice, benchmark evidence, and Explore.	`loopx issue-fix`, `loopx content-ops`, `loopx value-connectors`, `loopx ml-experiment`, `loopx benchmark`, Explore
Experimental context learning	Lets named registered agents trial provider-neutral Reward Memory through ignored, default-off project configuration. OpenViking is one provider option, not a global dependency.	`loopx reward-memory experiment-status`, Reward Memory architecture
Governance patterns	Captures reusable routing, gate, evidence, projection, and planning shapes.	interaction patterns, state model

The shipped primitives include lifetime goals, concrete user gates, audited safe fallbacks, peer todo ownership, quota and steering, compact run history, evidence-backed handoff, a read-first management surface, project-level value signals, and public/private boundary checks.

Runtime Responsibilities

Role	Responsibility
Agent	Plans, analyzes, uses tools, and performs one bounded action through a host/runtime.
Provider	Calls external systems and returns observations, effect results, and readback.
Capability	Defines the caller outcome, normalizes provider output, validates it, and proposes a typed transition.
Kernel	Owns durable todos, gates, monitors, accepted writeback, quota, recovery, and scheduling.

The execution path is Agent -> Capability -> Provider; the control path returns Provider readback -> Capability transition -> Kernel. An extension is how an optional provider is packaged and managed, not another control-plane owner. See Architecture and Extensions and Capabilities.

Advanced Paths

The first useful loop does not require every optional surface. Add these only when the work needs them.

Inspect the current goal's read-only capability catalog before enabling an advanced path:

loopx configure-goal --goal-id <goal-id>

Without --execute, this reports current/default state, fit, boundaries, and copyable commands without changing project state.

Presets and Auto Research

Safe presets cover daily triage, changelog drafts, and PR watching. The one-command research path coordinates proposer, executor, and evaluator/promoter roles while keeping quota and evidence visible. See the beginner preset guide and Auto Research command path.

loopx preset list
loopx preset show daily-triage

Preset inspection is read-only. For a connected recurring goal, loopx ready-score --goal-id <goal-id> --agent-id <agent-id> reports whether the loop is ready to run repeatedly.

Governed Turns

LoopX can generate one pure, bounded turn decision from a validated receipt, fresh quota state, and a provider-neutral budget. The current Codex CLI quickstart and activation contract are documented in LoopX Turn for Codex CLI.

Explore Graph and Harness

Explore is supported, optional, and default-off. It works best when a task has a measurable offline evaluation, baseline, treatment, and guardrails; it is not a substitute for production approval. Start with the Explore capability and its Lark presentation mapping.

Review Agent Work

Use loopx review-packet for a compact owner-facing view of decisions, evidence, validation, and unresolved gates. The intelligent management surface describes the operator model; the project-level reward model describes conservative value signals across output quantity, quality, token cost, and user attention cost.

For one concrete peer workflow, see the cross-runtime implementation review demo: Claude implements and Codex reviews while LoopX keeps ownership, evidence, quota, and handoff explicit.

App and Projection Paths

Local read-first UI: dashboard guide
Public product overview: public homepage
Documentation portal: hosted docs
Feishu/Lark projection: Lark Kanban adapter
Generic host integration: integration guide
Custom multi-agent runner: minimal custom runtime example, then custom runner integration

Optional projections make state easier to inspect; they do not become the source of truth.

Operating and Recovery

Start daily inspection with:

loopx status
loopx history --goal-id your-project-goal
loopx quota should-run --goal-id your-project-goal

Automatic turns must check quota first and append spend only after validated writeback. Quiet skips, preflight failures, and dry-run previews do not spend. When a user gate blocks one lane, a separately audited safe fallback may continue, but it must not bypass the gate.

Peer agents use loopx todo claim before delivery and loopx todo update after validation so ownership and evidence remain visible.

Scheduler cadence follows quota should-run.scheduler_hint; installed Codex App automations acknowledge the current hint through the returned ack_hint.cli_args. Collision recovery, monitor semantics, self-repair, and the exact operator commands are maintained in Getting Started, Quota Allocation, and Long-Task Cadence Policy.

Before publishing public docs or examples:

loopx check \
  --scan-path README.md \
  --scan-path docs/ \
  --scan-path examples/

Advanced Documentation

Start with the path that matches your current task. Use the hosted documentation portal for the published docs site; the documentation index remains the complete source map. This list stays selective; each category index owns its deeper documents and versioned protocols.

Use and Operate

Getting Started: install, connect, diagnose, daily workflow, heartbeats, dashboard, development, and commands.
User Manual: public onboarding, concepts, FAQ, and selected cases.
Operations: goal continuation, todo, cadence, attention, and authority workflows.
Quota Allocation and Heartbeat Automation Prompt: scheduler eligibility, spend, and scheduled continuation.
Dashboard and Status Data Contract: operator-facing state and projection contracts.
Release Readiness: install/update paths, compatibility gates, release notes, and safe-to-depend-on surfaces.

Understand the Control Plane

Architecture: lifetime-goal invariant and kernel.
State Interaction Model: actors, stores, interaction contract, and writeback.
Concepts: reusable routing, gate, evidence, projection, and planning patterns.
Product Foundations: Loop Engineering principles, project-level reward, and reward-style replanning.
Product Vision: the broader Loop Agent direction.

Integrate and Extend

Integration Guide
Minimal Custom Runtime Example
Custom Agent Runner Integration
Integrations: runtime, host, collaboration, and external-system adapters, including worker bridge and Lark.
Extensions and Capabilities

Build and Review LoopX

Developer Guide: contributor workflows, benchmark development, documentation layout, and quality gates.
Reference and Protocols: stable contracts and versioned implementation protocols, including host command and reward memory architecture.
Control-Plane Developer Course: nine Chinese, code-led lectures.
Testing and Quality: validation layers and risk-based checks.
Public/Private Boundary: safe fixtures, examples, evidence, and publication.

Inspect Outcomes

Showcase Catalog: public-safe cases and evidence labels.
Research and Evidence: benchmark investigations and source-backed findings.
Update Notes: public-safe progress notes.

Project and Community

Partner Projects

LoopX welcomes collaboration with other open-source projects to build the long-running agent ecosystem. Our confirmed partners include:

OpenViking - Self-evolving context database for AI agents
NoKV - AI native distributed file system

Community and Feedback

LoopX is still early. The most useful feedback comes from real long-running agent projects: where the control plane helped, where it felt heavy, and which gates or handoffs disappeared from view.

Use GitHub Issues for reproducible bugs, install problems, and feature requests.
Open PRs for docs fixes, showcase writeups, and small public-safe examples.
Join the Discord community, or use Lark or WeChat below.

See Support for channel routing and service boundaries, and Communications for official publication sources.

_{Lark: scan to join directly
WeChat: huangrt00 · mention LoopX in the friend request}

Contributing

External contributors should start with Contributor Tasks for public, claimable work and Contributing for setup, validation, and boundary rules. Project roles and public history are recorded in Governance, Authors and Contributors, and Project History.

LoopX keeps local active state separate from the public repository. Do not commit .loopx/, .codex/goals/, live ACTIVE_GOAL_STATE.md, raw benchmark traces, credentials, private logs, or operator artifacts.

Current Status

The v0.4.x line is an early but usable local control plane for long-running agent work. It is not a full agent platform, an agent runtime, or an autonomous production controller.

Today LoopX ships a durable state kernel for goals, typed todos and decision scopes, peer claims and leases, evidence and writeback, quota-aware scheduling, and cross-turn continuation. Guided start, recurring heartbeat, isolated Codex CLI turns, evidence-backed Issue-Fix admission, optional Explore and auto research paths, public validation canaries, and a read-first multi-project dashboard build on that shared control state.

Support levels remain explicit. The state and CLI contracts are the stable center; several host integrations and advanced paths are optional, default-off, or experimental. LoopX does not grant credentials, approve destructive or production actions, publish on a user's behalf without authorization, or turn an unverified run into evidence of success.

The next milestones are simpler installation and host packaging, broader typed runtime adapters, stronger terminal acceptance across repeated public loops, independent adoption and outcome evidence, and a more polished management surface.

Star History

_{Generated every six hours from GitHub's official stargazer timestamps using a repository-authorized workflow. A snapshot is published only when the fetched rows match GitHub's current star count; GitHub's image cache may delay refreshes.}

License

MIT. See LICENSE.

firecrawl/pdf-inspector

Fast Rust library for PDF inspection, classification, and text extraction. Intelligently detects scanned vs text-based PDFs to enable smart routing decisions.

pdf-inspector

Fast Rust library for PDF classification and text extraction. Detects whether a PDF is text-based or scanned, extracts text with position awareness, and converts to clean Markdown — all without OCR. Includes bindings for Python, Node.js, and browser WebAssembly.

Built by Firecrawl to handle text-based PDFs locally in under 200ms, skipping expensive OCR services for the ~54% of PDFs that don't need them.

Features

Smart classification — Detect TextBased, Scanned, ImageBased, or Mixed PDFs in ~10-50ms by sampling content streams. Returns a confidence score (0.0-1.0) and per-page OCR routing.
Text extraction — Position-aware extraction with font info, X/Y coordinates, and automatic multi-column reading order.
Markdown conversion — Headings (H1-H4 via font size ratios), bullet/numbered/letter lists, code blocks (monospace font detection), tables (rectangle-based and heuristic), bold/italic formatting, URL linking, and page breaks.
Table detection — Dual-mode: rectangle-based detection from PDF drawing ops, plus heuristic detection from text alignment. Handles financial tables, footnotes, and continuation tables across pages.
CID font support — ToUnicode CMap decoding for Type0/Identity-H fonts, UTF-16BE, UTF-8, and Latin-1 encodings.
Multi-column layout — Automatic detection of newspaper-style columns, sequential reading order, and RTL text support.
Encoding issue detection — Automatically flags broken font encodings so callers can fall back to OCR.
Single document load — The document is parsed once and shared between detection and extraction, avoiding redundant I/O.
Browser WebAssembly — Run the same Rust parser locally in browsers and Web Workers, with embedded CMaps and no server round trip.
Lightweight — Pure Rust, no ML models, no external services. Single dependency on lopdf for PDF parsing.

Benchmark

Evaluated on the opendataloader-bench corpus (200 PDFs). Only local engines without model-based PDF parsing are shown; OCR was disabled. Scores are 0-1, higher is better.

Engine	Overall	Reading Order (NID)	Tables (TEDS)	Headings (MHS)	Speed (200 docs)
pdf-inspector	0.875	0.915	0.814	0.788	0.470s
liteparse	0.873	0.913	0.693	0.811	0.750s
opendataloader	0.831	0.902	0.489	0.739	2.569s
pymupdf4llm	0.735	0.886	0.401	0.424	17.117s
markitdown	0.589	0.844	0.273	0.000	16.165s

Results were refreshed on July 31, 2026, on an Apple M4 Pro. Engine versions were pdf-inspector 0.2.6, LiteParse 2.10.1, OpenDataLoader 2.2.1, PyMuPDF4LLM 0.2.0, and MarkItDown 0.1.5. Speed is the median of five alternating or rotating complete corpus runs after an excluded warm-up run, with each parser processing documents sequentially in a single process.

The complete parser configuration, per-document predictions, evaluator output, and generated charts are available in the reproducible results branch.

Best fit: Native-text PDFs where speed, reading order, and table structure matter. In this comparison, pdf-inspector delivered the higher overall, reading-order, and table scores, along with the fastest complete run. That makes it a strong local default for reports, research papers, financial documents, invoices, and legal PDFs that need clean, structured Markdown without adding OCR latency or infrastructure.

Use the paired benchmark harness to compare two local builds against the exact same corpus and evaluator revision.

Quick start

Python

pip install maturin
maturin develop --release

import pdf_inspector

result = pdf_inspector.process_pdf("document.pdf")
print(result.pdf_type)   # "text_based", "scanned", "image_based", "mixed"
print(result.markdown)   # Markdown string or None

Full API reference: docs/python.md

Node.js

npm install @firecrawl/pdf-inspector

import { readFileSync } from 'fs';
import { processPdf, classifyPdf } from '@firecrawl/pdf-inspector';

const result = processPdf(readFileSync('document.pdf'));
console.log(result.pdfType);   // "TextBased", "Scanned", "ImageBased", "Mixed"
console.log(result.markdown);  // Markdown string or null

Full API reference: napi/README.md

Browser WebAssembly

npm install @firecrawl/pdf-inspector-wasm

import init, { processPdf } from '@firecrawl/pdf-inspector-wasm';

await init();
const response = await fetch('/document.pdf');
const pdf = new Uint8Array(await response.arrayBuffer());
const result = processPdf(pdf);

console.log(result.pdfType);
console.log(result.markdown);

Full API reference: wasm/README.md

Rust

Install from crates.io:

cargo add pdf-inspector

Or add it manually:

[dependencies]
pdf-inspector = "1"

use pdf_inspector::process_pdf;

let result = process_pdf("document.pdf")?;
println!("Type: {:?}", result.pdf_type);
if let Some(markdown) = &result.markdown {
    println!("{}", markdown);
}

Full API reference: docs/rust-api.md

CLI

# Install the CLI tools
cargo install pdf-inspector

# Convert PDF to Markdown
pdf2md document.pdf

# JSON output (for piping)
pdf2md document.pdf --json

# Positioned TextItem JSON, including is_underline metadata
pdf2md document.pdf --items-json

# Raw markdown only (no headers)
pdf2md document.pdf --raw

# Token-efficient output (collapses long dot leaders and similar source padding)
pdf2md document.pdf --compact

# Insert page break markers (<!-- Page N -->)
pdf2md document.pdf --pages

# Process only specific pages
pdf2md document.pdf --select-pages 1,3,5-10

# Detection only (no extraction)
detect-pdf document.pdf
detect-pdf document.pdf --json

# Detection + layout analysis (tables, columns)
detect-pdf document.pdf --analyze --json

From a source checkout, use cargo run --bin pdf2md -- document.pdf or cargo run --bin detect-pdf -- document.pdf instead.

Architecture

PDF bytes
  │
  ├─► detector         → PdfType (TextBased / Scanned / ImageBased / Mixed)
  │
  └─► extractor
        ├─ fonts        → font widths, encodings
        ├─ content_stream → walk PDF operators → TextItems + PdfRects
        ├─ xobjects     → Form XObject text, image placeholders
        ├─ links        → hyperlinks, AcroForm fields
        └─ layout       → column detection → line grouping → reading order
              │
              ├─► tables
              │     ├─ detect_rects      → rectangle-based tables (union-find)
              │     ├─ detect_heuristic  → alignment-based tables
              │     ├─ grid              → column/row assignment → cells
              │     └─ format            → cells → Markdown table
              │
              └─► markdown
                    ├─ analysis     → font stats, heading tiers
                    ├─ preprocess   → merge headings, drop caps
                    ├─ convert      → line loop + table/image insertion
                    ├─ classify     → captions, lists, code
                    └─ postprocess  → cleanup → final Markdown

The document is loaded once via load_document_from_path / load_document_from_mem and shared between the detection and extraction stages, so there's no redundant parsing.

Project structure

src/
  lib.rs                — Public API, PdfOptions builder, convenience functions
  python.rs             — PyO3 Python bindings
  types.rs              — Shared types: TextItem, TextLine, PdfRect, ItemType
  text_utils.rs         — Character/text helpers (CJK, RTL, ligatures, bold/italic)
  process_mode.rs       — ProcessMode enum (DetectOnly, Analyze, Full)
  detector.rs           — Fast PDF type detection without full document load
  glyph_names.rs        — Adobe Glyph List → Unicode mapping
  tounicode.rs          — ToUnicode CMap parsing for CID-encoded text
  extractor/            — Text extraction pipeline
  tables/               — Table detection and formatting
  markdown/             — Markdown conversion and structure detection
  bin/                  — CLI tools (pdf2md, detect_pdf)
napi/                   — Node.js/Bun bindings (napi-rs)
wasm/                   — Browser bindings (wasm-bindgen)

How classification works

Parse the xref table and page tree (no full object load)
Select pages based on ScanStrategy (default: all pages with early exit)
Look for Tj/TJ (text operators) and Do (image operators) in content streams
Classify based on text operator presence across sampled pages

This detects 300+ page PDFs in milliseconds. The result includes pages_needing_ocr — a list of specific page numbers that lack text, enabling per-page OCR routing instead of all-or-nothing.

Scan strategies

Strategy	Behavior	Best for
`EarlyExit` (default)	Scan all pages, stop on first non-text page	Pipelines routing TextBased PDFs to fast extraction
`Full`	Scan all pages, no early exit	Accurate Mixed vs Scanned classification
`Sample(n)`	Sample `n` evenly distributed pages (first, last, middle)	Very large PDFs where speed matters more than precision
`Pages(vec)`	Only scan specific 1-indexed page numbers	When the caller knows which pages to check

Markdown output

The converter handles:

Element	How it's detected
Headings (H1-H4)	Font size tiers relative to body text, with 0.5pt clustering
Bold/italic	Font name patterns (Bold, Italic, Oblique)
Bullet lists	`•`, `-`, `*`, `○`, `●`, `◦` prefixes
Numbered lists	`1.`, `1)`, `(1)` patterns
Letter lists	`a.`, `a)`, `(a)` patterns
Code blocks	Monospace fonts (Courier, Consolas, Monaco, Menlo, Fira Code, JetBrains Mono) and keyword detection
Tables	Rectangle-based detection from PDF drawing ops + heuristic detection from text alignment
Financial tables	Token splitting for consolidated numeric values
Captions	"Figure", "Table", "Source:" prefix detection
Sub/superscript	Font size and Y-offset relative to baseline
URLs	Converted to Markdown links
Hyphenation	Rejoins words broken across lines
Page numbers	Filtered from output
Drop caps	Large initial letters merged with following text
Dot leaders	TOC-style dots collapsed to " ... "

Use case: smart PDF routing

pdf-inspector was built for pipelines that process PDFs at scale. Instead of sending every PDF through OCR:

PDF arrives
  → pdf-inspector classifies it (~20ms)
  → TextBased + high confidence?
      YES → extract locally (~150ms), done
      NO  → send to OCR service (2-10s)

This saves cost and latency for the majority of PDFs that are already text-based (reports, papers, invoices, legal docs).

Debugging

See docs/debugging.md for RUST_LOG environment variable usage.

License

MIT

TencentCloud/TencentDB-Agent-Memory

TencentDB Agent Memory is a team-level memory hub for AI Agents — turning conversations, docs, and code into four reusable memory assets (Chat Memory, Skill, LLM-Wiki, Code-Graph) that are governed, shared, and equipped across agents and frameworks.

Agents remember. Humans innovate.

Installation · What is it? · Team Play · Technical Implementation · Benchmark · Roadmap

English · 简体中文

Latest: Team Memory Beta is evolving quickly — install it and start exploring in minutes.

Installation

Start all three services in one go (memory-core + memory-hub + proxy):

git clone https://github.com/Tencent/TencentDB-Agent-Memory.git
cd TencentDB-Agent-Memory/deploy/global-images
cp .env.example .env
$EDITOR .env       # Fill in two sets of LLM parameters (memory group + proxy group)
./start-all.sh     # Launch everything with one command; when finished, it prints a one-liner you can paste directly into Claude

Open the panel: http://localhost:8125.

Complete installation documentation (standalone Memory Hub deployment, Proxy + Claude Code / CodeBuddy usage, stop and cleanup, port reference, etc.) is available in INSTALL.md (中文: INSTALL_CN.md).

Migrating data from an older version

If you're already on an older release (v1.x / v0.x) and want to bring your existing data over to v2.0.0+, we provide a migration tool:

See Data Migration Tool (v2 → v3) for full usage and flags. New installations can skip this.

What is TencentDB Agent Memory?

We started from a practical question: How do you reduce repetitive work when using Agents?

If project context has already been explained, it shouldn't need to be repeated in a new session. If documents have already been read, every Agent shouldn't have to start again from page one. A workflow that already works shouldn't have to be rediscovered next time.

Memory here means more than just "remembering conversations." Any information that helps the next Agent avoid reinventing the wheel should be saved, organized, and reused.

Existing information → Reusable memory assets → Fewer turns → Less rework → More stable results and higher efficiency

Let experience accumulate, flow, and pass on to the next Agent

Memory Hub for Agent teams closes the loop across the entire experience lifecycle: work produces assets, assets circulate through the team, and new members can load the team's save file on day one.

Automatic asset extraction: Extract Chat Memory and Skills from conversations and tasks; convert documents and code into Wiki and CodeGraph; then manage, review, and route them consistently.
Portable & multi-Agent compatible: Memory assets are decoupled from Agent frameworks — they can move across frameworks and be shared and maintained by multiple Agents and team members.
Cold-start friendly: Import existing documents, codebases, and Agent conversation sessions. New Agent teams can start from existing experience instead of learning from scratch.

🧠 A brain that remembers people and context

Chat Memory retains preferences, facts, decisions, and interaction history.
Each Agent automatically gets its own memory when created — no need to re-introduce yourself next time.
L0 Conversation → L1 Atom → L2 Scenario → L3 Persona — raw conversations are distilled layer by layer.

"Don't refactor the old auth module — mobile is still using it." — Context this costly shouldn't depend on humans repeating it every time.

⚡ A Skill library that accumulates expertise

After completing complex work, Agents can extract and manage reusable Skills from conversations and tool calls, and import them into the context of a designated Agent when needed.
A Skill isn't just a prompt snippet; it has versions, resource files, trigger boundaries, execution steps, and validation rules.
Personal Skills are private by default; after review, they can be shared with the team and assigned to other Agents.

Troubleshooting, code review, release checklists — learn it once, and the whole team can use it.

📖 A knowledge map that reads both docs and code

Wiki turns product docs, design specs, and ops runbooks into structured pages with a link graph. (Inspired by Karpathy's LLM knowledge base.)

CodeGraph indexes code symbols, files, call relationships, and impact paths.
Agents can search, read, inspect callers/callees, and perform impact analysis before modifying code.

Wiki keeps Agents from reading every file list before getting to work. CodeGraph doesn't just tell them "the code is here" — it tells them "changing this might affect those."

🛡️ A team memory panel controlled by humans

Create teams and Agents in Memory Hub; review, share, and equip memory assets.
Manage ownership, versions, status, visibility, usage counts, and Agent bindings in one place.
private belongs strictly to the Owner; team is visible to all team members; restricted grants precise access via User / Role / Agent ACLs.
Two role layers: global System Admin manages users and teams (creating teams, adding members) and can also use Wiki, CodeGraph, Skill, and other asset management features; Team-level roles include Admin (team manager) and Member (regular member), responsible for asset collaboration and access control within a team. Asset ownership is tracked via Owner — the Owner automatically has management permissions for their assets.

Cold Start: Load the Save File, Then Get to Work

Most Agents' first task is re-learning your project. TencentDB Agent Memory turns the learning cost you've already paid into a save file:

Specifically, these existing assets can be imported directly and processed automatically in the panel:

Codebases: Import existing repositories — CodeGraph automatically indexes symbols, files, call relationships, and impact paths.
Documents & files: Import relevant docs and files — Wiki automatically generates structured pages with a link graph.
Conversation sessions: Import past Agent conversation sessions — Skills and Chat Memory are automatically extracted as reusable assets.

Stop retraining every Agent. Give it the save file.

One Play Style: Build a Growing Agent Team for a One-Person Company

Open Memory Hub and create a team:

Tiny but Serious Inc.
├── 👤 You · Set goals / Make decisions
├── 🔭 Scout · Research / Find opportunities
├── 🛠 Builder · Write code / Build products
├── 🧪 Reviewer · Test / Find issues
└── 🧠 Agent Memory · Preserve the team's experience

You're not opening four disconnected chat windows — you're assembling a squad with different roles that can inherit the team's accumulated experience.

Recruit first, then equip

🔭 Scout
   ├── User interview Chat Memory
   ├── Market research Wiki
   └── Competitive analysis Skill

🛠 Builder
   ├── Product Wiki
   ├── Project CodeGraph
   └── Feature Delivery Skill

🧪 Reviewer
   ├── Historical incident Chat Memory
   ├── Project CodeGraph
   └── Release Checklist Skill

Different roles, different loadouts. Less noise — give each Agent the memory assets it actually needs to get work done.

The company can be tiny. Experience can compound forever.

Memory Assets, Not a Chat Log Warehouse

RAG answers "what can be found?" Team Memory also answers "who can use it, which version is valid, and which Agent should receive it."

	Chat History	Standard RAG	TencentDB Agent Memory
Cross-session user understanding	△	△	✅ Chat Memory
Distilled executable experience	—	—	✅ Skill
Document structure & relationships	—	△ Chunk retrieval	✅ Wiki + Link Graph
Code call graphs & impact scope	—	△ Text match	✅ CodeGraph
Ownership / Version / Status	—	—	✅
Team sharing & Agent loadout	—	—	✅
Private / Team / ACL	—	△	✅

Memory Hub Is Not a Display Board — It's a Control Panel

Play Style	What you do in the Hub
Team Up	Create teams, add people and Agents, define sharing boundaries
Asset Library	Browse, search, review, and manage Chat Memory, Skills, Wiki, and CodeGraph
Agent Loadout	Bind different memory assets to different Agents; adjust priority and usage mode
Knowledge Workshop	Build Wiki and CodeGraph; monitor processing status and asset metadata
Access Control	Switch between private, team, and ACL-based access; revoke sharing when needed

When you open an asset, what matters is not just "what it says," but also "where it came from, which version it is, who it's assigned to, and whether it's been used recently."

Every Loop Gains Experience

Memory doesn't run the Agent loop; it ensures the next iteration inherits the previous one's results: valuable interactions stay in Chat Memory, proven workflows are distilled into Skills, and document/code changes are updated through Wiki ingest and CodeGraph sync.

Without Memory, loops may just repeat faster. With inherited memory, each iteration has the chance to be better than the last.

One Agent Team: Shared Experience, Not Shared Privacy

New Chat Memory and Skills are private by default. Sharing is an explicit action, not a default leak.

Visibility	Semantics
`private`	Only the Owner can read — not even team admins
`team`	Team members can read; the Owner / Admin can manage
`restricted`	Precise access via User / Role / Agent ACL
`agent`	For targeted equipping of Agents within the same team

You can assign the "Release Skill" to the Release Agent, the "Architecture Wiki" to all development Agents, and CodeGraph to Coder and Reviewer.

Technical Implementation

TencentDB Agent Memory doesn't aim to "store everything." It solves three problems: what's worth keeping, who can use it, and how to retrieve less while retrieving the right things next time.

1. Memory isn't flat records — it grows in layers

Conversations are first saved as L0, then refined by an async pipeline into multiple levels of granularity:

Layer	What it stores	Primary use
L0 Conversation	Raw conversations with full context	Verify exact wording, timestamps, and sources
L1 Atom	Facts, preferences, constraints, and events extracted from conversations	Precise recall of actionable information
L2 Scenario	Knowledge blocks organized around projects or scenarios	Quickly restore a working context
L3 Core / Persona	Long-term profiles, stable patterns, and high-level cognition	Let Agents rapidly enter a user's and team's context

Both generation and retrieval are layered: normally, L2/L3 provide a quick context bootstrap; when specific facts are needed, BM25 + vector retrieval + RRF fall back to L1/L0. Results are further capped by item count, character budget, and timeout limits to prevent memory from overwhelming the context window.

2. Memory isn't a global prompt — it's the Agent's loadout

Chat Memory, Skills, Wiki, and CodeGraph are all registered uniformly as Memory Assets. Memory Hub uses Fixed Binding + ACL to determine which assets a given Agent can use: first narrow the permission scope by Team, User, Agent, and visibility, then retrieve based on the current query.

This lets teams share experience without exposing all their private information; switching Agents or frameworks only requires re-equipping, not retraining.

3. Knowledge isn't injected wholesale — it's called on demand

Documents are organized into searchable Wiki pages that support link-graph drill-down; codebases are indexed into CodeGraph assets containing files, symbols, and call relationships. Agents first discover capabilities via /v3/tools/list, then use /v3/tools/call to read relevant pages, source code, or impact paths.

This makes documents and code part of memory as well — but they remain available tools that only enter context when truly needed.

Benchmark

Benchmark	Without TencentDB Agent Memory	With it enabled	Relative improvement
PersonaMem	48%	76%	+59%

PersonaMem tests whether an Agent can correctly understand and apply user information after extended interactions.

Notes

Wiki and CodeGraph are built asynchronously; allow some processing time before they reach ready status.
CodeGraph currently prioritizes public HTTPS repositories; support for private repositories and SSH credentials is still being refined.
The Hub supports manual asset binding; fully automated memory routing is still under iteration.
TencentDB Agent Memory currently supports OpenClaw, Hermes, Claude Code, CodeBuddy, and SDK integration; broader cross-framework migration is on the roadmap.

Roadmap

Current release is v2.0.0. Next up (v2.0.1): zero-config cold start, faster Wiki generation, user/team custom prompts, Skill export, and Codex (IDE Plan mode) support.

👉 See the full plan in ROADMAP.md (中文: ROADMAP_CN.md).

Acknowledgements

TencentDB Agent Memory stands on the shoulders of the open-source community:

CodeGraph — our CodeGraph asset module uses code from this project. Its design of a pre-indexed code graph is the foundation of our implementation.
Hermes Agent (Nous Research) — our Skill asset management uses part of the Skill-related code from Hermes Agent and builds further optimizations base on it.
"LLM Wiki" by Andrej Karpathy — the idea of treating documentation as an LLM-maintained, incrementally growing knowledge artifact directly informed how our Wiki layer is built and kept up to date.

We are grateful to the authors and contributors of these projects.

Community & Contributing

We welcome contributions of all kinds — bug reports, feature suggestions, documentation fixes, benchmark reproductions, ecosystem integrations, or pull requests. Agent memory is far from settled, and we hope to build it together with the community.

🐞 Found a bug or have a question? Open an issue in GitHub Issues — we respond within 24 hours.
💡 Have an idea to share? Start a thread in GitHub Discussions.
🛠️ Want to contribute code? Please read CONTRIBUTING.md first.
💬 Want to chat with us? Join our Discord community and talk to the core developers directly.

Let the path the team has walked become the next Agent's starting line.

✨ Contributors

💡 Thanks to the following contributors building with us — you make TencentDB Agent Memory better.

If TencentDB Agent Memory has been helpful to you, please consider starring the project.
If you have any suggestions, feel free to open an issue for discussion.

Star History

MIT © TencentDB Agent Memory Team

semantica-agi/semantica

Graph-Native Infrastructure for Context and Accountable AI Systems

The Open Source Palantir for AI Agents

Ingest your enterprise data, extract what matters, build a Context Graph and knowledge graph (KG), and run graph analytics and causal reasoning over all of it, with full decision provenance baked in. Explainable, traceable, and trustworthy by design.

Decision Intelligence · Context Management · Deterministic Reasoning · Ontology Management · Knowledge Modeling · End-to-End Traceability

Open Source · Self-Hostable · Auditable · Governed · Zero Vendor Lock-In

Polyglot Graph Storage · RDF & LPG Support · W3C Standards · Interoperable

Built for High-Stakes, Regulated Domains

pip install semantica

Knowledge Explorer · Context Graphs · Reasoning Engine · Decision Intelligence · Ontology Hub

▶ Watch the full platform walkthrough

Most AI agents act without a trail. They store embeddings, not meaning: context that can't be explained, decisions that can't be audited. In lending, that gap is a compliance exposure, not an inconvenience: an underwriting agent's approval has to survive a regulator's "why" months later.

Semantica sits underneath your LLM, vector store, and agent framework as a deterministic infrastructure layer: no LLM required for graph construction, reasoning, or provenance.

Who it's for:

AI/ML platform teams shipping agents that make consequential decisions and need structured, queryable context built from fragmented raw data, not just a vector index
Data platform teams on Databricks or Snowflake who need to turn tables already sitting in Unity Catalog or a Snowflake warehouse into a governed, lineage-tracked knowledge graph, without exporting that data to a third-party SaaS first
Compliance, risk, and audit teams who need a straight answer to "why did the AI do that?" in a format a regulator will actually accept
Regulated enterprises (finance, healthcare, legal, government, defense) that can't ship a black box, and can't send their data to someone else's SaaS to get one
Platform and infra engineers who want the KG, reasoning, and provenance stack self-hosted and swappable, not locked to one vendor's backend
Data and knowledge engineers building a KG from messy, multi-source data: entities and relationships get extracted, conflicting or contradictory facts are flagged instead of silently overwritten, and duplicates are merged before they turn into noise

Quick Start · Architecture · What You Get · Why Semantica · Decision Intelligence · Context Graphs · Recipe: Audit Trail · Module Reference · Integrations · CLI · Performance · Install

What Semantica Gives You

Context Graphs: A structured, queryable graph of everything your agent knows, decides, and reasons about
Decision Intelligence: Every decision is a first-class object: traceable, searchable by precedent, and causally linked
AI Governance & Ontology: SHACL constraints, conflict detection, compliance rules, OWL generation, and SKOS vocabulary management with a visual editor
Full Auditability: W3C PROV-O provenance on every fact, with audit trails exportable to JSON, CSV, or RDF
Deterministic Reasoning: Forward chaining, Rete network, Datalog, and SPARQL with fully explainable paths, not black boxes
Knowledge Pipeline: Multi-source ingestion, entity-aware chunking, NER/relation/event extraction, and knowledge graph construction, with semantic deduplication and provenance-preserving merges throughout
Enterprise Data Platforms: Native connectors for Databricks (Unity Catalog + Delta Lake, PAT/OAuth M2M auth, catalog/schema/table/lineage introspection) and Snowflake (warehouse/database/schema, key-pair and OAuth auth), so tables already living in your lakehouse or warehouse become graph nodes with provenance, not another export/import hop
Graph Analytics: Centrality, community detection, link prediction, and shortest-path queries over the graph you just built
Polyglot Graph Storage: Native RDF (embedded Oxigraph, Blazegraph, Apache Jena, Eclipse RDF4J via SPARQL) and Labeled Property Graphs (Neo4j, FalkorDB, Apache AGE, AWS Neptune via Cypher), plus vector stores, all swappable without touching your code
Visualization: Explore any graph, ontology, or timeline in an interactive browser workbench
Drop-in Integrations: Native Agno support, a full-featured MCP server, a comprehensive CLI, a REST API, and plugins across major editors

Why Semantica

	Vector DB + RAG	Plain LLM Memory	Semantica
Recall method	Embedding similarity	Token window	Graph traversal + semantic search
Decision history	Not stored	Not stored	First-class queryable objects
Provenance	None	None	W3C PROV-O, source-linked
Reasoning	None	Black box	Forward chain, Rete, Datalog, SPARQL
Conflict detection	Silent overwrite	Silent overwrite	Detected, flagged, resolved
Time travel	No	No	Point-in-time graph snapshots
Compliance export	None	None	PROV-O, SHACL, OWL, RDF
Policy enforcement	None	None	Built-in rule engine + SHACL
Entity resolution	No	No	Blocking + semantic deduplication
Multi-agent context	Separate per agent	Separate per agent	Single shared intelligence layer

Semantica complements your existing stack rather than replacing it. Keep your LLM, vector store, and agent framework exactly as they are; Semantica adds the decision records, causal reasoning, provenance, ontology governance, conflict detection, and audit trails on top. The reasoning engines, KG construction, and provenance layer are fully deterministic; no LLM is required to use them.

Quick Start

pip install semantica

from semantica.context import ContextGraph

graph = ContextGraph(advanced_analytics=True)

# Every agent decision becomes a queryable, auditable knowledge node
decision_id = graph.record_decision(
    category="vendor_selection",
    scenario="Choose cloud provider for HIPAA workload",
    reasoning="AWS offers BAA, mature HIPAA tooling, and existing team expertise",
    outcome="selected_aws",
    confidence=0.93,
)

# Ask "why did this happen?" and get a real, structured answer
chain     = graph.trace_decision_chain(decision_id)       # full causal ancestry
similar   = graph.find_similar_decisions("cloud vendor", max_results=5)  # precedents
impact    = graph.analyze_decision_impact(decision_id)    # downstream influence map
compliant = graph.check_decision_rules({"category": "vendor_selection"})  # policy gate

Verify your install in 5 seconds:

semantica doctor
# Python 3.11.9         pass
# semantica 0.6.5       pass
# faiss vector store    pass
# Config file           pass    ~/.semantica/config.yaml

If Semantica solves a real problem for you, a star helps others find it.

⭐ Star on GitHub · Join Discord

Architecture

Semantica is a real end-to-end pipeline, not a single library with a marketing name. Every stage below is a shipping module, independently importable:

Sources → Ingest → Parse → Normalize → Split → Extract → Conflict Detection → Deduplication
   → Knowledge Graph → [ Ontology · Reasoning · Provenance · Decisions ] → Enriched KG
   → Vector Store + Polyglot Graph Store (RDF & LPG) → Export / Visualize / REST · MCP · CLI

Ingest: files, web, databases, enterprise data platforms (Databricks, Snowflake), cloud (Google Drive, Elasticsearch), streams (Kafka, Kinesis), Git, email, MCP
Parse → Normalize → Split: document parsing, text/entity/date normalization, GraphRAG-native entity-aware chunking
Extract → Conflict Detection → Deduplication: NER, relations, events, triplets; conflicting facts flagged and resolved before they merge
Knowledge Graph: GraphBuilder constructs the graph; bi-temporal facts and full graph analytics (centrality, communities, link prediction) run on top of it
Ontology · Reasoning · Provenance · Decisions: the intelligence layer sitting on the KG, with SHACL/OWL governance, Rete/Datalog/SPARQL inference, W3C PROV-O lineage, and first-class decision records
Storage: polyglot by design, with RDF triple stores (embedded Oxigraph, Blazegraph, Apache Jena, Eclipse RDF4J), Labeled Property Graphs (Neo4j, FalkorDB, Apache AGE, AWS Neptune), and vector stores, all swappable without touching your code
Outputs: export (RDF, OWL, Parquet, Cypher, JSON-LD), interactive visualization, and access via REST API, MCP server, or CLI

→ Full Mermaid diagrams for the pipeline and the decision intelligence lifecycle

Decision Intelligence

Decision Intelligence turns every AI choice from an ephemeral inference into a permanent, auditable, queryable record. It answers "what did your AI decide, why, and what happened next?": the question regulators and enterprise risk teams ask with increasing urgency.

In Semantica, a decision is not a log line. It is a first-class graph node with a full lifecycle. In regulated domains, every AI decision must be traceable to a source and defensible to an auditor: record_decision() creates a permanent, structured record exportable as W3C PROV-O, the format most compliance frameworks accept for regulator submission.

record_decision()             → stored as a graph node with full structured context
add_causal_relationship()     → linked to upstream causes and downstream effects
find_similar_decisions()      → semantic precedent search across all past decisions
trace_decision_chain()        → full causal ancestry back to root causes
analyze_decision_impact()     → downstream influence map - everything this decision affected
check_decision_rules()        → policy compliance gate against configurable rule sets
export / audit trail          → W3C PROV-O, CSV, or JSON for regulator submission

from semantica.context import ContextGraph

graph = ContextGraph(advanced_analytics=True)

# Record decisions with full structured context
app_id = graph.record_decision(
    category="credit_application",
    scenario="Personal loan, $85k income, 31% DTI, 3yr employment",
    reasoning="Income meets threshold; employment stable; no adverse credit events",
    outcome="proceed_to_underwriting",
    confidence=0.88,
    metadata={"applicant_id": "A-7291"},
)
uw_id = graph.record_decision(
    category="loan_underwriting",
    scenario="Underwriting review for A-7291",
    reasoning="DTI within policy; clean 36-month credit history",
    outcome="approved",
    confidence=0.94,
)
rate_id = graph.record_decision(
    category="interest_rate",
    scenario="Rate assignment for approved loan A-7291",
    outcome="rate_set_8.9pct",
    reasoning="Prime + 2.4% based on risk tier B2",
    confidence=0.99,
)

# Build the auditable causal chain - relationship_type must be one of
# CAUSED, INFLUENCED, or PRECEDENT_FOR
graph.add_causal_relationship(app_id, uw_id,   relationship_type="CAUSED")
graph.add_causal_relationship(uw_id,  rate_id, relationship_type="INFLUENCED")

# Query the intelligence
chain     = graph.trace_decision_chain(rate_id)
similar   = graph.find_similar_decisions("personal loan approval, 31% DTI", max_results=5)
impact    = graph.analyze_decision_impact(uw_id)
compliant = graph.check_decision_rules({"category": "loan_underwriting", "confidence": 0.94})
insights  = graph.get_decision_insights()

Context Graphs

A Context Graph is the structured memory layer that traditional RAG is missing. Instead of flat embeddings that answer "what is similar?", a Context Graph answers "what is connected, why, and how?" Every entity, relationship, decision, and fact is a first-class node, queryable by graph traversal. Entities link to source documents, decisions link to evidence and consequences, facts carry full provenance, and conflicts are detected, not silently overwritten.

from semantica.context import ContextGraph, AgentContext
from semantica.vector_store import VectorStore

graph = ContextGraph(advanced_analytics=True)

# Add nodes with typed properties
graph.add_node("acme_corp",    "Organization", name="Acme Corp", industry="SaaS")
graph.add_node("alice_chen",   "Person",       name="Alice Chen", role="CTO")
graph.add_node("contract_001", "Contract",     value=2_400_000, currency="USD")

# Add typed, weighted edges (extra kwargs become edge metadata)
graph.add_edge("alice_chen", "acme_corp",    edge_type="works_for",  since="2019-03-01")
graph.add_edge("acme_corp",  "contract_001", edge_type="party_to",   signed="2024-01-15")

# BFS traversal - hop through the graph from any node
neighbors = graph.get_neighbors("acme_corp", hops=2)

# Point-in-time snapshot - the graph as it existed on any past date
snapshot  = graph.state_at("2024-01-01")

# AgentContext - high-level API for agent memory workflows
vs  = VectorStore(backend="faiss")
ctx = AgentContext(vector_store=vs, knowledge_graph=graph)
ctx.store("Alice approved the Acme renewal in Q1 2024", conversation_id="conv_001")
retrieved = ctx.retrieve("who approved the Acme contract?")

Why graph over embeddings: traversal finds connections embeddings miss (a person 3 hops from a contract); every node carries provenance so you can always ask "where did this come from?"; conflicts are flagged before they corrupt your knowledge base; point-in-time snapshots let you replay history without reprocessing.

Recipe: Audit Trail for a Regulated Decision

The flagship pattern: record a causally-linked decision chain, attach provenance to every entity, and export a regulator-ready audit trail.

from semantica.context import ContextGraph
from semantica.provenance import ProvenanceManager
from semantica.export import RDFExporter

graph = ContextGraph(advanced_analytics=True)
prov  = ProvenanceManager(storage_path="./audit.db")

# Record the decision chain
d1 = graph.record_decision(
    category="drug_interaction_check", scenario="Patient P-4821: warfarin + amiodarone co-prescribed",
    reasoning="Amiodarone potentiates warfarin's anticoagulant effect", outcome="flag_for_review", confidence=0.91,
)
d2 = graph.record_decision(
    category="dosage_adjustment", scenario="INR monitoring plan for P-4821",
    reasoning="Reduce warfarin dose per interaction severity; recheck INR in 5 days", outcome="dose_reduced_30pct", confidence=0.87,
)
# relationship_type must be one of CAUSED, INFLUENCED, or PRECEDENT_FOR
graph.add_causal_relationship(d1, d2, relationship_type="CAUSED")

# Track provenance for every entity
prov.track_entity("patient_P4821", source="ehr/medication_orders_2024.json",
                  metadata={"extractor": "NamedEntityRecognizer"})

# Export W3C PROV-O for regulator submission - RDFExporter expects
# {"entities": [...], "relationships": [...]}, so map ContextGraph.to_dict()'s
# {"nodes": [...], "edges": [...]} shape onto it first
graph_dict = graph.to_dict()
kg = {
    "entities": [{"id": n["id"], "type": n["type"], "text": n["content"]} for n in graph_dict["nodes"]],
    "relationships": [
        {"source_id": e["source"], "target_id": e["target"], "type": e["type"]}
        for e in graph_dict["edges"]
    ],
}
RDFExporter().export(kg, "audit_trail.ttl", format="turtle")

More recipes (GraphRAG pipelines, an AML rules engine, ontology-to-KG in one pass) are in More Recipes below.

Explore the Platform

Every module below is independently importable, with working code samples verified against the current source tree; use one or all of them.

Module	What it does
`semantica.ingest`	Files, web, databases, APIs, streams, email, Git, Parquet, Databricks, Snowflake, MCP
`semantica.semantic_extract`	NER, relation extraction, event detection, triplet generation
`semantica.kg`	Graph construction, centrality, communities, link prediction
`semantica.reasoning`	Forward chaining, Rete, Datalog, SPARQL, fully explainable
`semantica.vector_store`	FAISS, Qdrant, Weaviate, Milvus, Pinecone, PgVector, hybrid search
`semantica.split`	Entity-aware, relation-aware, ontology-aware chunking for GraphRAG
`semantica.provenance`	W3C PROV-O lineage on every fact
`semantica.ontology`	OWL generation, SHACL validation, SKOS vocabularies
`semantica.conflicts`	Detect and resolve conflicting facts across sources
`semantica.deduplication`	Entity resolution at scale
`semantica.normalize`	Text, entity, date, and number normalization; dataset cleaning
`semantica.pipeline`	Declarative, parallel pipeline DSL for ingest → extract → build → export
`semantica.export`	RDF, OWL, Parquet, Cypher, JSON-LD
`semantica.visualization`	Force-directed graphs, ontology hierarchies, temporal dashboards
Temporal Intelligence	Bi-temporal facts, Allen interval algebra, time travel
Multi-Agent (Agno)	One shared context graph across every agent on a team

↓ Expand Module Reference below for every module's working example, or jump to More Recipes, the full Integrations matrix, MCP tool list, and REST endpoints.

Module Reference

Expand any module below for its runnable example.

semantica.ingest: Multi-Source Ingestion

Ingest from files, web, databases, APIs, streams, email, Git repos, Parquet, Databricks, Snowflake, or MCP servers, all through a unified interface.

from semantica.ingest import FileIngestor, WebIngestor, ParquetIngestor, DBIngestor

# Ingest an entire directory of contracts (PDF, DOCX, HTML, TXT)
docs = FileIngestor().ingest_directory("./contracts/", recursive=True)

# Ingest live web content with robots.txt compliance
pages = WebIngestor().ingest_url("https://example.com/reports/annual-2024.html")

# Ingest structured data from Parquet with Snappy compression
records = ParquetIngestor().ingest("./data/transactions.parquet")

# Ingest from a SQL database - specify which tables to pull
rows = DBIngestor().ingest_database(
    connection_string="postgresql://user:pass@localhost/mydb",
    include_tables=["customer_events"],
    max_rows_per_table=50_000,
)

# Enterprise data platforms - pull tables straight out of your lakehouse
# or warehouse, with lineage, instead of exporting to CSV first
from semantica.ingest import DatabricksIngestor, SnowflakeIngestor

# pip install "semantica[db-databricks]"
databricks = DatabricksIngestor(
    host="https://adb-xxx.azuredatabricks.net",
    token="dapi-xxxxxxxx",              # or client_id/client_secret for OAuth M2M
    http_path="/sql/1.0/warehouses/xxxxxxxx",
    catalog="main",
)
customers    = databricks.ingest_table("customers", limit=10_000)
sales        = databricks.ingest_query("SELECT * FROM sales WHERE region = 'EMEA'")
table_lineage = databricks.get_table_lineage("customers", catalog="main", schema="default")  # Unity Catalog lineage

# pip install semantica[db-snowflake]
snowflake = SnowflakeIngestor(
    account="myaccount",
    user="myuser",
    password="mypassword",              # or private_key=... for key-pair; use authenticator="oauth", token=... for OAuth
    warehouse="COMPUTE_WH",
    database="MYDB",
)
orders = snowflake.ingest_table("ORDERS", limit=10_000)

Security Note: Never hardcode credentials (token, password, private_key) in production code; pass them via environment variables (e.g., DATABRICKS_TOKEN, SNOWFLAKE_PASSWORD) or a secrets manager.

Supported sources: Local files (PDF, DOCX, PPTX, HTML, TXT, CSV, JSON, YAML, Excel, XML) · Web pages · RSS/Atom feeds · REST APIs · Databases (PostgreSQL, MySQL, SQLite, Oracle, SQL Server) · Parquet datasets · Databricks (Unity Catalog + Delta Lake) · Snowflake · Git repositories · Email (IMAP/POP3) · Message streams (Kafka, RabbitMQ, Kinesis, Pulsar) · MCP resources · Apache Arrow/Feather/IPC (ArrowIngestor)

DuckDB, Elasticsearch, Google Drive, HuggingFace, MongoDB, and Pandas ingestion also ship (DuckDBIngestor, ElasticIngestor, GDriveIngestor, HuggingFaceIngestor, MongoIngestor, PandasIngestor) but aren't re-exported from the top-level semantica.ingest namespace yet — import them directly: from semantica.ingest.duckdb_ingestor import DuckDBIngestor.

semantica.semantic_extract: NER, Relations, Events, Triplets

Extract structured knowledge from raw text in one pass.

from semantica.semantic_extract import (
    NamedEntityRecognizer,
    RelationExtractor,
    EventDetector,
    TripletExtractor,
)

text = """
Anthropic CEO Dario Amodei announced a $7.3B Series E funding round in partnership
with Google and Spark Capital, valuing the company at $61.5B as of Q4 2024.
"""

# Named entity recognition with confidence thresholding
ner = NamedEntityRecognizer(confidence_threshold=0.7)
entities = ner.extract_entities(text)
# → [Entity(name="Dario Amodei", type="PERSON"), Entity(name="Anthropic", type="ORG"),
#    Entity(name="Google", type="ORG"), Entity(name="$7.3B", type="MONEY"), ...]

# Relationship extraction - bidirectional support
rel_extractor = RelationExtractor(confidence_threshold=0.6, bidirectional=True)
relations = rel_extractor.extract_relations(text, entities=entities)
# → [Relation(subject="Dario Amodei", predicate="ceo_of", object="Anthropic"),
#    Relation(subject="Anthropic", predicate="raised", object="$7.3B Series E"), ...]

# Event detection with temporal processing
events = EventDetector(extract_participants=True, extract_time=True).detect_events(text)
# → [Event(type="FUNDING", participants=["Anthropic","Google","Spark Capital"],
#          amount="$7.3B", date="Q4 2024")]

# RDF triplets with optional provenance metadata
triplets = TripletExtractor(include_temporal=True, include_provenance=True).extract_triplets(text)
# → [("Anthropic", "valuation", "$61.5B"), ("Dario Amodei", "is_ceo_of", "Anthropic"), ...]

Batch processing across many documents uses ner.process_batch([...]), not a per-call extract_entities_batch on the facade class.

semantica.kg: Knowledge Graph Construction & Analysis

Build a production knowledge graph from documents and run graph algorithms over it.

from semantica.ingest import FileIngestor
from semantica.kg import (
    GraphBuilder,
    GraphAnalyzer,
    CentralityCalculator,
    CommunityDetector,
    PathFinder,
    LinkPredictor,
    BiTemporalFact,
)
from datetime import datetime

# Build KG - merge duplicate entities, track temporal edges
sources = FileIngestor().ingest_directory("./contracts/", recursive=True)
kg = GraphBuilder(merge_entities=True, enable_temporal=True).build(sources)

# Graph analytics
analyzer    = GraphAnalyzer()
analysis    = analyzer.analyze_graph(kg)             # full graph metrics

centrality  = CentralityCalculator()
degree      = centrality.calculate_degree_centrality(kg)    # most-connected entities
betweenness = centrality.calculate_betweenness_centrality(kg)

communities = CommunityDetector().detect_communities(kg, method="louvain")  # natural clusters
path        = PathFinder().find_shortest_path(kg, "alice_chen", "contract_001")
predictions = LinkPredictor().predict_links(kg, top_k=10)   # relationship predictions

# Bi-temporal facts - track valid time vs. recorded time independently
fact = BiTemporalFact(
    valid_from=datetime(2024, 3, 1),
    valid_until=datetime(2025, 1, 1),
    recorded_at=datetime(2024, 3, 5),
)

semantica.reasoning: Forward Chaining, Rete, Datalog, SPARQL

Run explainable rule-based inference, not a black box.

from semantica.reasoning import ReteEngine, Rule, Fact, RuleType

rete = ReteEngine()
rete.build_network([
    Rule(
        rule_id="aml_flag",
        name="Flag high-risk transactions",
        conditions=[
            {"field": "amount",  "operator": ">",  "value": 10_000},
            {"field": "country", "operator": "in", "value": ["IR", "KP", "SY"]},
        ],
        conclusion="flag_for_compliance_review",
        rule_type=RuleType.IMPLICATION,
    ),
    Rule(
        rule_id="velocity_check",
        name="Flag rapid sequential transfers",
        conditions=[
            {"field": "transfers_in_1h", "operator": ">", "value": 5},
            {"field": "total_amount",    "operator": ">", "value": 50_000},
        ],
        conclusion="flag_velocity_breach",
        rule_type=RuleType.IMPLICATION,
    ),
])

rete.add_fact(Fact("tx_001", "transaction", [{"amount": 15_000, "country": "IR"}]))
flagged = rete.match_patterns()
# → [{"rule": "aml_flag", "matched_facts": ["tx_001"], "conclusion": "flag_for_compliance_review"}]

Current limitation: ReteEngine's alpha-node condition matcher is intentionally simple in this release — validate match_patterns() output against your actual rule set before wiring it into a production compliance gate; more selective condition evaluation is on the roadmap.

# Recursive Datalog - natural language for graph queries
from semantica.reasoning import DatalogReasoner

engine = DatalogReasoner()
engine.add_fact("parent(tom, bob)")
engine.add_fact("parent(bob, ann)")
engine.add_fact("parent(ann, pat)")
engine.add_rule("ancestor(X, Y) :- parent(X, Y).")
engine.add_rule("ancestor(X, Z) :- parent(X, Y), ancestor(Y, Z).")
ancestors = engine.query("ancestor(tom, ?X)")
# → [{"X": "bob"}, {"X": "ann"}, {"X": "pat"}]

# Explainable reasoning - trace the path, not just the answer
from semantica.reasoning import ExplanationGenerator, Reasoner

reasoner = Reasoner()
reasoner.add_fact("parent(tom, bob)")
reasoner.add_rule("ancestor(X, Y) :- parent(X, Y)")
result = reasoner.forward_chain()

explainer = ExplanationGenerator()
explanation = explainer.generate_explanation(result)
# → Explanation(conclusion="...", steps=[ReasoningStep(...)], justification=Justification(...))

semantica.vector_store: Hybrid & Filtered Semantic Search

Drop-in vector store with multiple backends, hybrid search, and decision-aware retrieval.

from semantica.vector_store import VectorStore, HybridSearch

# In-memory backend shown here: HybridSearch and explain_decision() work out of the box.
# Swap backend="qdrant" / "weaviate" / "milvus" / "pinecone" / "pgvector" / "faiss" once you
# scale past a single process — search() and store_decision() work identically on all of them.
vs = VectorStore(backend="inmemory", dimension=1536)

# Store a decision with scenario description and outcome
vs.store_decision(
    scenario="Personal loan A-7291, $85k income, 31% DTI, 3yr employment",
    outcome="approved",
    confidence=0.94,
    category="loan_underwriting",
)

# Semantic similarity search
results = vs.search(
    query="personal loan approval with low DTI",
    limit=10,
)

# Hybrid search - dense + sparse retrieval in one pass with RRF fusion
hs   = HybridSearch(vector_store=vs)
hits = hs.search("high-risk transactions 2024")

# Explain why a decision was retrieved
explanation = vs.explain_decision(results[0]["id"])

Backends: faiss · qdrant · weaviate · milvus · pinecone · pgvector · sqlite · inmemory

semantica.split: GraphRAG-Native Document Chunking

KG-aware splitting that preserves entity boundaries, relation triplets, and ontology concepts, essential for GraphRAG pipelines.

from semantica.split import TextSplitter, EntityAwareChunker, RelationAwareChunker

text = open("contracts/master_agreement.txt").read()

# Standard recursive chunking
chunks = TextSplitter(method="recursive", chunk_size=1000, chunk_overlap=200).split(text)

# Entity-aware chunking - never splits a named entity across chunks (GraphRAG)
chunks = TextSplitter(method="entity_aware", ner_method="llm", chunk_size=1000).split(text)

# Relation-aware chunking - preserves (subject, predicate, object) triplets intact
chunks = RelationAwareChunker(chunk_size=1000, preserve_triplets=True).chunk(text)

# Graph-based chunking - uses centrality to find natural community boundaries
chunks = TextSplitter(method="graph_based", chunk_size=1000).split(text)

# Hierarchical chunking - multi-level (section → paragraph → sentence)
chunks = TextSplitter(method="hierarchical", levels=["section", "paragraph"]).split(text)

Supported methods: recursive · token · sentence · paragraph · semantic_transformer · entity_aware · relation_aware · graph_based · ontology_aware · hierarchical · community_detection · centrality_based · llm

semantica.provenance: W3C PROV-O Lineage

Every fact is linked to its source. No black boxes, no mystery outputs.

from semantica.provenance import ProvenanceManager

prov = ProvenanceManager(storage_path="./provenance.db")

# Track where every entity came from
prov.track_entity(
    entity_id="acme_corp",
    source="contracts/acme_master_agreement_2024.pdf",
    metadata={"page": 1, "confidence": 0.97, "extractor": "NamedEntityRecognizer"},
)

# Track a relationship's provenance - entity linkage travels in metadata
prov.track_relationship(
    relationship_id="alice_works_for_acme",
    source="hr_records/employees_q1_2024.csv",
    metadata={"source_entity_id": "alice_chen", "target_entity_id": "acme_corp"},
)

# Answer "where did this come from?"
lineage = prov.get_lineage("acme_corp")
trail   = prov.trace_lineage("alice_chen")   # full ancestor chain
entry   = prov.get_provenance("acme_corp")

semantica.ontology: OWL Generation, SHACL Validation

Generate ontologies from data, validate shapes, and manage your vocabulary.

from semantica.ontology import OntologyGenerator, OntologyValidator

data = {
    "entities": [
        {"id": "acme_corp",  "type": "Organization", "industry": "SaaS", "founded": 2012},
        {"id": "alice_chen", "type": "Person",        "role": "CTO",     "since": 2019},
    ],
    "relationships": [
        {"source": "alice_chen", "target": "acme_corp", "type": "works_for"},
    ],
}

gen       = OntologyGenerator(base_uri="https://semantica.dev/ontology/")
ontology  = gen.generate_ontology(data)
classes   = gen.infer_classes(data)
props     = gen.infer_properties(data, classes)
optimized = gen.optimize_ontology(ontology)

# Validate against SHACL shapes
validator = OntologyValidator()
report    = validator.validate(ontology)
# → ValidationResult(valid=True, consistent=True, satisfiable=True, errors=[], warnings=[])

semantica.conflicts: Conflict Detection & Resolution

Detect and resolve conflicting facts from multiple sources before they corrupt your knowledge base.

from semantica.conflicts import ConflictDetector, ConflictResolver, SourceTracker

entities_from_source_a = [
    {"id": "alice_chen", "role": "CTO",   "salary": 250_000, "start_date": "2019-03-01"},
]
entities_from_source_b = [
    {"id": "alice_chen", "role": "VP Eng", "salary": 275_000, "start_date": "2019-03-01"},
]

# Detect all conflict types: value, type, relationship, temporal, logical
detector   = ConflictDetector()
conflicts  = detector.detect_conflicts(entities_from_source_a + entities_from_source_b)
# → [Conflict(entity="alice_chen", field="role",   values=["CTO","VP Eng"], severity="HIGH"),
#    Conflict(entity="alice_chen", field="salary",  values=[250000,275000],   severity="MEDIUM")]

# Resolve using multiple strategies
resolver = ConflictResolver()
resolved = resolver.resolve_conflicts(conflicts, strategy="credibility_weighted")  # weighted by source trust
resolved = resolver.resolve_conflicts(conflicts, strategy="most_recent")          # prefer most recent
resolved = resolver.resolve_conflicts(conflicts, strategy="voting")               # majority wins

# Track source credibility over time
tracker = SourceTracker()
tracker.register_source("source_a", source_type="document", credibility_score=0.85)
tracker.register_source("source_b", source_type="document", credibility_score=0.72)

semantica.deduplication: Entity Resolution at Scale

Block, cluster, and merge duplicates with semantic similarity.

from semantica.deduplication import DuplicateDetector, EntityMerger

entities = [
    {"id": "e1", "name": "Acme Corporation",  "domain": "acme.com"},
    {"id": "e2", "name": "Acme Corp.",         "domain": "acme.com"},
    {"id": "e3", "name": "ACME Corp",          "domain": "acme.co"},
    {"id": "e4", "name": "Globex Industries",  "domain": "globex.com"},
]

detector   = DuplicateDetector(similarity_threshold=0.75, use_clustering=True)
candidates = detector.detect_duplicates(entities)
groups     = detector.detect_duplicate_groups(entities)
# → DuplicateGroup(entities=["e1","e2","e3"], confidence=0.91, strategy="semantic+blocking")

merger  = EntityMerger(preserve_provenance=True)
ops     = merger.merge_duplicates(entities, strategy="keep_most_complete")
history = merger.get_merge_history()

semantica.normalize: Data Normalization & Cleaning

Standardize text, entities, dates, numbers, and encodings before building your knowledge graph.

from semantica.normalize import (
    TextNormalizer,
    EntityNormalizer,
    DateNormalizer,
    NumberNormalizer,
    DataCleaner,
)

# Unicode, whitespace, casing, HTML tags, smart quotes
text  = TextNormalizer().normalize("  Acme Corp.'s Q4 report...  ")
# → "Acme Corp.'s Q4 report..."

# Alias resolution + entity disambiguation with confidence scores
canonical = EntityNormalizer().normalize_entity("ACME Corp.")
# → NormalizedEntity(canonical="Acme Corporation", type="Organization", confidence=0.91)

# Natural language date parsing with timezone conversion
dt    = DateNormalizer().normalize_date("3 weeks ago")
# → datetime(2026, 7, 1, tzinfo=UTC)

# Unit conversion and currency normalization
price = NumberNormalizer().normalize_number("$1.25M USD")
# → NormalizedNumber(value=1_250_000, currency="USD")

# Deduplicate, validate, and impute missing values across a dataset
clean = DataCleaner().clean_data(records, remove_duplicates=True, handle_missing=True)

semantica.pipeline: Pipeline DSL

Compose ingestion, extraction, and graph-building into a declarative, parallel pipeline.

from semantica.pipeline import PipelineBuilder, ExecutionEngine

builder = PipelineBuilder()

# add_step() returns the created PipelineStep, not the builder, so these don't chain
builder.add_step("ingest",      step_type="ingest",           source="./contracts/", recursive=True)
builder.add_step("extract",     step_type="ner_extract")
builder.add_step("relations",   step_type="relation_extract")
builder.add_step("build_kg",    step_type="kg_build",         merge_entities=True)
builder.add_step("deduplicate", step_type="deduplicate",      threshold=0.75)
builder.add_step("export",      step_type="export",           format="turtle", output="kg.ttl")

# connect_steps() and set_parallelism() return the builder, so these do chain
pipeline = (
    builder
    .connect_steps("ingest",      "extract")
    .connect_steps("extract",     "relations")
    .connect_steps("relations",   "build_kg")
    .connect_steps("build_kg",    "deduplicate")
    .connect_steps("deduplicate", "export")
    .set_parallelism(4)
    .build(name="contracts_pipeline")
)

engine   = ExecutionEngine()
result   = engine.execute_pipeline(pipeline)
status   = engine.get_pipeline_status(pipeline.name)
progress = engine.get_progress(pipeline.name)

Temporal Intelligence: Bi-Temporal Graphs & Time Travel

Track when facts were true in the world vs. when they were recorded, and query either axis.

from semantica.context import ContextGraph
from semantica.kg import (
    BiTemporalFact,
    TemporalGraphQuery,
    TemporalNormalizer,
)
from datetime import datetime

graph = ContextGraph(advanced_analytics=True)
graph.add_node("alice_chen", "Person",       role="VP Engineering")
graph.add_node("acme_corp",  "Organization", valuation=1_200_000_000)

# A temporally-bounded edge - valid_from/valid_until define when it held true
graph.add_edge(
    "alice_chen", "acme_corp", edge_type="works_for",
    valid_from="2024-03-01T00:00:00", valid_until="2025-01-01T00:00:00",
)

# Point-in-time snapshots - replay history without reprocessing
snapshot_2023 = graph.state_at("2023-06-01")
snapshot_2024 = graph.state_at("2024-01-01")

# Bi-temporal facts - valid_time is when true in the world;
# recorded_at is when you learned about it
fact = BiTemporalFact(
    valid_from=datetime(2024, 3, 1),
    valid_until=datetime(2025, 1, 1),
    recorded_at=datetime(2024, 3, 5),
)

# Query facts valid within a time window - query_time_range() expects
# {"relationships": [...]} with source_id/target_id keys, which differs from
# ContextGraph.to_dict()'s {"nodes", "edges"} shape, so map it first
graph_dict = graph.to_dict()
kg_relationships = {
    "relationships": [
        {**e, "source_id": e["source"], "target_id": e["target"]}
        for e in graph_dict["edges"]
    ]
}

tq = TemporalGraphQuery()
facts_in_window = tq.query_time_range(
    kg_relationships, query="valid_facts", start_time="2024-01-01", end_time="2024-12-31"
)

# Normalize natural language temporal expressions - returns a (start, end) range
norm = TemporalNormalizer()
start, end = norm.normalize("last quarter")

semantica.export: RDF, OWL, Parquet, Cypher, JSON-LD

Export to any format required by regulators, graph databases, or downstream systems.

from semantica.export import (
    RDFExporter,
    JSONExporter,
    ParquetExporter,
    LPGExporter,
    ReportGenerator,
)

kg = {"entities": [...], "relationships": [...]}

rdf = RDFExporter()
turtle_str = rdf.export_to_rdf(kg, format="turtle")     # returns string
jsonld_str = rdf.export_to_rdf(kg, format="json-ld")

rdf.export(kg, "kg_audit.ttl",    format="turtle")
rdf.export(kg, "kg_audit.jsonld", format="json-ld")
rdf.export(kg, "kg_audit.nt",     format="n-triples")

# Columnar analytics - Snappy-compressed Parquet (writes kg_snapshot_entities.parquet
# and kg_snapshot_relationships.parquet)
ParquetExporter(compression="snappy").export_knowledge_graph(kg, "kg_snapshot")

# JSON knowledge graph
JSONExporter().export_knowledge_graph(kg, "kg.json")

# Neo4j / Memgraph Cypher statements for graph database import
LPGExporter().export(kg, "kg_import.cypher")

# Human-readable HTML report
ReportGenerator().generate_report(
    {"title": "KG Audit Report", "summary": "Weekly ingestion summary", "metrics": {"entities": len(kg["entities"])}},
    file_path="audit_report.html",
    format="html",
)

semantica.visualization: Interactive Graph Workbench

Render force-directed graphs, community maps, ontology hierarchies, and temporal dashboards.

from semantica.visualization import (
    KGVisualizer,
    OntologyVisualizer,
    EmbeddingVisualizer,
    TemporalVisualizer,
)
import numpy as np

kg = {"entities": [...], "relationships": [...]}

# Interactive force-directed graph (opens in browser)
viz = KGVisualizer(layout="force", color_scheme="default")
viz.visualize_network(kg, output="interactive", file_path="kg.html")
viz.visualize_communities(kg, communities, output="interactive")
viz.visualize_centrality(kg, centrality, centrality_type="degree")
viz.visualize_entity_types(kg, output="html", file_path="entity_types.html")

# Ontology class hierarchy
OntologyVisualizer().visualize_hierarchy(ontology, output="interactive")

# 2D embedding projection (UMAP / t-SNE / PCA)
EmbeddingVisualizer().visualize_2d_projection(
    embeddings=np.array([...]),
    labels=["entity_a", "entity_b"],
    method="umap",
)

# Timeline scrubber - watch the graph evolve
TemporalVisualizer().visualize_timeline(kg, output="interactive")

Multi-Agent Shared Context with Agno

One shared intelligence layer. All agents read and write to the same context graph.

# pip install semantica[agno]
from agno.agent import Agent
from agno.team import Team
from agno.models.anthropic import Claude
from semantica.context import ContextGraph
from semantica.vector_store import VectorStore
from integrations.agno import AgnoSharedContext, AgnoDecisionKit, AgnoKGToolkit

shared = AgnoSharedContext(
    vector_store=VectorStore(backend="faiss"),
    knowledge_graph=ContextGraph(advanced_analytics=True),
    decision_tracking=True,
)

researcher = Agent(
    name="Researcher",
    model=Claude(id="claude-sonnet-4-5"),
    memory=shared.bind_agent("researcher"),
    tools=[AgnoKGToolkit(context=shared)],
)
analyst = Agent(
    name="Analyst",
    model=Claude(id="claude-sonnet-4-5"),
    memory=shared.bind_agent("analyst"),
    tools=[AgnoDecisionKit(context=shared)],
)

team = Team(agents=[researcher, analyst], mode="coordinate")
# Researcher's findings are instantly available to the Analyst - no copy, no sync

→ runnable notebooks in the cookbook, each self-contained and runnable in under 5 minutes

More Recipes

The flagship audit-trail recipe is above. Here are three more common patterns.

End-to-End GraphRAG Pipeline

from semantica.ingest import FileIngestor
from semantica.split import TextSplitter
from semantica.semantic_extract import NamedEntityRecognizer, RelationExtractor
from semantica.kg import GraphBuilder
from semantica.vector_store import VectorStore, HybridSearch
from semantica.context import AgentContext

# 1. Ingest
docs = FileIngestor().ingest_directory("./docs/", recursive=True)

# 2. Entity-aware chunking - never splits an entity across a chunk boundary
splitter = TextSplitter(method="entity_aware", chunk_size=1000)
chunks   = [splitter.split(doc["text"]) for doc in docs]

# 3. Extract entities and relations
ner      = NamedEntityRecognizer(confidence_threshold=0.7)
rel_ext  = RelationExtractor(confidence_threshold=0.6)
entities = [ner.extract_entities(chunk) for chunk_group in chunks for chunk in chunk_group]

# 4. Build KG
kg = GraphBuilder(merge_entities=True, enable_temporal=True).build(docs)

# 5. Hybrid retrieval
vs  = VectorStore(backend="inmemory")
ctx = AgentContext(vector_store=vs, knowledge_graph=kg)
ctx.store("Alice approved the Acme renewal in Q1 2024", conversation_id="c1")

results = HybridSearch(vector_store=vs).search("who approved the renewal?")

AML Rules Engine

from semantica.reasoning import ReteEngine, Rule, Fact, RuleType

rete = ReteEngine()
rete.build_network([
    Rule(
        rule_id="sanctions_check",
        name="Flag sanctioned-country transactions",
        conditions=[
            {"field": "amount",  "operator": ">",  "value": 10_000},
            {"field": "country", "operator": "in", "value": ["IR", "KP", "SY", "CU"]},
        ],
        conclusion="flag_for_compliance_review",
        rule_type=RuleType.IMPLICATION,
    ),
])

# Run the rule across a batch of incoming transactions, not just one
for tx in [
    Fact("tx_101", "transaction", [{"amount": 25_000, "country": "IR"}]),
    Fact("tx_102", "transaction", [{"amount": 4_500,  "country": "DE"}]),
    Fact("tx_103", "transaction", [{"amount": 60_000, "country": "KP"}]),
]:
    rete.add_fact(tx)

flagged = rete.match_patterns()

Same condition-matcher caveat as above applies — validate against your rule set before production use.

Ontology-to-Knowledge-Graph in One Pass

from semantica.ingest import FileIngestor
from semantica.semantic_extract import NamedEntityRecognizer, RelationExtractor
from semantica.kg import GraphBuilder
from semantica.ontology import OntologyGenerator, OntologyValidator
from semantica.export import RDFExporter

sources   = FileIngestor().ingest_directory("./contracts/")
ner       = NamedEntityRecognizer(confidence_threshold=0.7)
entities  = ner.process_batch([s["text"] for s in sources])

kg  = GraphBuilder(merge_entities=True).build(sources)
gen = OntologyGenerator(base_uri="https://myco.dev/ontology/")
ont = gen.generate_ontology({"entities": entities[0], "relationships": []})

report = OntologyValidator().validate(ont)
if report.valid:
    RDFExporter().export({"entities": entities[0]}, "ontology.ttl", format="turtle")

Features at a Glance

Capability	Highlights
Context Graphs	Queryable graph of entities, decisions, relationships; causal links; cross-graph navigation
Decision Intelligence	`record_decision` · `trace_decision_chain` · `find_similar_decisions` · `analyze_decision_impact` · `check_decision_rules`
Temporal Intelligence	Point-in-time snapshots · Allen interval algebra (13 relations) · `TemporalNormalizer` · bi-temporal provenance
Distance Intelligence	N×N semantic distance matrices · ego-mode visualization · distance bands · embedding cache
Semantic Extraction	NER · relation extraction · event detection · triplet generation · coreference
Reasoning Engines	Forward chaining · Rete · deductive · abductive · SPARQL · Datalog with explainable output
GraphRAG Chunking	Entity-aware · relation-aware · graph-based · ontology-aware · community-detection chunking
Conflict Detection	Value / type / relationship / temporal / logical conflicts · multiple resolution strategies
Provenance	W3C PROV-O · every fact traced to source · audit log export JSON/CSV/RDF
Ontology Hub	SHACL Studio · visual editor · cross-ontology alignments · health dashboard
Vector Store	FAISS · Pinecone · Weaviate · Qdrant · Milvus · PgVector · hybrid + filtered search
Graph Databases (LPG)	Neo4j · FalkorDB · Apache AGE · AWS Neptune
Triple Stores (RDF)	Oxigraph (embedded) · Blazegraph · Apache Jena · Eclipse RDF4J · unified `TripletStore` interface · SPARQL query & bulk load
Enterprise Data Platforms	Databricks (`DatabricksIngestor`: Unity Catalog + Delta Lake, PAT/OAuth M2M, table/query ingestion, catalog/schema/table/lineage introspection) · Snowflake (`SnowflakeIngestor`: warehouse/database/schema, password/key-pair/OAuth auth)
LLM Providers	All already supported today: OpenAI (GPT-4o, o1, o3) · Anthropic (Claude) · Google Gemini · Mistral · Meta Llama · Groq · Cohere · Azure OpenAI · AWS Bedrock · Ollama · DeepSeek · Perplexity · Together AI · Fireworks AI · Replicate · HuggingFace · via `semantica.llms` and LiteLLM

Performance

Benchmarks from v0.5.0 on a 118,000-node production graph:

Operation	Before	After	Improvement
Node search (118k nodes)	24 ms	0.004 ms	6,000× faster
Embedding cache hit	cold load	revision-based cache	10× throughput
Semantic deduplication	baseline	optimized candidate gen	6.98× faster
Candidate generation	baseline	blocking strategy	63.6% faster

Measured on a 118,000-node production graph (AMD EPYC, 64 GB RAM); the deduplication/candidate-generation figures are historical measurements recorded in CHANGELOG.md rather than an automated tests/ assertion. Results vary by hardware, dataset topology, and backend selection — run pytest tests/vector_store/test_performance_benchmarks.py -s to measure your own data.

CLI

Every capability is available from the terminal. The CLI ships with the package, no separate install required.

pip install semantica
semantica        # startup dashboard
semantica doctor # health check
semantica --help # full grouped command reference

Start with semantica, verify with doctor, build a graph, and explore the command groups from one terminal.

Command groups: ingest · parse · extract · kg · reason · decision · temporal · provenance · ontology · embed · deduplicate · validate · export · visualize · pipeline · server · explorer · mcp · doctor · shell · init · watch

→ Full CLI reference

Integrations

Native plugin bundles for Claude Code, Cursor, Codex, Windsurf, Cline, Continue, VS Code, and OpenClaw; a full-featured MCP server for any MCP-compatible client; a comprehensive REST API; and first-class Agno support for multi-agent shared context. Every major LLM provider is already supported via semantica.llms and LiteLLM: OpenAI, Anthropic, Gemini, Mistral, Llama, Groq, Cohere, Azure, Bedrock, Ollama, DeepSeek, HuggingFace, and more.

MCP setup takes 30 seconds — see MCP Server below.

Full integrations matrix (editors, MCP clients, REST clients, agentic frameworks)

Native Plugin Bundle			MCP Server + Plugin
Claude Code _{Skills · agents · hooks}	Cursor _{Skills · agents}	Codex CLI _{Skills · agents}	Windsurf _plugin	Cline _plugin	Continue _plugin	VS Code _plugin	OpenClaw _{MCP + plugin}
MCP Server	REST API
Claude Desktop _{MCP server}	GitHub Copilot _{REST API}	Roo Code _{REST API}	Goose _{REST API}	Kilo Code _{REST API}	Aider _{REST API}	Amazon Q _{REST API}	Zed _{REST API}

Agentic Frameworks

Native Integration
Agno _{First-class · pip install semantica[agno]}
Already Supported via REST API & MCP
LangChain _{REST API · MCP}	LangGraph _{REST API · MCP}	CrewAI _{REST API · MCP}	LlamaIndex _{REST API · MCP}	AutoGen _{REST API · MCP}	OpenAI Agents _{REST API · MCP}	Google ADK _{REST API · MCP}
Native SDK Integration (Coming Soon)
LangChain _{Dedicated toolkit}	CrewAI _{Dedicated toolkit}	LlamaIndex _{Dedicated toolkit}	AutoGen _{Dedicated toolkit}	OpenAI Agents _{Dedicated toolkit}	Google ADK _{Dedicated toolkit}

MCP Server

Connect any MCP-compatible client (Claude Desktop, Windsurf, Cline, VS Code) in 30 seconds:

python -m semantica.mcp_server
# or via the installed entry point
semantica-mcp

{
  "mcpServers": {
    "semantica": { "command": "python", "args": ["-m", "semantica.mcp_server"] }
  }
}

Tools exposed over MCP:

Tool	What it does
`extract_entities`	NER on any text
`extract_relations`	Relation extraction
`record_decision`	Persist a decision node
`query_decisions`	Search decision history
`find_precedents`	Semantic precedent lookup
`get_causal_chain`	Full causal ancestry
`add_entity`	Add a KG node
`add_relationship`	Add a KG edge
`run_reasoning`	Execute rule set
`get_graph_analytics`	Centrality, communities
`export_graph`	Export to RDF/JSON/Parquet
`get_graph_summary`	Graph statistics

REST API

# Start the backend
python -m semantica.server   # port 8000

# Extract entities & relations via REST
curl -X POST http://localhost:8000/api/enrich/extract \
  -H "Content-Type: application/json" \
  -d '{"text": "Apple CEO Tim Cook announced record earnings."}'

# List recorded decisions
curl "http://localhost:8000/api/decisions?category=vendor_selection"

# Query the knowledge graph
curl "http://localhost:8000/api/graph/node/acme_corp/neighbors?depth=2"

REST endpoints span: enrich (extract) · graph · decisions · reasoning · provenance · ontology · embeddings · search · export · pipeline · temporal · deduplication

Plugin Bundles

Domain skills: extract · ingest · query · ontology · validate · deduplicate · embed · reason · decision · causal · temporal · provenance · policy · explain · export · change · visualize

Specialized agents: kg-assistant · decision-advisor · explainability

Bundles for Claude Code, Cursor, Codex, Windsurf, Cline, Continue, VS Code, and OpenClaw in plugins/.

Knowledge Explorer

A browser-based graph workbench. Pan and zoom live graphs, scrub the timeline, review every decision's causal chain, resolve duplicates, and author your ontology visually. Built on React 19 + Sigma.js.

Workspace	What you can do
Knowledge Graph	Live Sigma.js canvas with ForceAtlas2 layout, Ego Mode, semantic distance heatmap
Timeline	Scrub through temporal events and watch the graph evolve
Decisions	Browse the causal chain behind every recorded decision
Registry	Live audit log of every graph mutation
Entity Resolution	Review and merge duplicates
Ontology Hub	SHACL Studio, visual editor, cross-ontology alignments, SKOS browser
Lineage	W3C PROV-O provenance visualization for any entity

Quickest way to start (no Node.js required):

pip install "semantica[explorer]"
semantica-explorer --graph my_graph.json
# Dashboard opens at http://127.0.0.1:8000

For contributor / dev-server setup: explorer/README.md: Local Setup Guide

What's New in v0.6.5

Security release — upgrading is strongly recommended. Fixes for 5 externally-reported vulnerabilities in the Explorer API and graph/triplet store backends, plus a CodeQL-flagged ReDoS:

Missing authentication on all Explorer API routes (GHSA-j4mq-hprp-987v, Critical): every route now requires SEMANTICA_API_KEY, fails closed (503) rather than open when unconfigured
SSRF via redirect bypass in ontology URL fetching (GHSA-8c7v-62gr-hj6g, High): redirect targets are now re-validated at every hop and the connection is pinned to the validated address, closing a DNS check-then-use race
Cypher injection via unvalidated node labels and property keys (GHSA-482h-hw99-h62p, Critical): Neptune, Neo4j, and FalkorDB now sanitize every label/relationship-type/property-key interpolation site
SPARQL injection via unvalidated triplet IRIs (GHSA-8vgg-8mr4-r236, Critical): Blazegraph, RDF4J, and Jena now validate subject/predicate/object IRIs before interpolation
Missing Origin validation on the WebSocket handshake (GHSA-4643-wpgq-w329, Moderate, anonymous-mode only): /ws/graph-updates now checks Origin against the same allowlist CORSMiddleware enforces for HTTP
Polynomial ReDoS in SPARQL query validation (CodeQL py/polynomial-redos): fixed a backtracking regex in the Explorer's SPARQL route

Also includes: embedded Oxigraph backend for TripletStore, PROV-O trust/spec completeness for ProvenanceManager, and the Altair Anzo triplet store backend.

→ Full release notes · Changelog

Built for High-Stakes Domains

Semantica is designed for environments where AI outputs must be explainable, auditable, and defensible, and where the data itself can't leave your infrastructure. Self-hostable with zero vendor lock-in, it's built as much for organizations handling confidential or classified data as for regulated industries chasing an audit trail:

Finance: Loan underwriting audit trails, fraud detection, AML compliance, regulatory risk knowledge graphs
Healthcare: Clinical decision support, drug interaction graphs, and patient safety audit trails
Legal: Evidence-backed research, contract analysis, case law reasoning, and privilege tracking
Government & Defense: Policy decision records, classified information governance, and regulatory reporting, fully self-hosted with no data leaving your perimeter
Law Enforcement: Case linkage, evidence provenance chains, and investigative knowledge graphs that hold up under legal scrutiny
Cybersecurity: Threat attribution, incident response timelines, and IOC provenance tracking
Autonomous Systems: Decision logs, safety validation, and explainable AI for certification

Installation

pip install semantica           # core
pip install semantica[all]      # everything

pip install semantica[agno]                 # Agno multi-agent integration
pip install semantica[llm-litellm]          # OpenAI, Anthropic, Gemini, Mistral, Llama, Groq, Cohere, Bedrock, Ollama, DeepSeek, and more
pip install semantica[graph-neo4j]          # Neo4j graph store (LPG)
pip install semantica[graph-falkordb]       # FalkorDB graph store (LPG)
pip install semantica[graph-apache-age]     # Apache AGE graph store (LPG)
pip install semantica[graph-amazon-neptune] # AWS Neptune graph store (LPG)
pip install semantica[tripletstore-oxigraph] # Embedded in-memory/on-disk RDF store
# RDF triple stores (Blazegraph, Apache Jena, Eclipse RDF4J) need no extra:
# semantica.triplet_store talks SPARQL over HTTP using the core `requests` dependency
pip install semantica[vectorstore-qdrant]   # Qdrant vector store
pip install semantica[vectorstore-pinecone] # Pinecone vector store
pip install semantica[db-snowflake]         # Snowflake
pip install semantica[db-databricks]        # Databricks (SDK + SQL connector)
pip install semantica[ingest-parquet]       # Parquet / PyArrow
pip install semantica[ingest-arrow]        # Apache Arrow, Feather, IPC
pip install semantica[viz]                  # HTML interactive visualization
pip install semantica[watch]                # Directory file watcher
pip install semantica[explorer]             # Knowledge Explorer dashboard

For production deployments, use Docker or Kubernetes rather than a local pip install. Set SEMANTICA_SECRET_KEY, configure a persistent LPG graph store (Neo4j / FalkorDB / Apache AGE / AWS Neptune) and/or RDF triple store (Blazegraph / Apache Jena / Eclipse RDF4J), and point the vector store at a hosted backend (Qdrant / Pinecone). See ARCHITECTURE.md for the full deployment topology.

# From source
git clone https://github.com/semantica-agi/semantica.git
cd semantica && pip install -e ".[dev]" && pytest tests/

Enterprise

On-premises deployment · Private cloud · Custom domain implementations · SLA-backed support · Professional services for regulated industries (finance, healthcare, legal, government).

getsemantica.ai for enterprise solutions and pricing.

Community & Support


Discord	discord.gg/sV34vps5hH: real-time help, showcases, and announcements
GitHub Discussions	Q&A and feature requests
GitHub Issues	Bug reports
Documentation	docs.getsemantica.ai
Cookbook	Runnable Jupyter notebooks
Changelog	CHANGELOG.md · Release Notes

Star History

Contributors

Contributing

All contributions are welcome: bug fixes, features, tests, and documentation.

Fork the repo and create a branch
pip install -e ".[dev]"
Write tests alongside your changes (pytest tests/)
Open a PR and tag @KaifAhmad1 for review

See CONTRIBUTING.md for full guidelines.

MIT License · Built by Semantica

GitHub · Discord · Twitter/X · Website · Docs · PyPI

If this project helps you build better AI, a star means a lot.

⭐ Star on GitHub →

English · Deutsch · Français · Español · Italiano · Português · العربية · اردو · हिन्दी · 中文 · 日本語 · 한국어

zhaoxuya520/reverse-skill

Reverse Engineering / Authorized Penetration Testing / Security Research Skill Router Pack AI-powered routing + On-demand toolchain bootstrapping + Self-evolving knowledge base Supports Claude Code, Kiro, Cursor, Cline, and other AI coding clients 逆向/渗透/安全技能路由包 - AI 自动路由 + 按需自举工具链 + 自动进化经验库 | 支持 Claude Code / Kiro / Cursor / Cline 等代码 AI 客户端

reverse-skill

Cybersecurity Skills Router · 逆向技能路由包

Navigate the dark waters, sail against the stream.

About · Getting Started · Usage · Tutorial · Fast route · Routing · Ops contracts · AI Bootstrap · Sponsors · Contributing

🌐 中文 · Project website · Online tutorial

About

If you are an AI Agent, jump to README_AI.md and follow the instructions strictly.

When an AI agent (Claude Code, Codex, Cursor, OpenCode, or another compatible client) encounters an APK, a binary, frontend JS encryption, a CTF challenge, or a pentesting target, this package routes it to the right methodology, checks available tools, and executes a repeatable workflow instead of guessing commands.

User task
  → RULES.md
  → MASTER-ROUTING / master-route.ps1 (PRIMARY)
  → case-init / scope.md (auth + network_profile; no target ACT until ready)
  → Scenario skill → tools / MCP / scripts
  → timeline + Evidence→Finding→Path → report + field-journal

Why this exists:

AI agents don't know whether to use jadx, apktool, Frida, IDA, or BurpSuite for a given task
APK, ELF, JS, PCAP, and CTF tasks each need different playbooks
Tools, MCP servers, and scripts are scattered across machines
The same mistakes get repeated because experience isn't reused

Current status

Routing rules	Regression benchmark	Core skill modules	CI platforms	Client model
41 (R0–R40)	163 cases	42 tracked modules	Windows + Ubuntu	Client-neutral

The routing core is driven by one structured configuration, validated by cross-platform CI, and kept separate from optional client adapters.

PRIMARY ladder: skills/MASTER-ROUTING.md · Full matrix: skills/routing.md · Ops: skills/ops/

(back to top)

Built With

IDA Pro · radare2 · Ghidra

(back to top)

Getting Started

Prerequisites

Java / JDK — for jadx and apktool
Node.js 22.12+ — for JS toolchain and MCP servers
Python 3.x — for Frida and helper scripts
A code AI client — Claude Code, Codex, Cursor, OpenCode, or another compatible client

Installation

git clone https://github.com/zhaoxuya520/reverse-skill.git

Then refresh the tool index per platform:

Platform	Command
Windows	`powershell -File skills/scripts/refresh-tool-index.ps1`
Linux / macOS	`bash skills/scripts/refresh-tool-index.sh`
Kali Linux	`bash kali/scripts/refresh-tool-index.sh`

Check skills/tool-index.md to see detected tools.

Platform-specific docs:

Kali Linux → kali/README-kali.md
Ubuntu/Debian → docs/platforms/linux.md
macOS → docs/platforms/macos.md

(back to top)

Usage

Supported scenarios

Scenario	Entry
APK / Android analysis	`skills/apk-reverse/`
iOS / mobile	`skills/mobile-reverse/`
Binary reverse (exe/dll/so/elf)	`skills/ida-reverse/` / `skills/radare2/`
.NET / C#	`skills/dotnet-reverse/`
Frontend JS / encrypted params	`skills/js-reverse/`
DSL VM / custom JS opcode VM	`skills/reverse-engineering/dsl-vm-reverse/`
HTTP capture / request replay	anything-analyzer, Reqable MCP + `js-reverse/`
Malware / YARA	`skills/malware-analysis/`
Penetration testing / scanning	`skills/pentest-tools/`
Attack chain / red-team orchestration	`skills/attack-chain/`
Case evidence review / report handoff	`skills/case-review/`
CTF competition	`CTF-Sandbox-Orchestrator/` (42 sub-skills)
Firmware / IoT	`skills/firmware-pentest/`
Patch diff / N-day	`skills/patch-diff-exploit/`
Pwn / exploit development	`skills/pwn-chain/`
EDR bypass	`skills/edr-bypass-re/`
API / GraphQL	`skills/api-security/`
Supply chain / SBOM	`skills/supply-chain-security/`
LLM / AI security	`skills/llm-security/`
OLLVM deobfuscation	`skills/reverse-engineering/references/ollvm-deobfuscation.md`
Diagrams / reports	`skills/diagram-generator/` / `skills/docs-generator/`

Key files

File	Purpose
README_AI.md	AI agent bootstrap and configuration
RULES.md	Global routing rules (scope gate before ACT)
skills/MASTER-ROUTING.md	PRIMARY fast ladder
skills/routing.md	Task → skill routing matrix
skills/SKILL.md	Master entry point
skills/INDEX.md	Auto-generated, client-neutral skill navigation index
skills/config/routing.json	Routing single source of truth (41 rules, R0–R40)
skills/tool-index.md	Local tool status (auto-generated)
skills/scripts/master-route.ps1	One-shot PRIMARY triage (reads routing.json)
skills/scripts/case-init.ps1	Case dir: scope / timeline / workitems
skills/case-review/	Read-only Evidence graph review and artifact fixity checks
skills/scripts/test-routing.ps1	Routing regression runner (163 benchmark cases)
skills/scripts/verify-routing-coherence.ps1	Structure + supply-chain pin gate checks
skills/scripts/extract-summaries.ps1	Regenerates INDEX.md from skill frontmatter
AGENTS.md	Platform-neutral repository instructions
skills/ops/	Scope, Evidence chain, roles, timeline (skill-router form)

Testing (run after any routing/config change)

# 1. Routing regression — 163 (hint → expected PRIMARY) cases, fails CI on any mismatch
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/test-routing.ps1
# 2. Structure coherence + supply-chain pin gate (unpinned auto-install fails)
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/verify-routing-coherence.ps1
# 3. Smoke: verify + script parse + quick route matrix
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/smoke.ps1
# 4. INDEX.md drift check (regenerate with extract-summaries.ps1 if dirty)
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/extract-summaries.ps1 -Check

GitHub Actions CI runs all of the above on Windows + Ubuntu for every push/PR.

Client-neutral integration

The routing core, regression suite, manifests, and case workflow do not depend on a specific AI client. Claude Code, Codex, Cursor, OpenCode, and other clients should load the repository through their own adapter or project-instruction mechanism. Client-specific configuration must remain optional and outside the core routing contract.

Repository layout

.
├── README.md / README_zh.md / README_AI.md
├── RULES.md / RULES_zh.md
├── skills/
│   ├── MASTER-ROUTING.md / SKILL.md / routing.md
│   ├── ops/                   # ops contracts
│   ├── scripts/               # master-route, case-init, bootstrap, verify
│   ├── field-journal/
│   ├── apk-reverse/ mobile-reverse/ js-reverse/ dotnet-reverse/
│   ├── ida-reverse/ radare2/ reverse-engineering/ malware-analysis/
│   ├── pentest-tools/ attack-chain/ pwn-chain/ firmware-pentest/
│   ├── api-security/ supply-chain-security/ llm-security/
│   └── ...
├── CTF-Sandbox-Orchestrator/
├── docs/
├── kali/                      # see kali/README-kali.md
└── work/                      # local cases (gitignored)

(back to top)

Contributing

Contributions are welcome! Fork the repo, create a feature branch, and open a PR.

Fork the Project
git checkout -b feature/AmazingFeature
git commit -m 'Add some AmazingFeature'
git push origin feature/AmazingFeature
Open a Pull Request

Contributors

(back to top)

License

This project (reverse-skill) is primarily licensed under the MIT License (see LICENSE).

Submodule and third-party dependencies:

CTF-Sandbox-Orchestrator/: GNU GPLv3
Pentest Swarm AI: Original project is AGPL-3.0. This repo only invokes it via CLI or MCP and does not include its source code
Other tools (jadx, frida, nmap, burpsuite-mcp, etc.) are subject to their respective official licenses

(back to top)

Acknowledgments

Thanks to all open-source tool authors. This project integrates tools across reverse engineering, penetration testing, CTF, and security analysis — every tool is the fruit of community effort.

Special thanks to the OLLVM deobfuscation ecosystem contributors and everyone who submitted test samples, issues, and PRs.

(back to top)

Contact

Email: ww7517437@gmail.com
QQ Group: 942400892
Discord: reverse-skill community
Issues: GitHub Issues

esengine/DeepSeek-Reasonix

DeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.

English · 简体中文 · Guide · ACP · Extensions · Spec · Website · Discord

Open source · MIT · a single Go binary

A coding agent you can leave running.

One local engine, four ways in — terminal, desktop app, browser, or your editor over ACP. Plan mode, permissions, a workspace sandbox and per-turn checkpoints keep a long autonomous run something you can still read and undo.

Important

Community · 加入社区 — bilingual Discord for setup help (#help / #求助), workflow showcases, and feature ideas. → https://discord.gg/XF78rEME2D

Features

Config-driven. Providers, the agent, enabled tools, and plugins are all declared in reasonix.toml. No hardcoded models.
Multi-model & composable. DeepSeek ships as a preset; any OpenAI-compatible endpoint is a config entry, not new code. Optionally run two models together (executor + planner) in separate, cache-stable sessions.
Plugin-driven. MCP servers contribute tools, prompts, and resources; Extension Protocol v1 sidecars can also intercept runtime events, contribute Providers and structured UI, and ship versioned plugin packages.
Cache-aware context maintenance. Startup injects a small stable environment summary, stale tool output is snipped/pruned before summary compaction, and the built-in tool schema contract is documented for regression review.
Zero-friction distribution. CGO_ENABLED=0 single binary; cross-compile to six targets with one command. The result is a fully self-contained static binary — nothing to install on the target machine beyond the binary itself.

Install

Choose the path that matches how you want to use Reasonix. The CLI/TUI, desktop app, and VS Code extension all use the same local Reasonix engine.

Path A: CLI / TUI

Install the native binary through npm on any supported platform, or use Homebrew on macOS:

npm i -g reasonix                  # any OS; pulls the prebuilt native binary
brew install esengine/reasonix/reasonix   # macOS

Prebuilt archives (darwin|linux|windows × amd64|arm64) and SHA256SUMS are on every GitHub release.

Path B: Desktop app

Use the official download page for the latest desktop build.

Platform	Package	Architecture
macOS	Universal `.dmg` or `.zip`	Apple Silicon / Intel
Windows	Installer `.exe` or portable `.zip`	x64 / ARM64
Linux	`.deb` or `.tar.gz`	x64

Windows installers are code-signed through SignPath.io with a free certificate provided by the SignPath Foundation.

Path C: VS Code extension

Complete Path A first. The extension does not bundle the CLI; it starts your local reasonix acp backend and adds native chat, editor context, tool-call approvals, model selection, and workspace sessions.

VS Code: install from Visual Studio Marketplace
VSCodium / Eclipse Theia: install from Open VSX Registry
Extension ID: SivanLiu.reasonix-agent · source and usage guide

Path D: Build from source

Clone the repository first:

git clone https://github.com/esengine/DeepSeek-Reasonix.git
cd DeepSeek-Reasonix

CLI

The CLI build requires Go 1.25+. The module pins a toolchain directive; keep GOTOOLCHAIN=auto so Go downloads the pinned toolchain, or install it.

make build      # -> bin/reasonix(.exe)
make cross      # -> dist/ (darwin|linux|windows × amd64|arm64)

Desktop

The desktop build additionally requires:

Node 24+ and pnpm 10 (npm install -g pnpm@10) for the frontend
Wails CLI matching the shared .wails-version pin

make wails-install
cd desktop
wails build

See the desktop build guide for platform webview dependencies and Linux build tags.

Quick start

CLI / TUI

These commands are for the CLI/TUI installed through Path A:

reasonix setup                      # configure a provider and model
reasonix                            # start an interactive session
reasonix run "implement the TODOs in main.go"

In an interactive session, run /init when you want Reasonix to create project instructions.

Desktop app

Download the installer for your platform from the official download page, install and launch Reasonix, then configure a provider and model in the app. The CLI commands above are not required for the desktop app.

For advanced CLI usage and configuration, see the CLI reference, Guide, and configuration paths.

Documentation

Getting started: Guide · CLI reference · Configuration paths · ACP editor integration
Features & troubleshooting: Subagent profiles · Context Engine v2 · Capability diagnostics · Recovery and updates · Bot guide · Checkpoints & rewind
Engineering & migration: Spec · Task contracts & pause policy · Tool contract · Migrating from 0.x
Extension development: Extensions · Plugin packages and Manifest v1 · Extension Protocol · Go SDK and starter

Star History

Acknowledgments

A small list of folks whose work has shaped Reasonix the most — the current top 20 contributors by commit count. The full contributor graph is on GitHub.

Contributor	Contributor	Contributor	Contributor
SivanCola	esengine	ttmouse	lifu963
reasonix	HUQIANTAO	GTC2080	light-front-theory
merge-order-check	Li-Charles-One	eghrhegpe	wufengfan
CVEngineer66	dependabot[bot]	lanshi17	SuMuxi66
CnsMaple	cyq1017	JesonChou	XTLine

Special thanks to Bernardxu123 for designing the project logo and intro video.

_{MIT — see LICENSE}
_{Built by the community at esengine/DeepSeek-Reasonix}

_{Support this project}

If Reasonix has been useful and you'd like to say thanks, you can. It stays a coffee, not a contract — donations don't buy feature priority or change how issues get triaged.

International — PayPal: paypal.me/yuhuahui
国内 — 微信支付（扫码）

google/skills

Agent Skills for Google products and technologies

Agent Skills

This repository contains Agent Skills for Google products and technologies, including Google Cloud.

Note

This repository is under active development.

Installation

npx skills add google/skills

From the npx install command, you can select the specific skills from this repo to install.

Available Skills

Additional Google skills

Plugins

This repo also bundles Google product plugins (Skills + MCP servers) for agent harnesses.

Agent harness	Install
Claude Code	`claude plugin marketplace add google/skills`, then `claude plugin install <plugin>@google-plugins`
Codex	`codex plugin marketplace add google/skills`, then install from the `/plugins` browser
Antigravity CLI	`agy plugin install https://github.com/google/skills/<plugin-path>`

Support

If you need help or encounter issues with these skills, search for existing issues or open a new one in the GitHub Issue Tracker.

Contributing

We welcome contributions to improve our skills. You can help by:

Reporting bugs or inaccuracies in the skill Markdown files.
Suggesting new skills to add to this repository (for example, Google technologies or recipes) by filing a feature request.

License

You are free to copy, modify, and distribute these skills under the terms of the Apache 2.0 license. See the LICENSE file for details.

vitali87/code-graph-rag

The ultimate RAG for your monorepo. Query, understand, and edit multi-language codebases with the power of AI and knowledge graphs

Code-Graph-RAG

Code-Graph-RAG parses a multi-language codebase with Tree-sitter, builds a knowledge graph of its structure in Memgraph, and lets you query, edit, and optimise that code in plain English. It works across a monorepo of mixed languages under one unified graph schema.

Latest News 🔥

Ruby Support: Ruby joins the graph through a new pluggable ast-grep tier that adds a language from a single YAML pattern file, emitting Module, Function, and Class nodes plus import edges without a hand-written parser.
Structural Search & Replace: Find and rewrite code by AST pattern with ast-grep, exposed as agent tools so you can match and transform structure across the whole codebase instead of relying on text or regex.
Data-Flow Tracing: New FLOWS_TO taint edges follow values through assignments, function calls, and I/O sinks. This release adds C#, Java, C, and Go, bringing tracing to 10 languages (Python, JavaScript, TypeScript/TSX, Go, Java, Rust, C++, C, and C#).

See NEWS.md for the full history.

What It Does

Point Code-Graph-RAG at a repository and it reads every source file, extracts functions, classes, methods, modules, and the relationships between them, and stores the result as an interconnected graph. Once the graph exists you can:

Ask questions about the codebase in natural language and get answers grounded in the real structure.
Retrieve the actual source of any function, class, or method by name or by intent.
Edit code through the agent with AST-based surgical patching and a diff preview before anything changes.
Optimise code against language best practices or your own coding standards.
Find dead code by walking call and reference edges from entry points.
Search and rewrite structurally by AST pattern with ast-grep.

How It Works

The system has two components:

Multi-language parser. A Tree-sitter based parser reads the codebase and ingests functions, classes, methods, modules, and their relationships into Memgraph under a single language-agnostic schema.
RAG system (codebase_rag/). An interactive CLI that turns natural language into Cypher queries, retrieves matching code, and drives AI-powered editing and optimisation.

Source Code -> Tree-sitter Parser -> AST Analysis -> Memgraph Knowledge Graph
                                                             |
User Query -> AI Model (Cypher Gen) -> Cypher Query -> Graph Results -> Response

See the Architecture Overview and Graph Schema for the full picture.

Supported Languages

Python, TypeScript, TSX, JavaScript, Rust, Go, Java, C, C++, C#, PHP, Lua, and Dart are fully supported. Scala is in development, and Ruby has structural support (modules, functions, classes, and imports) through the pluggable ast-grep tier. See the Language Support matrix for per-language capabilities.

Installation

cgr is published to PyPI. Install it system-wide with the treesitter-full (all languages) and semantic (vector search) extras:

# with uv (recommended)
uv tool install "code-graph-rag[treesitter-full,semantic]"

# or with pipx
pipx install "code-graph-rag[treesitter-full,semantic]"

You also need Docker (for Memgraph), cmake, and ripgrep. Full prerequisites, source installs, and environment setup are in the Installation guide.

Quick Start

# Start the packaged Memgraph + Qdrant stack (no compose file needed)
cgr daemon up

# Parse a repository into the graph, then query it
cgr start --repo-path /path/to/repo --update-graph
cgr start --repo-path /path/to/repo

Repeat the first command for each repository you want indexed; the graph is shared, and syncing one project leaves the others alone. To start over from an empty graph, add --clean — it deletes every project in the shared graph, not just this one, and asks for confirmation first when other projects would be destroyed.

The Quick Start guide walks through parsing, querying, and exporting in five minutes.

MCP Server

Code-Graph-RAG runs as an MCP server so Claude Code and other MCP clients can query and edit your codebase directly. See the MCP Server guide for setup.

Documentation

Getting Started

User Guide

Architecture

Python SDK

Advanced

Enterprise Services

Code-Graph-RAG is open source and free to use. For organisations that need more, we offer fully managed cloud-hosted solutions and on-premise deployments:

Cloud-Hosted Deployment: Managed cloud infrastructure for both the graph database and the AI agent connection. Zero infrastructure overhead, so we handle scaling, updates, and availability while your team focuses on building.
On-Premise & Air-Gapped Deployment: Deploy Code-Graph-RAG entirely within your own environment, including air-gapped networks. Full data sovereignty for regulated industries and security-sensitive organisations.

We also offer custom development, integration consulting, technical support contracts, and team training.

View plans & pricing at code-graph-rag.com

Contributing

Please see CONTRIBUTING.md for contribution guidelines. Good first PRs come from the TODO issues.

Support

For issues or questions, check the Troubleshooting guide first, then open an issue.

License

MIT. See LICENSE.

uber/ADR

ADR secures enterprise AI agents through observability, security benchmarking, and threat detection. Deployed at Uber.

ADR: Agentic AI Detection and Response

ADR (Agentic AI Detection and Response) is an enterprise security system for AI agents. It helps organizations secure employee-facing agents such as Cursor, Claude Code, and Codex, as well as customer-facing agents such as AI support agents.

ADR is deployed in production at Uber, and the accompanying paper was accepted to MLSys 2026: Paper PDF · Slides PDF

How ADR secures enterprise AI agents

ADR secures enterprise AI agents through four complementary capabilities: observing agent activity, evaluating defenses, detecting threats, and preventing unsafe actions.

ADR Observability: Understand what AI agents are doing and why. In production, ADR captures agent intent, tool use, and execution traces across 7+ AI coding tools on macOS, Linux, and Windows, as well as internal automation and customer-facing support agents.
ADR Benchmark: Test agent security under realistic enterprise conditions. ADR-Bench includes 300+ tasks, 133 MCP servers, and coverage of all 17 agent attack techniques.
ADR Detection: Detect risky agent behavior efficiently. Its two-tier architecture combines high-recall triage with deeper agentic reasoning for suspicious sessions.
ADR Prevention: Stop unsafe actions before they cause harm. This component is not included in the current open-source release. Stay tuned.

Repository layout

This repository contains the open-source ADR Sensor, ADR-Bench, and ADR Detector described in the paper. The offline ADR Explorer engine, which hardens ADR Detection through pre-deployment red teaming, is not included here.

Path	ADR component	Description
Sensor/	ADR Observability	Collect and normalize agent telemetry from Claude Code, Cursor, Codex, opencode, Claude Desktop, and others
Detection/	ADR Benchmark + Detection	Dual-agent detector, 133 MCP servers, 303 benchmark tasks, baselines, figure scripts
docs/REPRODUCIBILITY.md	Evaluation	Step-by-step workflow to reproduce benchmark detection and paper figures

Quick start: ADR Detection

git clone https://github.com/uber/ADR
cd ADR/Detection
uv sync
export ANTHROPIC_API_KEY="..." OPENAI_API_KEY="..."

Default detector is adr (ADR dual-agent). For keyless smoke tests, use --detector llamafirewall (see Detection/README.md).

See docs/REPRODUCIBILITY.md for the full evaluation workflow (inflate packed benchmark → run detectors → plot figures).

Component documentation:

Sensor/README.md: telemetry collection and unified schema
Detection/README.md: ADR-Bench, detector baselines, MCP infrastructure

Citation

@inproceedings{li2026adr,
  title={ADR: An Agentic Detection System for Enterprise Agentic AI Security},
  author={Li, Chenning and Hu, Pan and Xu, Justin and Ozbas, Baris and Liu, Olivia and Van, Caroline and Li, Manxue and Zhou, Wei and Alizadeh, Mohammad and Zhang, Pengyu and Sriramadhesikan, KK and Zhang, Ming},
  booktitle={Proceedings of the Ninth Conference on Machine Learning and Systems},
  year={2026}
}

Or use CITATION.cff.

License

Apache License 2.0. See LICENSE. Detection/benchmark/agentdojo/ is vendored third-party code under its own LICENSE (MIT).

Data notice

Detection/ includes synthetic benchmark fixtures (fake credentials, emulated environments, prompt-injection scenarios) for defensive security research only. Details: docs/OPEN_SOURCE_REVIEW.md.

virgiliojr94/book-to-skill

Turn any technical book PDF into a Claude Code skill — ready to study, reference, and use while you work.

book-to-skill

Turn any technical book, document folder, or collection of sources into a unified agent skill — ready to study, reference, and use while you work in GitHub Copilot CLI, Amp, or Claude Code.

Why · What it generates · Beyond books · How it works · Usage · Install · FAQ · Performance · Architecture · Changelog

24×–51× fewer tokens than dumping the book into context to answer one question, measured on real books (how it's measured).

How it works, in 3 steps:

Point it at a file, folder, or glob — /book-to-skill ./my-book.pdf
It distills the book into a skill — frameworks, decision rules, anti-patterns, and per-chapter files. Structure, not a summary.
Your agent loads it on demand — ask /my-book replication and it reads the right chapter and answers from the real content, no hallucination.

🤔 Why

You buy a great technical book. You read it once. Three months later you can't remember chapter 7 existed.

The usual workarounds don't help:

📄 "Let me just search the PDF" → you get a list of pages, not answers
🧠 "I'll ask the agent about this book" → it either hallucinates or says it doesn't have the content
📝 "I'll take notes as I read" → you end up with a 200-line doc you never open again

book-to-skill solves this by turning the book into a structured skill your agent loads on demand.

Once installed, you just type /your-book-slug replication and the agent reads the right chapter and answers from the actual content. No hallucination. No digging through PDFs. The book becomes part of your workflow.

Works with any host that supports the open Agent Skills standard — GitHub Copilot CLI, Amp, and Claude Code all read the same SKILL.md format.

📦 What it generates

Running /book-to-skill your-book.pdf (or a folder, glob, or list of files) creates a full skill in your agent's skills directory (~/.copilot/skills/<slug>/ for Copilot CLI, ~/.agents/skills/<slug>/ for Amp or cross-agent, ~/.claude/skills/<slug>/ for Claude Code):

File	Purpose	Size
`SKILL.md`	Core mental models + chapter index	~4,000 tokens
`chapters/ch01-*.md` …	One file per chapter, loaded on-demand	~1,000 tokens each
`glossary.md`	Every key term, alphabetically sorted with chapter refs	~1,500 tokens
`patterns.md`	All techniques, algorithms, and design patterns	~2,000 tokens
`cheatsheet.md`	Decision tables and quick-reference rules	~1,000 tokens

Chapter files are loaded on-demand — they don't count against the skill budget until you ask about that topic.

🏢 Beyond books

The name says "book", but the input is any structured prose. The same extraction works on knowledge you own and re-read constantly:

Internal documentation — architecture decision records, runbooks, onboarding guides. Fold a whole docs/ folder into one skill and ask it while you code.
Brand & design systems — voice guidelines, tone-of-voice docs, component principles. Turn a brand book into a skill your team queries instead of skimming a 60-page PDF.
Research clusters — a stack of papers plus your own notes, merged into a single unified skill and updated as new material lands (see Update / fold-in).
Specs & standards — RFCs, API contracts, compliance docs you reference but never memorize.

If you re-open a document often enough to wish you'd memorized it, it's a candidate.

🧾 The Discovery Loop Tax

A PDF-reading agent doesn't just read — it navigates: it re-fetches the ToC, backtracks, and re-processes all of it on every turn. book-to-skill pays that structuring cost once, at conversion, so queries stay proportional to the answer — 24×–51× fewer tokens than dumping the book into context, measured on real books.

📊 Full methodology, numbers, and per-book tables → docs/performance.md

⚙️ How it works

Two halves: a deterministic Python extractor (document → clean text + metadata) and a spec-driven generator (your agent follows SKILL.md to turn that into a structured skill). On-demand chapter files keep the loaded skill small.

🔧 Full walkthrough (Steps 0–10, extraction modes, token budgets) → docs/how-it-works.md

🚀 Usage

/book-to-skill <path|folder|glob> [skill-name] — plus analyze-only, generate-from-analysis, and update/fold-in modes.

▶️ All modes and examples → docs/usage.md

💬 Using it for something? → use cases — what people converted, the numbers they measured, and where it fell short. Your account lives in your own Gist; the index takes a one-line PR.

📥 Install

# One command, any host — via the cross-agent skills CLI:
npx skills add virgiliojr94/book-to-skill

# Or manually — clone into your skills folder (registers /book-to-skill):
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill
# (Copilot CLI: ~/.copilot/skills/ · Amp/cross-agent: ~/.agents/skills/)

📥 All hosts, optional extractors, and the standalone CLI → docs/install.md

❓ FAQ

Common questions — "why not just dump the PDF?", cost, privacy, non-book inputs, multi-file books.

❓ Answers → docs/faq.md

🔧 Requirements

The extractor tries tools in order per format and uses the first available. If nothing is installed, it tells you which command to run. Plain text, Markdown, reStructuredText and AsciiDoc need no extra deps.

Check your setup in one command: python3 scripts/extract.py --check prints which extractors are installed for every format and the exact command to install anything missing — no file needed.

PDF — choose by book type:

Book type	Tool	Install	Speed
Text-heavy (prose, few tables)	`pdftotext` (poppler)	`sudo apt install poppler-utils`	⚡ instant
Text-heavy fallback	`pypdf`	`pip3 install pypdf`	⚡ instant
Text-heavy fallback	`pdfminer.six`	`pip3 install pdfminer.six`	⚡ instant
Technical (code, tables, formulas)	`docling`	`pip3 install docling`	~1.5s/page

Before extraction begins, the skill asks you whether the book is technical or text-heavy and picks the right tool automatically. Docling preserves markdown tables and code blocks; pdftotext is faster for prose-only books.

Scanned PDFs need OCR first. A PDF that is page images with no text layer — a photographed or scanned book — has nothing for these tools to extract. The extractor checks the first pages and stops immediately with an explanation, rather than working through the whole book to produce an empty skill. Run OCR yourself, then convert the result:
ocrmypdf input.pdf output.pdf

EPUB:

Tool	Install	Quality
`ebooklib` + `beautifulsoup4`	`pip3 install ebooklib beautifulsoup4`	⭐⭐⭐ Best
stdlib `zipfile`	built-in — no install needed	⭐⭐ Always available

Other formats:

Format	Tool	Install
DOCX	`python-docx` (fallback: stdlib ZIP/XML)	`pip3 install python-docx`
HTML	`beautifulsoup4` (fallback: stdlib `html.parser`)	`pip3 install beautifulsoup4`
RTF	`striprtf` (fallback: regex)	`pip3 install striprtf`
MOBI / AZW / AZW3	Calibre `ebook-convert` (external app, not pip)	https://calibre-ebook.com/download
TXT / Markdown / reStructuredText / AsciiDoc	built-in	—

📁 Repository structure

book-to-skill/
├── SKILL.md              # Skill definition + step-by-step instructions (the generator spec)
├── scripts/
│   ├── extract.py        # Thin entrypoint wrapper
│   └── extractor/        # Modular extraction package
│       ├── config.py     # Extensions, paths, dependency constants
│       ├── dependencies.py  # optional-dep probing + --check
│       ├── exceptions.py # ExtractionError (per-source failures, batch-safe)
│       ├── utils.py      # CLI parsing, multi-source resolution, chapter detection, runner
│       └── parsers/      # Format-specific parsers (pdf, epub, docx, html, rtf, calibre, text)
├── tools/
│   ├── discovery_tax.py  # measures token cost vs context-dump / discovery loop
│   └── validate_skill.py # checks a generated SKILL.md against host rules (--lens claude|copilot|amp)
├── tests/                # pytest suite (extraction, detection, discovery tax)
├── docs/
│   ├── performance.md    # measured benchmarks, discovery tax, cost
│   └── architecture.md   # pipeline + component map
├── CHANGELOG.md          # release history (semver)
├── CONTRIBUTING.md       # dev setup, PR conventions, release process
├── SECURITY.md           # vulnerability reporting
└── README.md             # This file

⚖️ Copyright & fair use

book-to-skill ships no book content — not a single page. It's a converter you point at files you already own.

Processing is local. Extraction and analysis run on your machine. Your files are never uploaded by this tool. (If your agent's model runs in the cloud, the text you feed it follows that provider's normal data terms — same as any prompt.)
You use your own copy. Bring a book you bought, docs your company owns, or papers you have the right to read.
The output is your notes. A generated skill is a structured, synthesized derivative — framework names, definitions, takeaways — not a reproduction of the text. The skill explicitly never copies raw passages (see Quality Rule #7). Treat it like handwritten study notes: yours, for personal use.
Don't redistribute. Publishing or sharing a generated skill of a copyrighted work can infringe the rights holder. Keep skills of third-party books private. Internal docs, your own writing, and openly-licensed material are fine to share within the bounds of their license.

When in doubt, follow the license or terms of the source document. This project is a tool; how you use it is on you.

💖 Sponsors

book-to-skill is free and MIT-licensed, maintained on personal time. If it saves you tokens or study hours, consider sponsoring its upkeep: PR reviews, multilingual fixes, releases, and docs.

Become a sponsor → github.com/sponsors/virgiliojr94

Every sponsor is listed in BACKERS.md. Thank you for keeping open, privacy-first tooling alive. ✨

License

MIT — applies to the converter (code + skill definition) in this repository, not to any book or document you process with it.

Star History

unclebob/swarm-forge

A simple tool for coordinating several AI agents.

Do not spend any money on a bankrbot SWARM token.

SwarmForge

A disciplined tmux-based agent orchestration platform that turns swarms of AI agents into reliable, professional software engineers.

Intent

This main branch is documentary: it explains the system and carries the shared operational scripts and default constitution articles. The runnable workflow branches carry the project-facing configurations, role prompts, and local constitution articles that define specific workflows.

SwarmForge is an agent coordination system that facilitates communication between agents working in different git worktrees.

It provides a shared structure for role-specific prompts, worktree assignment, tmux sessions, and message passing so multiple agents can collaborate on the same project without stepping on each other.

Branches

The runnable SwarmForge configurations live on dedicated branches. Each branch contains the swarmforge/swarmforge.conf, local constitution articles, and role prompts for one workflow. At startup, its ./swarm wrapper copies the shared operational scripts and shared constitution articles from main when they are not already present, then launches that branch's local configuration.

`two-pack`

two-pack is the quick backend workflow. Use it for small tasks that benefit from fast coding without the overhead of Gherkin and acceptance testing, while still preserving backend refactoring and hardening.

coder implements requested behavior with TDD and unit tests.
cleaner batches coder handoffs and performs cleanup, CRAP and DRY review, architectural review, encapsulation and separation-of-concerns fixes, and language mutation hardening.

The normal flow is coder -> cleaner -> coder. Use this branch when you want a tight implementation/refinement loop without specification, QA, property-test, or acceptance-test roles.

`four-pack`

four-pack is the compact specification workflow. Use it for moderate projects that require Gherkin specification and some architectural consideration without splitting every quality gate into its own agent:

specifier turns user intent into precise Gherkin acceptance specifications and asks for approval before handoff.
coder implements approved behavior slices with TDD, unit tests, and generated acceptance tests.
refactorer performs behavior-preserving cleanup, coverage improvement, CRAP and DRY review, mutation-site scans, and property-test support.
architect owns high-level structure, dependency direction, mutation hardening, DRY review, soft Gherkin mutation, and final completion notification.

The normal flow is specifier -> coder -> refactorer -> architect -> specifier. Use this branch when you want disciplined development without splitting cleanup, architecture, hardening, and QA into separate agents.

`six-pack`

six-pack is the full workflow. Use it for major projects that require full specification, up-front QA, backend verification, and significant architectural consideration. It separates each major quality gate into its own role:

specifier turns user intent into accepted Gherkin specifications and end-to-end QA procedures.
coder implements approved behavior slices with TDD, unit tests, and generated acceptance tests.
cleaner performs local behavior-preserving cleanup, coverage improvement, CRAP and DRY review, and mutation-site scans.
architect reviews module structure, boundaries, dependency direction, and property-test coverage.
hardender performs mutation hardening, language mutation, CRAP and DRY verification, and soft Gherkin mutation.
QA converts the specifier's QA procedures into executable scripts, runs final user-interface verification, checks handoff consistency, and sends completion notifications.

The normal flow is specifier -> coder -> cleaner -> architect -> hardender -> QA -> completion. Use this branch when you want each review and verification concern owned by a separate agent.

Prerequisites

SwarmForge runs locally. Before starting a runnable branch, make sure the target machine has:

zsh
git
tmux
Babashka (bb)
At least one configured agent backend, such as codex, claude, copilot, or grok

Getting Started

In the directory where you want to use SwarmForge, choose a runnable branch and pull its contents without creating a Git remote:

BRANCH=four-pack
curl -L "https://github.com/unclebob/swarm-forge/archive/refs/heads/${BRANCH}.tar.gz" | tar -xz --strip-components=1

Use BRANCH=two-pack for the quick two-agent workflow, BRANCH=four-pack for the compact specification workflow, or BRANCH=six-pack for the full six-agent workflow. Do not use main for this command; main is documentary and stores the shared operational scripts, while the runnable branches provide the configurations and prompts intended for projects.

After copying a runnable branch, start the swarm from the target project:

./swarm

The ./swarm wrapper keeps the runnable branch small. On first use, if swarmforge/scripts/ is missing, it downloads the main branch archive, copies the shared operational scripts from swarmforge/scripts/, stages shared constitution articles from swarmforge/constitution/articles/, and then launches swarmforge/scripts/swarmforge.sh. Later runs reuse the existing local scripts directory instead of overwriting it.

The windows should open automatically.

To stop the swarm, close the first window listed in swarmforge/swarmforge.conf. That cleanup window shuts down the tmux sessions and closes the remaining tracked windows.

While a swarm is active, SwarmForge tries to prevent the host from sleeping. On macOS it uses caffeinate; on Linux it uses systemd-inhibit when available. Display lock or manual sleep can still interrupt agents depending on the OS. Set SWARMFORGE_PREVENT_SLEEP=0 before ./swarm to disable this behavior.

What SwarmForge Does

SwarmForge is a lightweight, tmux-based orchestration layer that:

Launches a config-driven swarm from a project-local swarmforge/swarmforge.conf
Creates one tmux session per configured role and opens a terminal surface for each role when the selected backend supports it
Reads behavior from project-local swarmforge/roles/<role>.prompt files plus a layered swarmforge/constitution.prompt
Supports per-role backends such as claude, codex, copilot, or grok
Puts the shared swarmforge/scripts/ directory on each agent's PATH, including handoff helpers for active swarm communication
Creates git worktrees under .worktrees/ for roles assigned to dedicated worktree names
Initializes a git repository in a new working directory when needed
Keeps all swarm state local to the working directory in .swarmforge/

Core Features

Config-Driven Topology — The swarm shape comes from swarmforge/swarmforge.conf, not hardcoded shell variables.
Project-Local Roles — Each role is defined by swarmforge/roles/<role>.prompt in the working tree being orchestrated.
Layered Constitution — swarmforge/constitution.prompt directs agents to read article files under swarmforge/constitution/articles/.
Backend Selection Per Role — A role can launch claude, codex, copilot, or grok.
Observable Swarm — Open one Terminal window per role and watch the sessions in real time.
Self-Hosted & Lightweight — Runs locally in tmux and Terminal with minimal machinery.

Constitution Structure

Each runnable branch contains a swarmforge/ directory with this general layout:

swarmforge/
  swarmforge.conf
  constitution.prompt
  constitution/
    articles/
      project.prompt
      local-engineering.prompt
      local-workflow.prompt
      ...
  roles/
    <role>.prompt
    ...

constitution.prompt is the entry point. Runnable branches normally use it to tell agents to read every file in swarmforge/constitution/articles/.

Shared default articles live on main under:

swarmforge/constitution/articles/
  engineering.prompt
  handoffs.prompt
  workflow.prompt

At startup, SwarmForge installs missing shared articles into the runnable branch's swarmforge/constitution/articles/ directory before creating role worktrees. It also installs missing shared articles into each role worktree during script synchronization. Existing local files are skipped, so a runnable branch can override a shared article by committing an article with the same filename.

Pack-specific additions and exceptions should use explicit local filenames rather than editing shared articles. Current conventions are:

project.prompt for the workflow's project shape and local topology.
local-engineering.prompt for workflow-specific engineering rules.
local-workflow.prompt for workflow-specific flow rules.

The local-*.prompt naming convention means "add to or specialize the shared default article for this runnable branch." Use it when the shared article remains valid and the branch only needs extra requirements, exceptions, or narrower instructions. Do not use local-*.prompt for a full replacement; use the shared filename instead when the branch intentionally overrides the shared article.

For example, main can provide a shared workflow.prompt, while six-pack can add local-workflow.prompt for QA-specific handoff behavior. If a branch needs to replace the shared workflow article completely, it can commit its own workflow.prompt; startup will treat that local file as an override and will not copy the shared one over it.

Roles

Each role in swarmforge/swarmforge.conf maps to a corresponding swarmforge/roles/<role>.prompt file.

How It Works

In a runnable branch:

SwarmForge reads swarmforge/swarmforge.conf.
The root ./swarm wrapper copies shared helper scripts, terminal adapters, and shared constitution articles from the main branch when they are not already present.
Startup installs missing shared constitution articles into swarmforge/constitution/articles/, skipping any local article file that already exists.
Startup validates the configured role prompts, helper scripts, and terminal adapters.
If the target directory is not already a git repository, startup initializes one and creates the first commit.
Startup creates one git worktree per configured role under .worktrees/, unless the role is assigned to master or none.
Startup syncs swarmforge/scripts/ and missing shared constitution articles into each role worktree and puts that local scripts directory on each agent's PATH, so agents use local handoff helpers without reaching back into the master checkout.
SwarmForge creates tmux sessions, opens terminal windows, and launches each configured backend in its assigned worktree.
Startup starts an OS-specific sleep inhibitor when one is available, and cleanup stops it with the swarm.
Roles communicate through daemon-delivered handoff files. Agents create validated drafts with swarm_handoff.sh, accept work with ready_for_next.sh, and complete work with done_with_current.sh.

Handoff Protocol

Startup syncs the shared helper scripts into every role worktree under swarmforge/scripts/ and puts that local directory on the agent's PATH. Agents do not send tmux messages directly. The launcher starts handoffd.bb, which owns tmux socket access, watches each agent outbox, copies validated handoff files into recipient inboxes, and sends only generic wake-up notifications.

Agents interact with handoffs through three helper scripts:

swarm_handoff.sh <draft-file> validates and queues outbound handoffs.
ready_for_next.sh accepts work using the role's configured receive mode.
done_with_current.sh completes the current task or batch using the role's configured receive mode.

Outbound drafts use one of two message types. A git handoff points the recipient at a committed state. The commit abbreviation must be exactly 10 hexadecimal characters; swarm_handoff.sh validates that it resolves to a single commit and canonicalizes it before queuing the handoff.

type: git_handoff
to: <role>[,<role>...]
priority: NN
task: <short-stable-task-name>
commit: <10-character-commit-abbrev>

A note is one short freeform message:

type: note
to: <role>[,<role>...]
priority: NN
message: <one line, max 80 chars>

The helper generates the delivered payload. Agents do not write long handoff bodies, branch names, queue filenames, or tmux commands.

Recipient agents run ready_for_next.sh when notified or after restart. It dispatches to the task or batch helper configured for that role. If it prints NO_TASK, they stop waiting for work. If it prints TASK: <path>, they treat the printed TASK_NAME and PAYLOAD as the task. If it prints BATCH: <path>, they process the printed BATCH_ITEM entries in helper-delivered order. If a wake-up arrives while an agent is already working, it can ignore the wake-up; done_with_current.sh checks for the next task or batch after completing the current work.

The durable handoff files and lifecycle headers replace the old logbook and resend queue. Runtime handoff state lives under .swarmforge/handoffs/ in each worktree, with outbox, sent, failed, and inbox subdirectories. Agents should not hand-edit, merge, stage, or commit handoff runtime state. See swarmforge/handoff-protocol.md for the full protocol.

The `swarmforge.conf` File

swarmforge/swarmforge.conf defines the swarm window-by-window. Each line has this form:

window <role> <agent> <worktree> [task|batch] [extra-cli-args...]

The optional receive mode defaults to task. Use batch for roles that should consume all currently queued equal-priority handoffs as one batch.

Any fields after the receive mode are passed directly to the agent CLI as additional arguments. If you omit the receive mode, extra arguments may start at the fifth field:

window coder copilot wt-coder --yolo
window architect claude wt-arch task --dangerously-skip-permissions

You can define as many windows as your project needs. Each role maps to a corresponding prompt file at swarmforge/roles/<role>.prompt, so a config containing architect, coder, reviewer, research, and release windows would expect:

swarmforge/roles/architect.prompt
swarmforge/roles/coder.prompt
swarmforge/roles/reviewer.prompt
swarmforge/roles/research.prompt
swarmforge/roles/release.prompt

This lets each project choose its own swarm shape instead of being locked to a fixed set of roles.

Example config:

window coordinator codex master
window coder codex coder
window refactorer codex refactorer
window architect codex architect

In the example above, the agents run in these worktrees:

coordinator -> main working directory on master, and is the cleanup window because it is listed first
coder -> .worktrees/coder
refactorer -> .worktrees/refactorer
architect -> .worktrees/architect

If a window uses master as its worktree name, SwarmForge does not create .worktrees/master; that role runs in the main working directory on the master branch.

tmux Behavior

SwarmForge uses a project-specific tmux socket recorded in .swarmforge/tmux-socket, so each project swarm is isolated from other tmux sessions. It also honors tmux base-index and pane-base-index settings when launching agents and sending notifications, so configurations that number windows or panes from 1 work without requiring users to change their tmux preferences.

Terminal Behavior

SwarmForge opens trackable terminal windows or tabs through a small terminal backend adapter.

Default detection:

If AppleScript is available, SwarmForge opens macOS Terminal.app windows.
Otherwise, if wt.exe is available, SwarmForge opens Windows Terminal windows.
Otherwise, SwarmForge attaches the cleanup tmux session in the current shell.

After copying a runnable branch, set SWARMFORGE_TERMINAL to override detection:

SWARMFORGE_TERMINAL=ghostty ./swarm
SWARMFORGE_TERMINAL=terminal-app ./swarm
SWARMFORGE_TERMINAL=windows-terminal ./swarm
SWARMFORGE_TERMINAL=none ./swarm

Use ghostty when you want SwarmForge to open Ghostty tabs instead of the default Terminal.app windows. Use windows-terminal when you want SwarmForge to open Windows Terminal windows from WSL. Use none when you want SwarmForge to skip terminal automation and attach the cleanup tmux session in the current shell.

Adding A Terminal Backend

The shared terminal backends are carried on main under swarmforge/scripts/terminal-adapters/. Runnable branches copy those scripts at startup. To add a new backend, update main by creating one file named after the backend:

swarmforge/scripts/terminal-adapters/wezterm.sh

The file must define this small contract:

terminal_backend_label() {
  echo "WezTerm"
}

terminal_backend_can_open_sessions() {
  return 0
}

terminal_backend_tracks_windows() {
  return 0
}

terminal_open_session() {
  local session="$1"
  local title="$2"
  local sibling_id="${3:-}"

  # Open a terminal surface that runs:
  # cd "$WORKING_DIR" && exec tmux -S "$TMUX_SOCKET" attach-session -t "$session"
  #
  # Print a stable window/tab id to stdout.
}

terminal_window_exists() {
  local window_id="$1"

  # Return 0 if the id from terminal_open_session still exists.
  # Return nonzero otherwise.
}

terminal_close_window() {
  local window_id="$1"

  # Close the id from terminal_open_session.
}

If the terminal can open sessions but cannot return stable ids for open/check/close, keep terminal_backend_can_open_sessions as return 0 and set terminal_backend_tracks_windows to return 1. SwarmForge will open one surface per session and skip the watchdog for that backend. swarmforge/scripts/terminal-adapters/windows-terminal.sh is an example of this launch-only style.

If the backend cannot open sessions at all, set both capability functions to return 1; SwarmForge will attach the cleanup tmux session in the current shell. Only edit swarmforge/scripts/swarm-terminal-adapter.sh when adding aliases or changing default auto-detection.

Window Behavior

Each visible agent window is attached to a tmux session. That means terminal selection, copy, and paste may follow tmux and terminal-emulator rules rather than ordinary text-field behavior. If copy or paste feels unusual, check whether tmux copy mode is active before assuming the agent is stuck.

The first window in swarmforge.conf is the cleanup window. Closing that top configured window is the intentional shutdown path: SwarmForge tears down the tmux sessions, closes the remaining tracked windows, and shuts down the swarm.

Closing any other tracked window is non-destructive. The watchdog reopens that window and attaches it back to the same tmux session, so the agent state and terminal history remain intact. This is often the simplest way to recover a window that has landed in an unfamiliar tmux mode or otherwise feels stuck.

drawdb-io/drawdb

Free, simple, and intuitive online database diagram editor and SQL generator.

^{Special thanks to:}

Next-gen AI-powered intelligent terminal for all platforms

drawDB

Free, simple, and intuitive database schema editor and SQL generator.

DrawDB is a robust and user-friendly database entity relationship diagram (ERD) editor right in your browser. Build diagrams with a few clicks, export and import SQL scripts, generate migrations, customize your editor, and more without creating an account. See the full set of features on here.

Getting Started

Local Development

git clone https://github.com/drawdb-io/drawdb
cd drawdb
npm install
npm run dev

Build

git clone https://github.com/drawdb-io/drawdb
cd drawdb
npm install
npm run build

Docker Build

docker build -t drawdb .
docker run -p 3000:80 drawdb

If you want to enable sharing, set up the server and environment variables according to .env.sample. This is optional unless you need to share files.

Contributing

Please see CONTRIBUTING.md for guidelines on how to contribute to this project.

Support

Join discussions: Discord

Comfy-Org/ComfyUI

The most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface.

ComfyUI

The most powerful and modular AI engine for content creation.

ComfyUI is the AI creation engine for visual professionals who demand control over every model, every parameter, and every output. Its powerful and modular node graph interface empowers creatives to generate images, videos, 3D models, audio, and more...

ComfyUI natively supports the latest open-source state of the art models.
API nodes provide access to the best closed source models such as Nano Banana, Seedance, Hunyuan3D, etc.
It is available on Windows, Linux, and macOS, locally with our desktop application, our portable install or on our cloud.
The most sophisticated workflows can be exposed through a simple UI thanks to App Mode.
It integrates seamlessly into production pipelines with our API endpoints.

Get Started

Local

Desktop Application

The easiest way to get started.
Available on Windows & macOS.

Windows Portable Package

Get the latest commits and completely portable.
Available on Windows.

Manual Install

Supports all operating systems and GPU types (NVIDIA, AMD, Intel, Apple Silicon, Ascend).

Cloud

Comfy Cloud

Our official paid cloud version for those who can't afford local hardware.

Examples

See what ComfyUI can do with the newer template workflows or old example workflows.

Features

A visual node graph for building and reusing image, video, audio, 3D, and text workflows without code.
Reusable subgraphs, workflow templates, App Mode, and a local API for integrating workflows into applications.
Efficient local execution with asynchronous queueing, partial graph re-execution, smart VRAM and RAM management, model offloading, and support for quantized models.
Broad native model support. This is a representative list; browse the workflow library for maintained, ready-to-run templates.
- Image generation: Stable Diffusion 1.5, SDXL, SD3.5, Flux.1, Flux.2, Qwen Image, Z-Image, Hunyuan Image 2.1, HiDream, Lumina Image 2.0, Chroma, Anima, LongCat Image, Ideogram 4, Krea 2, MageFlow, Microsoft Lens, PixelDiT, Kandinsky 5, and Ernie Image.
- Image editing: Flux Kontext, Flux.2 Klein, Qwen Image Edit, HiDream E1.1 and O1, OmniGen2, Boogu, JoyImage Edit, MageFlow Edit, and LongCat Image Edit.
- Video generation: Wan 2.1 and 2.2, LTX-Video 2 and 2.3, HunyuanVideo 1.5, Kandinsky 5 Video, CogVideoX, Cosmos Predict2, Bernini-R, SCAIL 2, and Mochi.
- Audio and video generation: MiniMax H3 and LTX-AV.
- Audio generation: ACE-Step 1.5 and Stable Audio 3.
- 3D and vision: Hunyuan3D 2.1, TripoSplat, SeedVR2, SUPIR, Depth Anything 3, MoGe, SAM 3 and 3.1, RT-DETRv4, and BiRefNet.
- Text generation: Gemma 3 and 4, Qwen3, Qwen3.5, and Qwen3-VL, including multimodal inputs.
Load complete checkpoints or separate diffusion models, VAEs, text encoders, LoRAs, ControlNets, adapters, and upscalers from supported model formats.
Built-in tools for inpainting, outpainting, reference conditioning, masks and compositing, model merging, upscaling, frame interpolation, segmentation, depth estimation, and media processing.
Save and load workflows as JSON, or recover complete workflows and seeds from supported generated media.
Runs fully offline: core does not download anything unless you request it. Use --disable-api-nodes to disable the optional paid Comfy API nodes and force all built-in functionality to stay offline.
Extend ComfyUI with custom nodes
Configure additional model locations with extra_model_paths.yaml.

Release Process

ComfyUI follows a weekly release cycle targeting Monday but this regularly changes because of model releases or large changes to the codebase. There are three interconnected repositories:

ComfyUI Core
- Releases a new major stable version (e.g., v0.7.0) roughly every 2 weeks.
- Starting from v0.4.0 patch versions will be used for fixes backported onto the current stable release.
- Minor versions will be used for releases off the master branch.
- Patch versions may still be used for releases on the master branch in cases where a backport would not make sense.
- Commits outside of the stable release tags may be very unstable and break many custom nodes.
- Serves as the foundation for the desktop release
Comfy Desktop
- Builds a new release using the latest stable core version
ComfyUI Frontend
- Every 2+ weeks frontend updates are merged into the core repository
- Features are frozen for the upcoming core release
- Development continues for the next release cycle

Shortcuts

Keybind	Explanation
`Ctrl` + `Enter`	Queue up current graph for generation
`Ctrl` + `Shift` + `Enter`	Queue up current graph as first for generation
`Ctrl` + `Alt` + `Enter`	Cancel current generation
`Ctrl` + `Z`/`Ctrl` + `Y`	Undo/Redo
`Ctrl` + `S`	Save workflow
`Ctrl` + `O`	Load workflow
`Ctrl` + `A`	Select all nodes
`Alt` + `C`	Collapse/uncollapse selected nodes
`Ctrl` + `M`	Mute/unmute selected nodes
`Ctrl` + `B`	Bypass selected nodes (acts like the node was removed from the graph and the wires reconnected through)
`Delete`/`Backspace`	Delete selected nodes
`Ctrl` + `Backspace`	Delete the current graph
`Space`	Move the canvas around when held and moving the cursor
`Ctrl`/`Shift` + `Click`	Add clicked node to selection
`Ctrl` + `C`/`Ctrl` + `V`	Copy and paste selected nodes (without maintaining connections to outputs of unselected nodes)
`Ctrl` + `C`/`Ctrl` + `Shift` + `V`	Copy and paste selected nodes (maintaining connections from outputs of unselected nodes to inputs of pasted nodes)
`Shift` + `Drag`	Move multiple selected nodes at the same time
`Ctrl` + `D`	Load default graph
`Alt` + `+`	Canvas Zoom in
`Alt` + `-`	Canvas Zoom out
`Ctrl` + `Shift` + LMB + Vertical drag	Canvas Zoom in/out
`P`	Pin/Unpin selected nodes
`Ctrl` + `G`	Group selected nodes
`Q`	Toggle visibility of the queue
`H`	Toggle visibility of history
`R`	Refresh graph
`F`	Show/Hide menu
`.`	Fit view to selection (Whole graph when nothing is selected)
Double-Click LMB	Open node quick search palette
`Shift` + Drag	Move multiple wires at once
`Ctrl` + `Alt` + LMB	Disconnect all wires from clicked slot

Ctrl can also be replaced with Cmd instead for macOS users

Installing

Windows and Mac

We highly recommend using the desktop app:

Link to Download

The desktop app is the easiest and best way to use ComfyUI for new users.

Windows Portable

There is a portable standalone build for Windows that should work for running on Nvidia GPUs or for running on your CPU only. It is not recommended for regular users. Regular users should use the desktop app above.

Direct link to download (nvidia)

Simply download, extract with 7-Zip or with the windows explorer on recent windows versions and run. For smaller models you normally only need to put the checkpoints (the huge ckpt/safetensors files) in: ComfyUI\models\checkpoints but many of the larger models have multiple files. Make sure to follow the instructions to know which subfolder to put them in ComfyUI\models\

If you have trouble extracting it, right click the file -> properties -> unblock

The portable above currently comes with python 3.13 and pytorch cuda 13.0. Update your Nvidia drivers if it doesn't start.

All Official Portable Downloads:

Portable for AMD GPUs

Portable for Intel GPUs

Portable for Nvidia GPUs (supports 20 series and above).

Portable for Nvidia GPUs with pytorch cuda 12.6 and python 3.12 (Supports Nvidia 10 series and older GPUs, DO NOT USE THIS ON NEWER 20 SERIES AND ABOVE GPUS).

How do I share models between another UI and ComfyUI?

See the Config file to set the search paths for models. In the standalone windows build you can find this file in the ComfyUI directory. Rename this file to extra_model_paths.yaml and edit it with your favorite text editor.

comfy-cli

You can install and start ComfyUI using comfy-cli:

pip install comfy-cli
comfy install

Manual Install (Windows, Linux)

Python 3.14 works but some custom nodes may have issues. The free threaded variant works but some dependencies will enable the GIL so it's not fully supported.

Python 3.13 is very well supported. If you have trouble with some custom node dependencies on 3.13 you can try 3.12

torch 2.7 is minimally supported but using a newer version is extremely recommended. Using a cu130 or above version of pytorch is required on Nvidia 20 series and above. Some features and optimizations might only work on newer versions. We generally recommend using the latest major version of pytorch with the latest cuda version unless it is less than 2 weeks old. If your pytorch is more than 6 months old, please update it.

Instructions:

Git clone this repo.

Put your SD checkpoints (the huge ckpt/safetensors files) in: models/checkpoints

Put your VAE in: models/vae

AMD GPUs (Linux)

AMD users can install rocm and pytorch with pip if you don't have it already installed, this is the command to install the stable version:

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm7.2

This is the command to install the nightly with ROCm 7.2 which might have some performance improvements:

pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/rocm7.2

AMD GPUs (Experimental: Windows and Linux), RDNA 3, 3.5 and 4 only.

These have less hardware support than the builds above but they work on windows. You also need to install the pytorch version specific to your hardware.

RDNA 3 (RX 7000 series):

pip install --pre torch torchvision torchaudio --index-url https://rocm.nightlies.amd.com/v2/gfx110X-all/

RDNA 3.5 (Strix halo/Ryzen AI Max+ 365):

pip install --pre torch torchvision torchaudio --index-url https://rocm.nightlies.amd.com/v2/gfx1151/

RDNA 4 (RX 9000 series):

pip install --pre torch torchvision torchaudio --index-url https://rocm.nightlies.amd.com/v2/gfx120X-all/

Intel GPUs (Windows and Linux)

Intel Arc GPU users can install native PyTorch with torch.xpu support using pip. More information can be found here

To install PyTorch xpu, use the following command:

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/xpu

This is the command to install the Pytorch xpu nightly which might have some performance improvements:

pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/xpu

NVIDIA

Nvidia users should install stable pytorch using this command:

pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130

This is the command to install pytorch nightly instead which might have performance improvements.

pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu132

Troubleshooting

If you get the "Torch not compiled with CUDA enabled" error, uninstall torch with:

pip uninstall torch

And install it again with the command above.

Dependencies

Install the dependencies by opening your terminal inside the ComfyUI folder and:

pip install -r requirements.txt

After this you should have everything installed and can proceed to running ComfyUI.

Others:

Apple Mac silicon

You can install ComfyUI in Apple Mac silicon (M1, M2, M3 or M4) with any recent macOS version.

Install pytorch nightly. For instructions, read the Accelerated PyTorch training on Mac Apple Developer guide (make sure to install the latest pytorch nightly).
Follow the ComfyUI manual installation instructions for Windows and Linux.
Install the ComfyUI dependencies. If you have another Stable Diffusion UI you might be able to reuse the dependencies.
Launch ComfyUI by running python main.py

Note: Remember to add your models, VAE, LoRAs etc. to the corresponding Comfy folders, as discussed in ComfyUI manual installation.

Ascend NPUs

For models compatible with Ascend Extension for PyTorch (torch_npu). To get started, ensure your environment meets the prerequisites outlined on the installation page. Here's a step-by-step guide tailored to your platform and installation method:

Begin by installing the recommended or newer kernel version for Linux as specified in the Installation page of torch-npu, if necessary.
Proceed with the installation of Ascend Basekit, which includes the driver, firmware, and CANN, following the instructions provided for your specific platform.
Next, install the necessary packages for torch-npu by adhering to the platform-specific instructions on the Installation page.
Finally, adhere to the ComfyUI manual installation guide for Linux. Once all components are installed, you can run ComfyUI as described earlier.

Cambricon MLUs

For models compatible with Cambricon Extension for PyTorch (torch_mlu). Here's a step-by-step guide tailored to your platform and installation method:

Install the Cambricon CNToolkit by adhering to the platform-specific instructions on the Installation
Next, install the PyTorch(torch_mlu) following the instructions on the Installation
Launch ComfyUI by running python main.py

Iluvatar Corex

For models compatible with Iluvatar Extension for PyTorch. Here's a step-by-step guide tailored to your platform and installation method:

Install the Iluvatar Corex Toolkit by adhering to the platform-specific instructions on the Installation
Launch ComfyUI by running python main.py

ComfyUI-Manager

ComfyUI-Manager is an extension that allows you to easily install, update, and manage custom nodes for ComfyUI.

Setup

Install the manager dependencies:

pip install -r manager_requirements.txt

Enable the manager with the --enable-manager flag when running ComfyUI:
```
python main.py --enable-manager
```

Command Line Options

Flag	Description
`--enable-manager`	Enable ComfyUI-Manager
`--enable-manager-legacy-ui`	Use the legacy manager UI instead of the new UI (implies `--enable-manager`)
`--disable-manager-ui`	Disable the manager UI and endpoints while keeping background features like security checks and scheduled installation completion (requires `--enable-manager`)

Running

python main.py

For AMD cards not officially supported by ROCm

Try running it with this command if you have issues:

For 6700, 6600 and maybe other RDNA2 or older: HSA_OVERRIDE_GFX_VERSION=10.3.0 python main.py

For AMD 7600 and maybe other RDNA3 cards: HSA_OVERRIDE_GFX_VERSION=11.0.0 python main.py

AMD ROCm Tips

You can try setting this env variable PYTORCH_TUNABLEOP_ENABLED=1 which might speed things up at the cost of a very slow initial run.

Notes

Only parts of the graph that have an output with all the correct inputs will be executed.

Only parts of the graph that change from each execution to the next will be executed, if you submit the same graph twice only the first will be executed. If you change the last part of the graph only the part you changed and the part that depends on it will be executed.

Dragging a generated png on the webpage or loading one will give you the full workflow including seeds that were used to create it.

You can use () to change emphasis of a word or phrase like: (good code:1.2) or (bad code:0.8). The default emphasis for () is 1.1. To use () characters in your actual prompt escape them like $ or $.

You can use {day|night}, for wildcard/dynamic prompts. With this syntax "{wild|card|test}" will be randomly replaced by either "wild", "card" or "test" by the frontend every time you queue the prompt. To use {} characters in your actual prompt escape them like: \{ or \}.

Dynamic prompts also support C-style comments, like // comment or /* comment */.

To use a textual inversion concepts/embeddings in a text prompt put them in the models/embeddings directory and use them in the CLIPTextEncode node like this (you can omit the .pt extension):

embedding:embedding_filename.pt

How to show high-quality previews?

Use --preview-method auto to enable previews.

The default installation includes a fast latent preview method that's low-resolution. To enable higher-quality previews with TAESD, download the taesd_decoder.pth, taesdxl_decoder.pth, taesd3_decoder.pth and taef1_decoder.pth and place them in the models/vae_approx folder. Once they're installed, restart ComfyUI and launch it with --preview-method taesd to enable high-quality previews.

How to use TLS/SSL?

Generate a self-signed certificate (not appropriate for shared/production use) and key by running the command: openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 3650 -nodes -subj "/C=XX/ST=StateName/L=CityName/O=CompanyName/OU=CompanySectionName/CN=CommonNameOrHostname"

Use --tls-keyfile key.pem --tls-certfile cert.pem to enable TLS/SSL, the app will now be accessible with https://... instead of http://....

Note: Windows users can use alexisrolland/docker-openssl or one of the 3rd party binary distributions to run the command example above.

If you use a container, note that the volume mount -v can be a relative path so ... -v ".\:/openssl-certs" ... would create the key & cert files in the current directory of your command prompt or powershell terminal.

Support and dev channel

Discord: Try the #help or #feedback channels.

Matrix space: #comfyui_space:matrix.org (it's like discord but open source).

Frontend Development

As of August 15, 2024, we have transitioned to a new frontend, which is now hosted in a separate repository: ComfyUI Frontend. The compiled JS files (from TS/Vue) are published to pypi and installed as a dependency in ComfyUI.

Reporting Issues and Requesting Features

For any bugs, issues, or feature requests related to the frontend, please use the ComfyUI Frontend repository. This will help us manage and address frontend-specific concerns more efficiently.

Using the Latest Frontend

The new frontend is now the default for ComfyUI. However, please note:

The frontend in the main ComfyUI repository is updated fortnightly.
Daily releases are available in the separate frontend repository.

To use the most up-to-date frontend version:

For the latest daily release, launch ComfyUI with this command line argument:
```
--front-end-version Comfy-Org/ComfyUI_frontend@latest
```
For a specific version, replace latest with the desired version number:
```
--front-end-version Comfy-Org/ComfyUI_frontend@1.2.2
```

This approach allows you to easily switch between the stable fortnightly release and the cutting-edge daily updates, or even specific versions for testing purposes.

QA

Which GPU should I buy for this?

See this page for some recommendations

lyogavin/airllm

AirLLM 70B inference with single 4GB GPU

Quickstart | Configurations | MacOS | Example notebooks | FAQ

AirLLM dramatically reduces inference memory usage, letting 70B large language models run on a single 4GB GPU card — without quantization, distillation, or pruning. You can even run 405B Llama 3.1 on 8GB, DeepSeek-V3 (671B) on ~12GB, and Kimi K3 (2.8T) — the largest open-source model released to date — on under 4GB, because sparse MoE models stream one expert at a time rather than a whole layer.

AI Agents Recommendation:

Updates

[2026/07] Kimi K3 (2.8T) support: the largest open-source model runs on a single card in 3.72GB of VRAM, measured end to end on one RTX 6000 Ada. Per-expert streaming loads only the experts a token actually routes to. K3 brings three requirements of its own: pip install compressed-tensors flash-attn (its model code mandates flash attention regardless of what you request), a CUDA 12 build of torch, since no prebuilt flash-attn wheel exists for CUDA 13 yet, and transformers 4.56.x, as its remote code does not load on 5.x.

[2026/06] v3.0: FP8 model support + the latest models. Run DeepSeek-V3 (671B) on ~12GB and Qwen3-235B on ~3GB, plus Qwen3, Llama 3.x/4, DeepSeek V2/V3, Phi-4, Gemma and more — all through a single AutoModel.

[2024/08/20] v2.11.0: Support Qwen2.5

[2024/08/18] v2.10.1 Support CPU inference. Support non sharded models. Thanks @NavodPeiris for the great work!

[2024/07/30] Support Llama3.1 405B (example notebook). Support 8bit/4bit quantization.

[2024/04/20] AirLLM supports Llama3 natively already. Run Llama3 70B on 4GB single GPU.

[2023/12/25] v2.8.2: Support MacOS running 70B large language models.

[2023/12/20] v2.7: Support AirLLMMixtral.

[2023/12/20] v2.6: Added AutoModel, automatically detect model type, no need to provide model class to initialize model.

[2023/12/18] v2.5: added prefetching to overlap the model loading and compute. 10% speed improvement.

[2023/12/03] added support of ChatGLM, QWen, Baichuan, Mistral, InternLM!

[2023/12/02] added support for safetensors. Now support all top 10 models in open llm leaderboard.

[2023/12/01] airllm 2.0. Support compressions: 3x run time speed up!

[2023/11/20] airllm Initial version!

Star History

Quickstart

1. Install package

First, install the airllm pip package.

pip install airllm

2. Inference

Then, initialize AirLLMLlama2, pass in the huggingface repo ID of the model being used, or the local path, and inference can be performed similar to a regular transformer model.

(You can also specify the path to save the splitted layered model through layer_shards_saving_path when init AirLLMLlama2.

from airllm import AutoModel

MAX_LENGTH = 128
# just pass a hugging face repo id — works with almost any popular model:
model = AutoModel.from_pretrained("Qwen/Qwen3-32B")

# go bigger with the exact same one line:
#model = AutoModel.from_pretrained("Qwen/Qwen3-235B-A22B")     # 235B, runs in ~3GB
#model = AutoModel.from_pretrained("deepseek-ai/DeepSeek-V3")  # 671B, runs in ~12GB

# or use a model's local path...
#model = AutoModel.from_pretrained("/home/ubuntu/.cache/huggingface/hub/models--Qwen--Qwen3-32B/snapshots/...")

input_text = [
        'What is the capital of United States?',
        #'I like',
    ]

input_tokens = model.tokenizer(input_text,
    return_tensors="pt", 
    return_attention_mask=False, 
    truncation=True, 
    max_length=MAX_LENGTH, 
    padding=False)
           
generation_output = model.generate(
    input_tokens['input_ids'].cuda(), 
    max_new_tokens=20,
    use_cache=True,
    return_dict_in_generate=True)

output = model.tokenizer.decode(generation_output.sequences[0])

print(output)

Note: During inference, the original model will first be decomposed and saved layer-wise. Please ensure there is sufficient disk space in the huggingface cache directory.

Model Compression - 3x Inference Speed Up!

We just added model compression based on block-wise quantization-based model compression. Which can further speed up the inference speed for up to 3x , with almost ignorable accuracy loss! (see more performance evaluation and why we use block-wise quantization in this paper)

How to enable model compression speed up:

Step 1. make sure you have bitsandbytes installed by pip install -U bitsandbytes
Step 2. make sure airllm verion later than 2.0.0: pip install -U airllm
Step 3. when initialize the model, passing the argument compression ('4bit' or '8bit'):

model = AutoModel.from_pretrained("garage-bAInd/Platypus2-70B-instruct",
                     compression='4bit' # specify '8bit' for 8-bit block-wise quantization 
                    )

What are the differences between model compression and quantization?

Quantization normally needs to quantize both weights and activations to really speed things up. Which makes it harder to maintain accuracy and avoid the impact of outliers in all kinds of inputs.

While in our case the bottleneck is mainly at the disk loading, we only need to make the model loading size smaller. So, we get to only quantize the weights' part, which is easier to ensure the accuracy.

Configurations

When initialize the model, we support the following configurations:

compression: supported options: 4bit, 8bit for 4-bit or 8-bit block-wise quantization, or by default None for no compression
profiling_mode: supported options: True to output time consumptions or by default False
layer_shards_saving_path: optionally another path to save the splitted model
hf_token: huggingface token can be provided here if downloading gated models like: meta-llama/Llama-2-7b-hf
prefetching: prefetching to overlap the model loading and compute. By default, turned on. For now, only AirLLMLlama2 supports this.
delete_original: if you don't have too much disk space, you can set delete_original to true to delete the original downloaded hugging face model, only keep the transformed one to save half of the disk space.

MacOS

Just install airllm and run the code the same as on linux. See more in Quick Start.

make sure you installed mlx and torch
you probably need to install python native see more here
only Apple silicon is supported

Example [python notebook] (https://github.com/lyogavin/airllm/blob/main/air_llm/examples/run_on_macos.ipynb)

Example Python Notebook

Example colabs here:

example of other models (ChatGLM, QWen, Baichuan, Mistral, etc):

ChatGLM:

from airllm import AutoModel
MAX_LENGTH = 128
model = AutoModel.from_pretrained("THUDM/chatglm3-6b-base")
input_text = ['What is the capital of China?',]
input_tokens = model.tokenizer(input_text,
    return_tensors="pt", 
    return_attention_mask=False, 
    truncation=True, 
    max_length=MAX_LENGTH, 
    padding=True)
generation_output = model.generate(
    input_tokens['input_ids'].cuda(), 
    max_new_tokens=5,
    use_cache= True,
    return_dict_in_generate=True)
model.tokenizer.decode(generation_output.sequences[0])

QWen:

from airllm import AutoModel
MAX_LENGTH = 128
model = AutoModel.from_pretrained("Qwen/Qwen-7B")
input_text = ['What is the capital of China?',]
input_tokens = model.tokenizer(input_text,
    return_tensors="pt", 
    return_attention_mask=False, 
    truncation=True, 
    max_length=MAX_LENGTH)
generation_output = model.generate(
    input_tokens['input_ids'].cuda(), 
    max_new_tokens=5,
    use_cache=True,
    return_dict_in_generate=True)
model.tokenizer.decode(generation_output.sequences[0])

Baichuan, InternLM, Mistral, etc:

from airllm import AutoModel
MAX_LENGTH = 128
model = AutoModel.from_pretrained("baichuan-inc/Baichuan2-7B-Base")
#model = AutoModel.from_pretrained("internlm/internlm-20b")
#model = AutoModel.from_pretrained("mistralai/Mistral-7B-Instruct-v0.1")
input_text = ['What is the capital of China?',]
input_tokens = model.tokenizer(input_text,
    return_tensors="pt", 
    return_attention_mask=False, 
    truncation=True, 
    max_length=MAX_LENGTH)
generation_output = model.generate(
    input_tokens['input_ids'].cuda(), 
    max_new_tokens=5,
    use_cache=True,
    return_dict_in_generate=True)
model.tokenizer.decode(generation_output.sequences[0])

To request other model support: here

Supported Models

AirLLM works out of the box with virtually every popular open LLM — just pass its Hugging Face ID to AutoModel.from_pretrained(...). That covers all the major families:

Llama (2 / 3 / 3.1 / 3.3 / 4) · Qwen (1 / 2 / 2.5 / 3, including MoE and FP8) · DeepSeek (V2 / V3 / R1) · Mistral & Mixtral · Phi · Gemma · ChatGLM · Baichuan · InternLM · Yi — and most new models the day they're released.

Tiny GPU, huge models

The trick: AirLLM only ever keeps one layer on the GPU at a time, so the VRAM you need depends on the model's layer size — not its total size. That's how a 671B model fits on a hobbyist card:

Model	Size	GPU VRAM
Qwen3 / Mistral / Phi (≈8B)	8B	~1–2 GB
Qwen3-30B / Mixtral (MoE)	30–47B	~1–3 GB
Qwen3-235B (MoE)	235B	~3 GB
Llama 3.x 70B (full precision)	70B	~4 GB
Llama 3.1 405B	405B	~8 GB
DeepSeek-V3	671B	~12 GB

Same one line of code for all of them — no special setup.

Acknowledgement

A lot of the code are based on SimJeg's great work in the Kaggle exam competition. Big shoutout to SimJeg:

GitHub account @SimJeg, the code on Kaggle, the associated discussion.

FAQ

1. MetadataIncompleteBuffer

safetensors_rust.SafetensorError: Error while deserializing header: MetadataIncompleteBuffer

If you run into this error, most possible cause is you run out of disk space. The process of splitting model is very disk-consuming. See this. You may need to extend your disk space, clear huggingface .cache and rerun.

2. ValueError: max() arg is an empty sequence

Most likely you are loading QWen or ChatGLM model with Llama2 class. Try the following:

For QWen model:

from airllm import AutoModel #<----- instead of AirLLMLlama2
AutoModel.from_pretrained(...)

For ChatGLM model:

from airllm import AutoModel #<----- instead of AirLLMLlama2
AutoModel.from_pretrained(...)

3. 401 Client Error....Repo model ... is gated.

Some models are gated models, needs huggingface api token. You can provide hf_token:

model = AutoModel.from_pretrained("meta-llama/Llama-2-7b-hf", #hf_token='HF_API_TOKEN')

4. ValueError: Asking to pad but the tokenizer does not have a padding token.

Some model's tokenizer doesn't have padding token, so you can set a padding token or simply turn the padding config off:

input_tokens = model.tokenizer(input_text,
   return_tensors="pt", 
   return_attention_mask=False, 
   truncation=True, 
   max_length=MAX_LENGTH, 
   padding=False  #<-----------   turn off padding 
)

Citing AirLLM

If you find AirLLM useful in your research and wish to cite it, please use the following BibTex entry:

@software{airllm2023,
  author = {Gavin Li},
  title = {AirLLM: scaling large language models on low-end commodity computers},
  url = {https://github.com/lyogavin/airllm/},
  version = {0.0},
  year = {2023},
}

Contribution

Welcomed contributions, ideas and discussions!

If you find it useful, please ⭐ or buy me a coffee! 🙏

LadybirdBrowser/ladybird

Truly independent web browser

Ladybird

Ladybird is a truly independent web browser, using a novel engine based on web standards.

Important

Ladybird is in a pre-alpha state, and only suitable for use by developers

Features

We aim to build a complete, usable browser for the modern web.

Ladybird uses a multi-process architecture with a main UI process, several WebContent renderer processes, an ImageDecoder process, and a RequestServer process.

Image decoding and network connections are done out of process to be more robust against malicious content. Each tab has its own renderer process, which is sandboxed from the rest of the system.

At the moment, many core library support components are inherited from SerenityOS:

LibWeb: Web rendering engine
LibJS: JavaScript engine
LibWasm: WebAssembly implementation
LibCrypto/LibTLS: Cryptography primitives and Transport Layer Security
LibHTTP: HTTP/1.1 client
LibGfx: 2D Graphics Library, Image Decoding and Rendering
LibUnicode: Unicode and locale support
LibMedia: Audio and video playback
LibCore: Event loop, OS abstraction layer
LibIPC: Inter-process communication

How do I build and run this?

See build instructions for information on how to build Ladybird.

Ladybird runs on Linux, macOS, Windows (with WSL2), and many other *Nixes.

How do I read the documentation?

Code-related documentation can be found in the documentation folder.

Get in touch and participate!

Join our Discord server to participate in issue and development discussions.

Please read Getting involved with Ladybird if you're new to Ladybird and want to help.

Before opening an issue, please see the issue policy and the detailed issue-reporting guidelines.

The project participation guidelines can be found in CONTRIBUTING.md.

License

Ladybird is licensed under a 2-clause BSD license.

goauthentik/authentik

The authentication glue you need.

What is authentik?

authentik is an open-source Identity Provider (IdP) for modern SSO. It supports SAML, OAuth2/OIDC, LDAP, RADIUS, and more, designed for self-hosting from small labs to large production clusters.

Our enterprise offering is available for organizations to securely replace existing IdPs such as Okta, Auth0, Entra ID, and Ping Identity for robust, large-scale identity management.

Installation

Docker Compose: recommended for small/test setups. See the documentation.
Kubernetes (Helm Chart): recommended for larger setups. See the documentation and the Helm chart repository.
AWS CloudFormation: deploy on AWS using our official templates. See the documentation.
DigitalOcean Marketplace: one-click deployment via the official Marketplace app. See the app listing.

Screenshots

Light	Dark

Development and contributions

See the Developer Documentation for information about setting up local build environments, testing your contributions, and our contribution process.

When you contribute documentation, either to accompany a code change or as a standalone contribution, please be sure to follow our documentation Style Guide.

Security

Please see SECURITY.md.

Adoption

Using authentik? We'd love to hear your story and feature your logo. Email us at hello@goauthentik.io or open a GitHub Issue/PR!

	Atlas Cloud is a full-modal AI inference platform that provides unified API access to 400+ curated image, video, audio, 3D, and language models. Atlas Cloud supports reverse-skill with model services for cross-platform routing verification, documentation, and open security workflows.
	Kite AI builds identity and payment infrastructure for the agent economy. Its support helps sustain reverse-skill's open-source maintenance, routing benchmarks, and platform-neutral security workflows.