🗺️ Overview

🌱 ACORN¹ is a research assistant and metascience multi-tool that provides and operationalizes an ontology for research activity data (RAD). ACORN enables adding linked data context and transforming RAD into a knowledge graph that is amenable to automated reasoning and artifact generation (e.g. PDFs, PPTX, etc.)

ACORN is a command line multi-tool that employs automated processes for informing and enforcing defined content schemas. With these content schemas, ACORN builds communication assets such as PDFs, presentation files, and web pages. It also lays the foundation for deep data insights about ORNL’s — and any institution’s — corpus of research. Built using the memory-safe Rust programming language, ACORN can be used on any Windows, Mac, or Linux machine

AI-enabled, without making AI mandatory. ACORN’s core validation, formatting, linking, and export workflows are deterministic. Optional tooling can discover and download local GGUF models, configure them for OpenCode, VS Code, Goose, and llama-swap, and provide compatible AI agents with ACORN-specific operating instructions through acorn skill.

Note

AI-Assisted Development Disclosure — Level 4. ACORN uses AI in accordance with VisidataMachineAssistanceLevel::Significant: humans author the majority of project code and retain review and decision authority over all changes; AI tools may directly create or edit code which is reviewed and refactored before being merged.

Choose your trail

Start with the outcome closest to your work:

Not sure yet? The role guide shows every trail at a glance.

Explore ACORN

Choose a route to explore its concepts and commands.

Research activity data

Explore: research activity data · check and format · linked data · shareable artifacts

Persistent identifier lifecycle

Explore the persistent identifier lifecycle →

Local AI And Agent Tooling

Explore: local models · application sync · agent skill · …but is it agentic?

1. ACORN stands for “Accessible Content Optimization for Research Needs ↩

🤔 So what? Big deal? Who cares?

Important

If you do science, you need ACORN.

🎯 What is ACORN trying to solve?

Accessible Content Optimization for Research Needs, ACORN, allows science achievers and communicators to create analysis-ready research activity data. ACORN’s associated schemas standardize how research is codified and communicated to capture the entire research architecture, including what research is being done, how it’s done, and how it all relates.

Built with memory-safe Rust, ACORN is a portable solution that uses statically typed and dynamically validated data structures. Schemas include unique identifiers¹ to support open science principles and practices.

ACORN can help inform researchers, sponsors, and partners, as well as train machines on existing research projects. It can also identify where gaps in a body of research exist.

🆕 How is it novel?

ACORN focuses on research at the project level. While there are other systems that track research projects tangentially — through people, publications, or organizations — there is no system we know of that employs projects as the primitive source of information. We believe codifying research activity data at the project level is the key to unlocking deep insights about an organization’s resources, funding, partnerships, and accomplishments. This network of linked data surpasses what may be already present but siloed in current search tools.

With existing tools, we can see

• publications², but we don’t know about projects without journal publications or how projects relate,
• people³, but people move groups, change job roles, and leave organizations, and
• approvals and timelines, but these systems aren’t often designed to integrate with other PIDs or systems
• budgets, but budgets do not include the level of project details necessary to capture appropriate scientific understanding

ACORN does not replace or remove these systems. Each supports part of the puzzle. ACORN can help ensure they integrate and work together to provide users with valuable information from a central source of truth, no matter their entry point.

⚠️ What are the risks?

There are very few risks to ACORN. They would simply include anything that could preclude continued development of ACORN like lack of funding or human resources to support further development of the project. They also include any security risks inherent in projects at locations that host potentially sensitive data.

Even if it completely fails⁴, our “escalator” turns to stairs and remains useful. It is open source⁵, designed to be local and decentralized, and built on existing systems, with information stored in flat files so it will never be lost or unshareable.

Tip

Research activity data curated and controlled by ACORN and its associated schemas and processes will always hold value.

🎁 Why should I use ACORN?

You should use ACORN if you want your project to be part of the research conversation. We initially developed ACORN for researchers, to help capture and communicate their projects more effectively. ACORN helps cut down on administrative burden, allowing the PI or a project designee to submit descriptive metadata to a form and receive automatically generated fact sheets in PDF, web, or PowerPoint form. This form, kept as a JSON file in a designated repository⁶, becomes the single source of truth for information on each project. We continue to develop the metadata schema and talk with research groups to benefit organization processes.

1. ACORN provides CURIEs and will soon also work with research activity identifiers (RAiD) ↩

2. e.g., DOIs ↩

3. e.g., ORCiDs ↩

4. Realistically, the only mode of failure is complete lack of adoption… ↩

5. https://www.osti.gov/doecode/biblio/156286 ↩

6. We call these repositories “buckets”; see Buckets for details. ↩

🚀 Getting Started

Important

You do not need to install ACORN on your computer to use it in a CI job. If you only need to validate or publish a repository automatically, configure ACORN in CI using this example .gitlab-ci.yml. Use one of the options below when you want to run ACORN directly on your computer or in a container.

Installation

Choose an installation method

Install with Scoop (Windows only)

• Ensure you have Scoop installed.

• Open your terminal and add the extras bucket to Scoop

  scoop bucket add extras
  

• Run the following command to install ACORN

  scoop install acorn
  

• After installation, you can verify the installation by running:

  acorn help
  

• You can keep ACORN up to date with Scoop by running:

  scoop update acorn
  

Install with Homebrew (Linux and MacOS)

• Add the custom tap:

  brew tap research-enablement/acorn https://code.ornl.gov/research-enablement/homebrew-acorn.git
  

• Trust the custom tap:

  brew trust research-enablement/acorn
  

• Install ACORN:

  brew install acorn-cli
  

• Verify installation:

  acorn help
  

• Upgrade to the latest version:

  brew update
  brew upgrade acorn-cli
  

Install with Cargo

• Ensure you have Rust and Cargo installed. If not, you can install them using rustup.rs.

• Open your terminal and run the following command to install ACORN

  cargo install --locked acorn-cli
  

• After installation, you can verify the installation by running:

  acorn help
  

Run Inside a Container

• Ensure you have Docker¹ installed.

• Pull the latest ACORN image with Docker¹

  docker pull savannah.ornl.gov/research-enablement/acorn/runner
  

• Run ACORN using Docker¹

  docker run --rm savannah.ornl.gov/research-enablement/acorn/runner help
  

Tip

You will probably need to mount a volume to use ACORN with your local files. For example:

docker run --rm -v $(pwd):/data savannah.ornl.gov/research-enablement/acorn/runner:latest check /data/project

Download pre-compiled binary

• Download the latest release from the ACORN GitLab Releases page

  • 🪟 Windows

    • Open a PowerShell terminal, visit the releases page to find the latest version, and run:

      irm -OutFile acorn.exe -Uri https://code.ornl.gov/api/v4/projects/16689/packages/generic/x86_64-pc-windows-gnu/v<version>/acorn.exe
      

    • Test the downloaded executable:

      .\acorn.exe help
      

  • 🐧 Linux

    • Open a terminal, visit the releases page to find the latest version, and run:

      curl -LO https://code.ornl.gov/api/v4/projects/16689/packages/generic/x86_64-unknown-linux-musl/v<version>/acorn
      

    • Make the downloaded file executable:

      chmod +x acorn
      

    • Test the downloaded executable:

      acorn help
      

  • 🍎 macOS

    • Standalone macOS binaries are not currently published. Use the Homebrew, Cargo, or source installation above.

Install from source

• Clone the ACORN repository

  git clone https://code.ornl.gov/research-enablement/acorn.git
  cd acorn
  

• Install acorn command

  cargo install --locked --path ./crates/acorn-cli
  

• After installation, you can verify the installation by running:

  acorn help
  

1. These instructions will work with any OCI-compliant container runtime, such as Docker or Podman. ↩ ↩2 ↩3

Choose your path

ACORN spans research writing, data tooling, and platform operations. Pick a trail now; switch trails whenever your work changes.

If you want to see ACORN work before choosing, take the 10-minute Quick Quest.

Next stop: Plant your first project in the Quick Quest.

Researcher trail

Goal: describe a project once, improve it safely, and create outputs for people and machines.

1. Read why ACORN treats projects as first-class research objects.
2. Complete the Quick Quest with a small research activity record.
3. Learn what check evaluates and how to run it offline.
4. Follow the persistent identifier lifecycle to find and enrich project connections.
5. Choose an export target such as CFF, PDF, Markdown, or PowerPoint.

Your finish line is a version-controlled RAD file that passes the checks you selected and produces at least one shareable artifact.

Next stop: Begin with the hands-on Quick Quest.

Developer trail

Goal: integrate ACORN’s data model, validation, and optional agent tooling into your own tool.

1. Install ACORN and inspect acorn help.
2. Learn the ACORN research activity model.
3. Use the acorn-lib Rust crate for native and agent-enabled applications, and extract ACORN’s operating instructions with acorn skill.
4. Use the acorn-py package for Python workflows.
5. Review the WebAssembly-supported surface before targeting a browser or edge runtime.

When adding a CLI integration, prefer the generated CommandLineHelp.md in the repository as the exact option reference and the curated command pages for workflow guidance.

Next stop: Start building with the acorn-lib crate.

Platform engineer trail

Goal: make ACORN repeatable across repositories, services, and local inference tools.

1. Define sources and defaults with ACORN configuration.
2. Aggregate versioned buckets with download.
3. Follow the model workflow from metadata import through weight selection.
4. Route downloaded models to applications with sync.
5. Use serve for supported GitLab bot automation, distribute acorn skill for compatible agents, and keep doctor nearby as the rescue guide. The CLI lists Model Context Protocol (MCP)¹ paths for giving agents standardized access to tools and context, but they are not yet implemented.

For CI commands that support it, use global --offline mode when the job must be deterministic and ensure every required network-backed asset is cached or configured explicitly. Commands reject offline mode when they cannot honor that guarantee.

Next stop: Define the workflow in ACORN configuration.

1. Model Context Protocol, “Architecture” and “Server features”. ↩

Quick Quest: Validate your first RAD file

In about 10 minutes, you will take one research activity data (RAD) file through ACORN’s core loop:

📥 Download the project

Download the quest fixture, or fetch it from the documentation repository with ACORN:

acorn download https://code.ornl.gov/research-enablement/acorn \
  --filter '^docs/src/_assets/quick-quest/' \
  --flatten \
  --output acorn-quick-quest
cd acorn-quick-quest

Your tiny project contains one RAD record and its fact-sheet graphic:

quick-quest/
├── index.json
└── lazer-kitten.png

Key fields in the record look like this:

{
  "meta": {
    "id": "quick-quest",
    "media": [{ "contentUrl": "lazer-kitten.png" }]
  },
  "title": "Lazer Kitten Research Lab",
  "subtitle": "A tiny experiment in reusable research storytelling"
}

🔎 Check it

acorn --offline check index.json --skip prose

You should get a successful exit and no schema findings. ACORN may still offer a readability coaching note. --offline makes the lab deterministic; --skip prose avoids synchronizing the optional prose analyzer.

✨ Preview, then format

acorn format index.json --dry-run
acorn format index.json

The first command shows a diff without writing. The second applies normalized formatting and controlled-vocabulary values. A second dry run should show no remaining changes.

📤 Export shareable files

acorn --offline export index.json --format cff --skip prose
acorn --offline export index.json --format pdf --skip prose

Expected artifacts: CITATION.cff, beside index.json, and export/quick-quest.pdf. The PDF uses the downloaded lazer kitten graphic and the full project narrative. Both files come from the same source record, so you can update one file and reproduce every output.

🏆 Quest complete

You now have one human-maintainable source plus citation and PDF outputs.

Next stop: Explore the full Check, Format, and Export guides.

Concepts

ACORN is built around a few core concepts to ensure its effectiveness. This section will introduce these concepts and explain their significance in the context of ACORN and science.

Motivation

For the last few decades, scientific progress has been driven largely by publishing papers in, ideally peer-reviewed, scientific journals. Publishing affords researchers recognition, career advancement, and funding opportunities. This model can be effective, but it has some serious limitations ACORN aims to address.

1. Publish or perish¹: Scientists and researchers often care more about publishing than about sharing knowledge. This is not without reason, as publications are a key metric for career advancement and funding. However, this can lead to a focus on quantity over quality and a reluctance to share negative results or data that does not support a hypothesis.
2. Reproducibility crisis²: Many scientific results are difficult or impossible to reproduce, leading to questions about their validity. This is compounded by the fact that many publications do not provide access to the underlying data or code used in the research.
3. No clear way to demonstrate science: Publications, people, and budgets do not tell the whole story. Science needs a cross-domain standard to collect and communicate the full context of scientific endeavors, including data, code, methods, and results.

ACORN addresses these issues by codifying the details of a research project and providing an automated framework for sharing and analyzing scientific knowledge. Predicated on the idea of applying “science all the way down”, ACORN applies rigorous scientific principles to the management and dissemination of scientific knowledge.

Research Enablement

ACORN is managed by the Research Enablement Initiative at Oak Ridge National Laboratory (ORNL). REI aims to improve the way scientific research is conducted, shared, and evaluated. It is a team of developers, communication experts, and information scientists passionate about open science, transparency, and improving the researcher experience.

REI provides:

• A cross-domain model of research activity data (RAD)
  • ACORN - Schema, controlled vocabularies, and ontologies for describing research activities
  • ASPECT - Attribute of ACORN that describes technology associated with a given research activity
• A command-line application written in Rust - acorn-cli
• A Rust crate for working with RAD - acorn-lib
• A Python package for working with RAD - acorn-py
• A catalog of research activity data at ORNL - research.ornl.gov

🪣 Buckets

RAD lives in versioned folder collections called “buckets”. Each bucket contains a set of files and media assets that describe research activities. For multiple examples, see ORNL’s buckets.

Buckets can be combined via a flat-file³ configuration file using the ACORN CLI tool. This allows users to aggregate data from multiple sources and generate outputs such as reports based on the combined data.

Buckets are flexible and extensible - they do not require a cloud provider or expensive infrastructure to use. They can be stored in any version-controlled repository, such as GitLab, GitHub, or even a local file system.

Buckets are designed to enable federation and scaling while maintaining low-level control over permissions and access. This allows organizations to share data across teams and departments while maintaining control over who can access and modify the data.

Tip

See the research enablement wiki for more information on buckets.

1. D. R. Grimes, C. T. Bauch, and J. P. A. Ioannidis, “Modelling science trustworthiness under publish or perish pressure,”“ Royal Society Open Science, vol. 5, no. 1, p. 171511, Jan. 2018, doi: 10.1098/rsos.171511. ↩

2. M. Baker, “1,500 scientists lift the lid on reproducibility,”“ Nature, vol. 533, no. 7604, Art. no. 7604, May 2016, doi: 10.1038/533452a. ↩

3. A flat-file is a simple text file that contains data in a structured format, such as JSON or YAML. Flat-files are easy to read and write, and can be used to store configuration data for applications. ↩

ACORN Schemas and Ontologies

The research activity schema organizes identity, metadata, technology context, narrative sections, contact information, and extension notes into one portable record. Field names below follow the serialized JSON/YAML form.

ASPECT

A Scientific Paradigm for the Efficient Classification of Technology

portability | maturity | autonomy | motivity

The ASPECT framework is a standardized methodology for classifying and describing technology. It defines underlying dimensions of technology and uses them to map projects into a shared space, allowing clearer insight into their capabilities, requirements, and relationships.

ASPECT was designed to unify our understanding of automation, AI/ML technology, and “classical” software. We focus on “technology” instead of “AI/ML technology” because the latter is a subset of the former. Focusing on AI/ML as the end goal is not fruitful or correct. In fact, doing so is backward. AI/ML software is not novel in any meaningful sense. Even if it was, it would still be 100% predicated on the scientific principles of software.

In the context of technology, AI/ML and automation are the same.

Tip

Read docs.rs documentation for ASPECT

Key Components

Primary attributes

click arrow to expand or collapse

💾 Data

Data is not included in primary four attributes, but is very important when characterizing technology.

Data has multiple dimensions

• Real or Synthetic
• Availability
• Modality
• Quality

Example

The ASPECT framework can be applied in various scenarios

Consider a fictional project with the following characterization:

Badge Visualization

ASPECT can be visualized in a badge-like form for visual project portfolio management

Figure 1: ASPECT badge for a project

Figure 1 is an example of an ASPECT badge that provides immediate feedback on the state of the project and its technology components. It can be used in project dashboards, reports, and presentations to communicate the current status and future goals of the project in a clear and concise manner. Figure 2 below shows the same badge as depicted in figure 1, but with the attributes annotated for clarity.

Figure 2: Annotated ASPECT badge

📦 Software Portability

Software portability describes how easily software can move across platforms and run in different environments with little or no modification. In ASPECT, this attribute helps measure whether software can work across different hardware, operating systems, and cloud setups.

Levels of Portability

Limited (Level 0)

Software at this level is tied to a specific environment. Running it elsewhere often requires major code or configuration changes. It may depend on platform-specific hardware, operating systems, or libraries that are hard to reproduce.

Source (Level 1)

Software at this level can be compiled and run on different platforms when the required compiler and build tools are available. In most cases, only minor changes are needed. Some platform-specific dependencies may still need attention during build or setup.

Containerized (Level 2)

Software at this level is packaged and run in containers such as Docker¹, Podman², or Apptainer³. Containers isolate dependencies and provide a consistent runtime. As a result, deployment and scaling are easier across local, on-premise, and cloud environments when a compatible container runtime is available.

Installable (Level 3)

Software at this level is designed to be installed and configured on multiple platforms, usually through installers or setup scripts. Some manual setup may still be required, but the process is generally user-friendly. Platform-specific installers or options are often provided to support different operating systems and hardware.

Automated Installation Available (Level 4)

Software at this level is distributed through one or more package managers such as npm⁴, Homebrew⁵, Scoop⁶, or the Ubuntu advanced package management tool⁷. It is typically published to package repositories so users can install and update it with standard tools. This approach improves deployment speed and ongoing maintenance across many environments.

WebAssembly8 (Level 5)

Software at this level is compiled to WebAssembly (WASM)⁹, which allows it to run in modern browsers and other environments that support a WebAssembly runtime. It can often run across desktop, mobile, and server targets without platform-specific changes. Because runtime support is broad and growing, WebAssembly is often treated as a leading portability target.

1. https://www.docker.com/ ↩

2. https://podman.io/ ↩

3. https://apptainer.org/ ↩

4. https://www.npmjs.com/ ↩

5. https://brew.sh/ ↩

6. https://scoop.sh/ ↩

7. https://ubuntu.com/server/docs/how-to/software/package-management/ ↩

8. https://webassembly.org/ ↩

9. https://webassembly.org/getting-started/developers-guide/ ↩

🤝 Autonomy

In the context of ASPECT, “autonomy” characterizes a technology’s level of human-machine teaming (HMT) and describes the adaptive, bi-directional interaction among humans and machines that augments human capabilities for improved outcomes. This attribute builds on prior work by the Society of Automotive Engineers’ six levels of driving automation¹ and expands on ISO definitions to partition technology into distinct and employable categories.

Tip

ISO 22989² defines human-machine teaming as “integration of human interaction with machine intelligence capabilities.”

This attribute is important for understanding how well a technology can operate independently of human intervention, as well as the level of human oversight and control required for its operation. By categorizing technologies based on their autonomy, we can better understand their capabilities and limitations and make informed decisions about their use in various applications. The Visidata project popularized its own similar “level of machine assistance” characterizing LLM involvement in code changes³, and ASPECT’s autonomy attribute builds on this work to provide a more comprehensive framework for understanding the relationship between humans and machines in technology.

Tip

The acorn-lib crate provides conversion utilities to seemlessly integrate Visidata’s AI collaboration levels into ASPECT’s autonomy attribute.

Levels

Manual (HMT 0)

This level is characterized by the execution of a script where the deterministic outcome is fully known and controlled by the human operator.

Machine-assisted (HMT 1)

In this level, the machine assists the human operator in executing a task. The human remains in full control of the task execution, with the machine offering support or suggestions as needed. This might include an iterative script that augments the input during each iteration based on prior outputs.

Human as primary (HMT 2)

Machine as primary (HMT 3)

Human supervisor (HMT 4)

Machine only (HMT 5)

1. SAE J3016 Taxonomy and Definitions for Terms Related to Driving Automation Systems: https://www.sae.org/standards/j3016_202104-taxonomy-definitions-terms-related-driving-automation-systems-road-motor-vehicles ↩

2. ISO/IEC 22989:2022 Information Technology — Artificial Intelligence Concepts and Terminology ↩

3. Visidata AI Collaboration Levels: https://www.visidata.org/blog/2026/ai/ ↩

🪴 Maturity

Levels

Tip

Read docs.rs documentation for maturity levels

Discussion

ASPECT leverages a simplified mapping from augmented technology readiness levels (TRL). Wikipedia¹ defines TRLs as “a method for estimating the maturity of technologies during the acquisition phase of a program. TRLs enable consistent and uniform discussions of technical maturity across different types of technology.” The U.S. federal acquisitions community widely uses TRLs to assess the maturity of a particular technology. Additionally, ASPECT incorporates work² that adapted TRLs to directly address the particular nuances of machine learning systems. Additionally, ASPECT maturity levels work well with the capability maturity model but go beyond maintenance processes and efficiency to characterize a technology’s maturity in practice. Specifically, ASPECT’s openness and portability attributes create a well-defined understanding of a given technology.

Maturity in ASPECT reflects the degree to which a system has been tested, validated, and proven in real-world scenarios, as well as its readiness for deployment and integration into existing workflows. In combination with the other ASPECT attributes, ASPECT’s maturity attribute provides a holistic view of the system under consideration, beyond a technology’s age or quality.

1. Technology Readiness Level: https://en.wikipedia.org/wiki/Technology_readiness_level ↩

2. A. Lavin et al., “Technology readiness levels for machine learning systems,” Nat Commun, vol. 13, no. 1, p. 6039, Oct. 2022, doi: 10.1038/s41467-022-33128-9. ↩

🦾 Motivity

Discussion

“Motivity” is a technology’s ability to exert power over its environment. In the context of ASPECT, this involves how a given technology interacts with its environment and its degree of autonomy in performing tasks. As a model of interaction, motivity is closely related to the autonomy attribute. Motivity can also be viewed in terms of data binding: no binding, one-way binding, and two-way binding.

Motivity is a somewhat uncommon word. It was chosen for the ASPECT framework in part because deliberate ambiguity can foster conceptual depth. Rarity minimizes external preconceptions, enabling custom meaning layering without the baggage of a widely used term.

Motivity has been defined in various contexts across philosophy, biology, and psychology, often emphasizing intrinsic capacity for motion or change, which makes sense considering its etymology, emphasizing an intrinsic ability rather than external force. Motivity uniquely captures an inherent “motive power” or self-initiating force for change, aligning with a data model’s bidirectional synchronization as an active, propulsive property rather than passive reactivity (which implies response) or linkage (structural connection).

Similar niche terms like “affordance” in HCI gained traction despite initial obscurity and today offer rich, nuanced meanings.

Levels

Motivity is partitioned into six ordinal levels that describe how a technology interacts with its environment. The framework is built around three primitives: perception (one-way input binding), projection (one-way output binding), and comprehension (internal state and computation).

Note

Throughout this document, “comprehension” refers to a technology’s ability to receive, store, and act on data — not to general intelligence, consciousness, or AGI. A hash function, a state machine, and a lookup table all exhibit comprehension in this sense: they maintain internal state and their behavior depends on it.

Inert (Level 0)

Technology at this level has no computational capability and no interaction with the environment. It is purely passive. Examples include a hammer, a simple pulley system, or any purely physical tool with no embedded intelligence.

Computational (Level 1)

Technology at this level performs self-contained computation but has no input from or output to the environment. Comprehension (internal processing) is present, but neither perception nor projection are. Examples include a digital model or simulation that runs in isolation.

Perceptive (Level 2)

Technology at this level receives input from the environment (one-way input binding) but produces no output and has no internal comprehension. The technology observes but does not process or act. Examples include a data shadow or a sensor that logs readings to storage without analyzing them.

Projective (Level 3)

Technology at this level produces output to the environment (one-way output binding) but receives no input and has no internal comprehension. Examples include a cron job that emails a status report — it projects information without sensing or reasoning about its environment.

Reactive (Level 4)

Technology at this level has two-way binding with the environment (perception and projection) but is stateless — it responds to input with output in a direct stimulus-response fashion with no internal model or memory of past interactions. Comprehension is absent. Examples include a smart light switch that turns lights on when motion is detected, or a relay that closes a circuit when a threshold is crossed.

Adaptive (Level 5)

Technology at this level has full two-way binding (perception and projection) with internal comprehension — it maintains state, builds an internal model of its environment, and changes its behavior based on accumulated experience. Examples include a digital twin that continuously synchronizes with a physical system and predicts future states, or an autonomous agent that plans and adapts.

1. Y. K. Liu, S. K. Ong, and A. Y. C. Nee, “State-of-the-art survey on digital twin implementations,” Adv. Manuf., vol. 10, no. 1, pp. 1-23, Mar. 2022, doi: 10.1007/s40436-021-00375-w. ↩ ↩2 ↩3

💾 Data

Discussion

When discussing data, we can evaluate four core aspects:

• Origin — Where does the data come from, and how was it produced?
• Availability — How accessible is the data to intended users and systems?
• Modality — What forms of information does the data contain?
• Quality — How well does the data support its intended use?

Attributes

Origin

Data origin describes whether the data is collected from real-world observations (real) or generated synthetically (synthetic). Real data is often considered more valuable for certain applications, such as training machine learning models, because it captures the complexity and variability of the real world. However, synthetic data can be useful for testing, simulation, and augmenting real datasets, especially when real data is scarce or sensitive.

NVIDIA Omniverse Replicator¹ is an example of a tool that can generate synthetic data, particularly in the context of computer vision and robotics. By creating realistic virtual environments and scenarios, it allows researchers to generate large amounts of labeled data without costly and time-consuming real-world data collection.

Availability

Availability describes the extent to which data can be accessed and used. It is strongly related to “openness” and the “presumed open principle” for data.

While openness is characterized as open, public, shared, or closed, ASPECT data availability takes a more direct approach to describing the actual availability of data, which may be “open” but still unavailable due to other factors (e.g., technical or legal barriers).

Modality

Data modality describes the type or format of data, which can include:

• 📕 Text — Unstructured or structured textual data, such as documents, articles, or social media posts
• 🎵 Audio — Sound recordings, such as music, speech, or environmental sounds
• 🖼️ Image — Visual data, such as photographs or scanned images
• 🎬 Video — Moving image data, such as movies or surveillance footage
• 📈 Signal — Time-series data, such as sensor readings or financial market data
• 🕸️ Graph — Structured data representing relationships between entities, such as social networks or knowledge graphs

Multi-modal data combines multiple modalities, such as video with audio or text with images, to provide richer context and insights. In the context of ASPECT, data modality is a list, and multi-modal data can be described by including multiple modalities in the list (e.g., [“text”, “image”] for research activity data that relies on both textual and visual data).

Quality

Data quality leverages a precious metals metaphor to describe data quality.

Data quality describes the level of processing and readiness of the data for analysis and use. The levels were developed with inspiration from data readiness levels ², anaylsis-ready data³, and multiple other data quality frameworks. For example, the transition from gold to platinum maps nearly directly to a transition from band B to band A in the data readiness levels. The key difference is ASPECT’s quality levels are more intuitive and directly actionable for researchers working with data in the context of research activities. See the geospatial data section below for an example of how data processing levels relates to data quality.

🌎 Geospatial Data

Geospatial data describes features and events tied to location. Common formats include raster data, such as satellite imagery, and vector data, such as points, lines, and polygons. These datasets support mapping, navigation, and spatial analysis. For geospatial work, data processing level is an important additional quality dimension.

Based on NASA’s Data Processing Levels⁴, geospatial data can be described with the following processing levels

• Level 0 — Raw
• Level 1A — Annotated
• Level 1B — Processed Annotated
• Level 1C — Spectral Variables
• Level 2 — Derived Geophysical
• Level 2A — Derived Surface
• Level 2B — Processed Derived Surface
• Level 3 — Gridded
• Level 3A — Periodic Summaries
• Level 4 — Model Output

Most remote sensing sources (e.g. satellites) provide metadata that includes the data processing level. Processing the geospatial data with techniques such as atmospheric correction, pansharpening, and orthorectification can improve the quality and usability of the data for various applications, thereby increasing the associated processing level. For example, orthorectification corrects for terrain-induced distortions, improving the spatial accuracy of the data and increasing its processing level from Level 1B to Level 2B.

Geospatial data processing level relates to ASPECT’s data quality attribute in that higher processing levels typically indicate higher quality data. For instance, Level 2B data, which has been processed to correct for atmospheric effects and terrain distortions, would generally be considered higher quality than Level 1B data, which is only annotated and not fully processed. However, the specific quality designation (e.g., gold, silver) would depend on additional factors such as the use case and the presence of any remaining artifacts or limitations in the data. For example, orthorectification might be the difference between gold and silver quality data for AI/ML applications.

1. NVIDIA Omniverse Replicator: https://docs.omniverse.nvidia.com/extensions/latest/ext_replicator.html ↩

2. Data Readiness Levels: https://arxiv.org/abs/1705.02245 ↩

3. Analysis Ready Data (ARD): https://ieeexplore.ieee.org/document/8899846 ↩

4. NASA Data Processing Levels: https://www.earthdata.nasa.gov/learn/earth-observation-data-basics/data-processing-levels ↩

Persistent identifier lifecycle

ACORN treats a persistent identifier (PID) as evidence that moves through several distinct stages. Finding a PID does not by itself prove that it is valid, and parsing it does not contact its registration authority.

flowchart LR
    input["Text<br/>or metadata"] --> find["Find<br/>candidates"]
    find --> parse["Parse<br/>components"]
    parse --> validate[Validate]
    validate --> normalize[Normalize]
    normalize --> classify[Classify]
    classify --> report["Report<br/>and retain"]
    classify -->|Project identity| persist["Create<br/>or enrich"]
    classify -. optional .-> resolve["Resolve<br/>metadata"]
    resolve --> report
    resolve -->|Project identity| persist
    persist -. exact identity .-> merge["Merge<br/>deterministically"]

Supported identifiers

The typed Rust API supports ARK, arXiv, DOI, Handle, ISBN, ISNI, ORCID, RAiD, ROR, SWHID, and US patent parsing. The generic Identifier representation also recognizes HTTP(S) URLs. PIDINST and Unknown are classification values, but they do not currently have typed parsers.

Validation is local. It checks syntax, components, and a checksum where the implemented identifier specification defines one; it does not resolve the identifier or confirm that a registration record exists.

ACORN’s regression suite maintains shared test-vector parity with Metadata Tools for arXiv, DOI, ISBN, ISNI, ORCID, RAiD, and ROR, and with idutils for ARK, arXiv, DOI, Handle, ISBN, ISNI, ORCID, RAiD, ROR, and SWHID. Here, parity means ACORN runs corresponding upstream cases for these overlapping identifier types; it does not mean the libraries have identical APIs, normalization policies, or support for other identifier families.

Schema validation recognizes ISNI in DataCite name, affiliation, publisher, and funder identifiers; InvenioRDM person or organization identifiers; and RAiD contributors whose schemaUri is https://isni.org.

1. Find candidates

Each typed PID implements PersistentIdentifierParse::find_all. The finder scans unstructured text with the PID’s recognition pattern and returns parsed values:

#![allow(unused)]
fn main() {
use acorn::schema::pid::{DOI, PersistentIdentifier, PersistentIdentifierParse};

let text = "The dataset is available at https://doi.org/10.11578/dc.20250604.1.";
let found = DOI::find_all(text);

assert_eq!(found.len(), 1);
assert_eq!(found[0].identifier(), "10.11578/dc.20250604.1");
}

The gather command runs the supported finders across file, document, URL, standard-input, and literal-text content. It removes duplicate normalized discoveries from the report while retaining the source reference for discovery history. To avoid classifying ordinary paths as Handles, unstructured discovery requires hdl: or an hdl.handle.net resolver URL; structured fields and direct parsing also accept bare Handles.

2. Parse components

from_string decomposes one value into a typed structure. Parsing is intentionally separate from validation: malformed input can produce an empty or partial value, so callers that require a usable PID must validate it.

#![allow(unused)]
fn main() {
use acorn::schema::pid::{DOI, PersistentIdentifier, PersistentIdentifierParse};

let doi = DOI::from_string("https://doi.org/10.11578/dc.20250604.1");

assert_eq!(doi.prefix().as_deref(), Some("10.11578"));
assert_eq!(doi.suffix().as_deref(), Some("dc.20250604.1"));
assert_eq!(doi.url(), "https://doi.org/10.11578/dc.20250604.1");
}

The PersistentIdentifier trait provides common component access through identifier, prefix, suffix, check_digit, schema_uri, and url. The meaning of a component depends on the PID specification.

3. Validate locally

Use the typed is_valid method when a boolean is convenient. Schema fields use the helpers in schema::validate, which return Result<(), ValidationError> for composition with the RAD validators.

#![allow(unused)]
fn main() {
use acorn::schema::pid::{DOI, PersistentIdentifierParse};
use acorn::schema::validate::is_doi;

assert!(DOI::is_valid("10.11578/dc.20250604.1"));
assert!(is_doi("10.11578/dc.20250604.1").is_ok());
assert!(is_doi("not-a-doi").is_err());
}

The local checks do not make a network request. Identifier resolution is a later, optional operation.

4. Normalize a representation

format parses a value and renders the type’s standard display form. It is a formatting operation, not a validity result:

#![allow(unused)]
fn main() {
use acorn::schema::pid::{DOI, ISNI, ORCID, PersistentIdentifierParse};

assert_eq!(DOI::format("https://doi.org/10.11578/dc.20250604.1"), "10.11578/dc.20250604.1");
assert_eq!(ISNI::format("0000 0004 9229 9539"), "https://isni.org/isni/0000000492299539");
assert_eq!(ORCID::format("0000-0002-2057-9115"), "https://orcid.org/0000-0002-2057-9115");
}

For discovery and ingestion, Identifier::normalized is the safer combined boundary. It trims surrounding prose punctuation, parses according to the declared kind, formats the result, validates it, and returns None when the value is unsupported or invalid. PID::Unknown asks ACORN to detect a supported kind.

#![allow(unused)]
fn main() {
use acorn::schema::pid::{Identifier, PID};

let raw = Identifier {
    kind: PID::DOI,
    value: "<https://doi.org/10.11578/dc.20250604.1>".to_string(),
};
let Some(normalized) = raw.normalized() else {
    panic!("expected a valid DOI");
};

assert_eq!(normalized.value, "10.11578/dc.20250604.1");
assert_eq!(normalized.identity_key(), "doi:10.11578/dc.20250604.1");
}

This distinction matters: the normalized display is suitable for RAD fields and reports, while the identity key is suitable for exact matching.

arXiv identifiers convert to their work-level DataCite DOI with DOI::from(arxiv), producing the 10.48550/arXiv.* namespace and omitting any revision suffix. The reverse conversion uses ARXIV::try_from(doi) because publisher DOIs and other DOI namespaces do not encode an arXiv identifier.

Research activity metadata stores both DOI and arXiv publication identifiers in meta.doi; validation and export classify each value by its format. Handles are stored in meta.handle and cross into CFF as other identifiers. SWHIDs are stored separately in meta.swhid and exported to CFF with identifier type swh.

5. Classify the evidence

PID records what an identifier identifies. ACORN currently divides discoveries into two groups:

• arXiv, DOI, RAiD, ISBN, patent, ARK, and SWHID values are project-like identifiers. Each can independently create or match a research activity candidate. Versioned arXiv identifiers retain their revision in evidence but share the unversioned work identity.
• Handle, ISNI, ORCID, ROR, PIDINST, unknown identifiers, and arbitrary URLs are entity or supporting evidence. They remain in reports and discovery history but cannot independently create or merge a candidate.

A provider can explicitly relate person or organization evidence to a project, but ACORN does not infer that relationship merely because the values occur in the same input.

6. Resolve and enrich optional metadata

acorn gather --resolve runs after local discovery. arXiv and DOI evidence is sent to CiteAs, Handle evidence to the public Handle proxy REST API, ORCID evidence to ORCID, RAiD evidence to the RAiD resolver, and SWHID evidence to the Software Heritage resolver. Handle resolution retains the complete public record as provenance and maps only direct HTTP(S) URL string values to websites on a project candidate found in the same source; it does not interpret 10320/loc or make a Handle project identity. SWHID resolution confirms archive presence and returns resolver metadata, not citation data. ISNI is normalized and retained as local evidence but does not currently have a remote resolver integration. A successful response contributes only values with a direct candidate mapping: identifiers, title, description, websites, keywords, sponsors, partners, and related activities. A resolver failure does not turn a locally valid identifier into invalid evidence. In --raw output, resolved arXiv and DOI values use the citation family selected by --citation-format, then ACORN_CITATION_FORMAT, then IEEE; resolved ORCIDs use Given Family (normalized ORCID) with public credit name as fallback, and failed resolutions retain the original normalized identifier while reporting a failure on stderr.

Remote DOE CODE project matches enter the same candidate pipeline with a provider identity such as osti-project:<code_id> and a DOI when one is available. DOE CODE supplies project descriptions, websites, and role-separated organization names. A --lab filter additionally associates the selected laboratory’s known ROR. With --resolve, valid ORCIDs enrich person reports, project DOIs and person ORCIDs receive structured resolver outcomes and resolved raw rendering, repository URLs can contribute provider-reported programming languages, and provider-confirmed links are checked for liveness. These optional online operations retain the original DOE CODE result when they fail. DOE CODE people and organization searches remain report-only.

GitLab work-item intake uses the same artifact candidate representation but is separate from the gather command. An embedded or repository CITATION.cff can contribute normalized DOI and other supported identifiers, title, abstract, author names, an explicitly declared singular contact, landing and repository websites, canonical keywords, and repository languages. It does not infer sponsors, partners, or a contact from the author order. Dates, contributor roles, licenses, and award identifiers are not currently mapped or placed in notes; dedicated typed schema fields are planned.

All enrichment follows the same merge rules:

1. Accept values only from a provider field with a defined semantic mapping; do not infer relationships from proximity or list order.
2. Normalize recognized identifiers before identity or field mapping.
3. At database persistence, prefer an existing populated scalar value and fill only missing scalar values.
4. Union and deduplicate list values, using the URL as the identity for websites; normalize keywords and technologies through their controlled vocabularies.
5. When resolver or provider evidence is persisted, retain it as provenance; do not coerce an unsupported value into an unrelated field.

RAiD organization roles are mapped independently from ROR name resolution. Funder produces a sponsor relationship; every supported non-funder organization role produces a partner relationship. A mixed-role organization can therefore be both. A single organization without a role is treated as the RAiD default lead organization, but roleless entries in a multi-organization record are not classified. The organization name is emitted only when its ROR is present in ACORN’s embedded sponsor or partner vocabulary; an unknown ROR remains organization evidence without a guessed name.

7. Build exact identities and persist candidates

Before persistence, project identifiers become namespaced identity keys such as doi:10.11578/dc.20250604.1 or arxiv:2106.09685. A qualified SWHID uses swhid:<core-swhid> so origin, path, and fragment context do not change byte identity; the complete qualified value remains in evidence. ACORN lowercases the namespace. arXiv versions are removed from identity keys, while normalized evidence retains them. DOI, arXiv, RAiD, ISBN, patent, and SWHID identity values are compared case-insensitively; ARK and provider-specific values preserve their value case. Keys are sorted and deduplicated.

Bucket ingestion also adds a repository-qualified RAD identity, and providers can add their own project identity. These are identity keys rather than new PID types.

Persistence uses exact identity overlap:

1. No matching row creates a candidate with a portable NanoID.
2. One matching row fills missing fields and unions unique arrays and identities.
3. Repeated identical evidence leaves the row unchanged.
4. Conflicting populated values keep the stored value and add the observation to provenance.
5. Evidence matching multiple rows reports a conflict and does not mutate them.

Use acorn gather to inspect this lifecycle from the command line. Add global --no-local-database when you want discovery and reporting without history or candidate persistence.

Calculate local SWHIDs

The host CLI can hash working-tree objects or traverse an existing local SHA-1 Git repository. It never clones, fetches, changes refs, or writes working-tree files.

acorn swhid README.md --raw
acorn swhid ./src --kind directory --raw
acorn swhid . --kind revision --reference HEAD --raw
acorn swhid . --kind git-tree --reference HEAD --raw
acorn swhid . --kind release --reference v1.0.0 --raw
acorn swhid . --kind snapshot --raw

--verify <SWHID> recalculates the selected object and compares core identifiers. Qualifiers are intentionally ignored for that byte/object comparison. Directory calculation traverses the supplied filesystem directory and does not apply Git ignore rules; use --kind git-tree for committed tree state.

…But Is It Agentic?

🌱 It is growing in that direction. ACORN approaches agentic development through Intelligence in Depth (IID): the deliberate layering of AI capabilities so that each layer adds structure, context, continuity, or control.

In a Nutshell

IID layers prompting, templates, workflows, skills and context, memory, and agent harnesses. Each layer adds capability and control while staying local-first and file-oriented.

Two protocols are optional extensions: the Model Context Protocol (MCP)¹ can connect agents to context and tools, while the Agent Client Protocol (ACP)² lets clients communicate with and supervise agents.

IID adapts the idea of defense in depth: an information security strategy that integrates people, technology, and operations across multiple layers.³ Instead of expecting one prompt or one model to carry an entire workflow, IID distributes intelligence across reusable prompts, controlled workflows, skills and connected capabilities, memory, and an interoperable agent harness. The layers reinforce one another, but each remains useful on its own:

Arrows indicate composition and control flow, not increasing maturity or quality.

IID is an ordered architecture, not an ASPECT maturity scale. The sequence shows how each layer can structure, supply, or govern the layers before it. A system is not more mature for using an agent harness; it should use the shallowest sequence that reliably satisfies the task. IID is therefore not a synonym for maximum autonomy.

Intelligence in Depth

Guiding Principles

Two principles constrain every IID layer:

• Local-first. Data, models, validation, and orchestration remain on the user’s machine by default. The network and remote services are explicit choices, not prerequisites. Local-first preserves user ownership and offline operation without prohibiting synchronization or collaboration.⁴
• File over app. Durable instructions, context, state, and results live in files the user can control, retrieve, and read. Applications are replaceable tools that operate on those files rather than the only place the work can exist.⁵

Together they produce a third rule: protocols are adapters, not dependencies. MCP, ACP, and model APIs can connect IID to external capabilities without becoming the source of truth.

IID Layers

1. One-time prompting sends a direct instruction to a model through a library or API. It is appropriate for a single transformation or answer whose inputs and outputs are already well defined.

   Example: An application sends one research narrative to acorn-lib’s OpenAI-compatible chat-completion API with the instruction “Summarize this activity,” then returns the model’s response.

   OpenAI-compatible describes the connection format, not who provides the model. A compatible server accepts supported OpenAI-style HTTP endpoints and JSON requests and responses. That server may be OpenAI’s service or another implementation, including a local server such as llama-swap; the term does not mean OpenAI created, hosts, or endorses the server or model.

2. Prompt templates turn instructions into reusable, version-controlled .prompt files with defined inputs, configuration, and expected outputs. Templates make model behavior easier to share, test, and improve. Google’s Dotprompt specification documents this executable .prompt file pattern.⁶

   Example: ACORN renders its embedded summarize.prompt template with a source narrative, maximum word count, and output structure so different callers reuse the same instructions.

3. Workflow composition and iteration coordinates model calls, deterministic operations, and tools through explicit control flow. A workflow may sequence, select, repeat, delegate, or combine bounded tasks, but its path and safeguards remain defined by the application. Anthropic distinguishes these predefined workflows from agents that dynamically direct their own process and tool use.⁷ Repeating workflows require clear exit conditions, measurable progress, state passed between calls when needed, and limits on iterations, time, tokens, and cost.

   Example (planned): ACORN asks a model to address gaps in a research narrative, runs deterministic validation, and supplies any remaining findings to another bounded pass until no high-severity issue remains or the workflow reaches its iteration, token, or time limit.

4. Skills, context, and capability engineering assembles the instructions, research data, evidence, examples, tools, constraints, and current state needed for each invocation. Agent Skills package specialized instructions and optional resources into portable, version-controlled directories that an agent can load when relevant.⁸ As an optional extension, the Model Context Protocol (MCP) can standardize how applications connect agents to prompts, resources, and tools.¹

   Example: An agent loads the ACORN skill and receives the relevant ResearchActivity schema, source record, validation results, and allowed tools before proposing a correction. A future MCP server could expose the same authoritative context and deterministic checks through a standard interface.

5. Connected memory preserves useful state across iterations, sessions, or tasks. Memory should be selective and attributable: durable facts, decisions, provenance, and prior results are more valuable than an unfiltered transcript. Its origin, availability, modality, and quality are part of the capability’s data profile. A memory service may be reached through MCP, but the protocol is the connection mechanism rather than the memory itself.

   Example (planned): A later session retrieves a previously reviewed project identity, identifier mapping, and provenance record instead of asking the model to infer them again from conversation history.

6. Agent harness and interoperability orchestrates models, skills, tools, workflows, context, memory, permissions, validation, recovery, observability, and human approval. The harness turns the lower layers into a controlled workflow and owns its budgets and stopping conditions. Its permissions and approval policy shape autonomy, while its perception, state, actions, and feedback shape motivity. As an optional extension, the Agent Client Protocol (ACP) can standardize communication between the harness and external agents, including sessions, streamed updates, and permission requests.²

   Example (planned): ACORN launches OpenCode through ACP, sends a hydrated prompt, streams progress, mediates tool permissions, validates the returned suggestion, and asks for human approval before any change is applied.

Applying the Guiding Principles

How IID Shapes ACORN

ACORN exists to maintain, validate, connect, analyze, and communicate research activity data. That work needs trustworthy structure and provenance before it needs autonomy. ACORN therefore keeps schema validation, identifier checks, formatting, linking, and artifact generation deterministic. AI is an optional consumer of—and contributor to—those workflows, not a replacement for their rules.

IID guides ACORN development in five ways:

• Ground intelligence in research structure. ACORN schemas, validators, persistent identifiers, and provenance provide authoritative context and machine-checkable boundaries for model-assisted work.
• Make capability composable. Prompts, skills, model APIs, local-model configuration, and future tools are useful independently and can be combined without forcing every user into a full agent stack.
• Keep agency accountable. Iteration needs explicit exit criteria and budgets; memory needs provenance and lifecycle rules; tools need permissions; and consequential actions need validation or human approval.
• Work locally by default. Deterministic core operations, prompt hydration, and locally available models should continue to work without a remote AI service. Network use must remain explicit and respect ACORN’s offline boundary.
• Keep files authoritative. Research records, .prompt templates, SKILL.md instructions, configuration, and generated artifacts should remain portable. Applications consume or synchronize this state rather than owning its only copy.

Local-first does not mean local-only: ACORN can still synchronize applications and use remote services when selected. It is also distinct from portability, which describes where the complete capability can run after accounting for its model, tool, and service dependencies. File over app does not require every internal value to be a flat file. Databases may provide rebuildable indexes and operational storage, while credentials belong in environment variables or dedicated secret stores rather than portable project files.

MCP and ACP are optional, complementary extension points rather than requirements for IID. MCP answers what context and capabilities an agent can access; ACP answers how a client communicates with and supervises an agent. Skills remain portable instruction and resource packages independent of both protocols. A system can implement context engineering or an agent harness without MCP or ACP. The protocols also do not replace model APIs, which provide direct model invocation.

Current ACORN Support

The table reports ACORN’s implementation coverage for each IID layer. It does not score ACORN’s maturity or imply that every workflow should use every layer.

The sequence is composable, not all-or-nothing. ACORN can strengthen each layer independently—for example, by adding prompt evaluation before workflow execution, exposing deterministic ACORN operations as tools before granting broader agency, and defining memory provenance before retaining agent state. The result should be an agentic ACORN whose intelligence grows in depth without weakening the dependable research infrastructure at its core.

1. Model Context Protocol, “Architecture” and “Server features”. ↩ ↩2

2. Agent Client Protocol, “Architecture”. ↩ ↩2

3. National Institute of Standards and Technology, “defense-in-depth,” Computer Security Resource Center Glossary. The glossary traces the definition to CNSSI 4009-2015 and multiple NIST publications, including SP 800-53 Rev. 5. ↩

4. Martin Kleppmann, Adam Wiggins, Peter van Hardenberg, and Mark McGranaghan, “Local-first software: You own your data, in spite of the cloud”, Ink & Switch, 2019, doi: 10.1145/3359591.3359737. ↩

5. Steph Ango, “File over app”, 2023. ↩

6. Google, Dotprompt specification and Dotprompt reference documentation. ↩

7. Anthropic, “Building effective agents”, 2024. ↩

8. Agent Skills, Specification. ↩

Citations

A selection of academic papers and resources that have influenced the development of ACORN

[1] E. Njor, M. A. Hasanpour, J. Madsen, and X. Fafoutis, “A Holistic Review of the TinyML Stack for Predictive Maintenance,” IEEE Access, vol. 12, pp. 184861-184882, 2024, doi: 10.1109/ACCESS.2024.3512860.

[2] Y. Yang et al., “A Survey of AI Agent Protocols,” Apr. 26, 2025, arXiv: arXiv:2504.16736. doi: 10.48550/arXiv.2504.16736.

[3] B. Liu et al., “Advances and Challenges in Foundation Agents: From Brain-Inspired Intelligence to Evolutionary, Collaborative, and Safe Systems,” Mar. 31, 2025, arXiv: arXiv:2504.01990. doi: 10.48550/arXiv.2504.01990.

[4] “AI Blindspot: A Discovery Process for preventing, detecting, and mitigating bias in AI systems.” Accessed: Jan. 24, 2023. [Online]. Available: https://aiblindspot.media.mit.edu/

[5] V. Gadepally et al., “AI Enabling Technologies: A Survey,” May 08, 2019, arXiv: arXiv:1905.03592. doi: 10.48550/arXiv.1905.03592.

[6] A. Jain, S. Sharma, and S. Duggal, “Comparative Study of Various Process Model in Software Development,” 2013. Accessed: Jan. 24, 2023. [Online]. Available: semanticscholar.org

[7] Q. Hua et al., “Context Engineering 2.0: The Context of Context Engineering,” Oct. 30, 2025, arXiv: arXiv:2510.26493. doi: 10.48550/arXiv.2510.26493.

[8] N. D. Lawrence, “Data Readiness Levels,” May 05, 2017, arXiv: arXiv:1705.02245. doi: 10.48550/arXiv.1705.02245.

[9] A. Fuller, Z. Fan, C. Day, and C. Barlow, “Digital Twin: Enabling Technologies, Challenges and Open Research,” IEEE Access, vol. 8, pp. 108952-108971, 2020, doi: 10.1109/ACCESS.2020.2998358.

[10] J. Gou, B. Yu, S. J. Maybank, and D. Tao, “Knowledge Distillation: A Survey,” Int J Comput Vis, vol. 129, no. 6, pp. 1789-1819, June 2021, doi: 10.1007/s11263-021-01453-z.

[11] D. Kreuzberger, N. Kühl, and S. Hirschl, “Machine Learning Operations (MLOps): Overview, Definition, and Architecture,” May 14, 2022, arXiv: arXiv:2205.02302. doi: 10.48550/arXiv.2205.02302.

[12] M. Mitchell et al., “Model Cards for Model Reporting,” in Proceedings of the Conference on Fairness, Accountability, and Transparency, Jan. 2019, pp. 220-229. doi: 10.1145/3287560.3287596.

[13] E. Blasch, J. Sung, and T. Nguyen, “Multisource AI Scorecard Table for System Evaluation,” Feb. 07, 2021, arXiv: arXiv:2102.03985. doi: 10.48550/arXiv.2102.03985.

[14] F. Yu, H. Zhang, and B. Wang, “Natural Language Reasoning, A Survey,” Mar. 26, 2023, arXiv: arXiv:2303.14725. doi: 10.48550/arXiv.2303.14725.

[15] S. Zhao, Y. Yang, Z. Wang, Z. He, L. K. Qiu, and L. Qiu, “Retrieval Augmented Generation (RAG) and Beyond: A Comprehensive Survey on How to Make your LLMs use External Data More Wisely,” Sept. 23, 2024, arXiv: arXiv:2409.14924. Accessed: Oct. 02, 2024. [Online]. Available: arxiv.org

[16] Y. K. Liu, S. K. Ong, and A. Y. C. Nee, “State-of-the-art survey on digital twin implementations,” Adv. Manuf., vol. 10, no. 1, pp. 1-23, Mar. 2022, doi: 10.1007/s40436-021-00375-w.

[17] Center for Security and Emerging Technology and B. Buchanan, “The AI Triad and What It Means for National Security Strategy,” Center for Security and Emerging Technology, Aug. 2020. doi: 10.51593/20200021.

[18] J. M. Bradshaw, R. R. Hoffman, D. D. Woods, and M. Johnson, “The Seven Deadly Myths of ‘Autonomous Systems,’” IEEE Intelligent Systems, vol. 28, no. 3, pp. 54-61, May 2013, doi: 10.1109/MIS.2013.70.

[19] M. R. Endsley, “Toward a Theory of Situation Awareness in Dynamic Systems. Human Factors Journal 37(1), 32-64,” ResearchGate, Aug. 2025, doi: 10.1518/001872095779049543.

[20] M. Kleppmann, A. Wiggins, P. van Hardenberg, and M. McGranaghan, “Local-First Software: You Own Your Data, in spite of the Cloud,” in Proceedings of the 2019 ACM SIGPLAN International Symposium on New Ideas, New Paradigms, and Reflections on Programming and Software, Oct. 2019, pp. 154-178. doi: 10.1145/3359591.3359737. [Online]. Available: inkandswitch.com/essay/local-first

[21] S. Ango, “File over app,” July 01, 2023. Accessed: Aug. 18, 2026. [Online]. Available: stephango.com/file-over-app

Command Line Reference

• Configuration
• Commands
• Generated option reference
• Model workflows

The command pages explain workflows and common decisions. For the exact options in the version you installed, run:

acorn help
acorn <command> --help

The repository’s generated option reference is rebuilt from the same Clap definitions as the binary. Documentation checks keep its top-level command list aligned with the curated pages.

Configuration

Flat file

ACORN can be configured using JSON, JSONC (JSON with Comments), or YAML format flat files. These configuration files allow users to specify options and settings for the ACORN CLI tool, including input and output directories and logging levels.

Example

.acorn.json file

{
    "buckets": [
        {
            "name": "bessd",
            "repository": {
                "provider": "gitlab",
                "id": 17603,
                "uri": "https://code.ornl.gov/research-enablement/buckets/bessd"
            }
        }
    ],
    "models": [
        {
            "name": "qwen-0.5b",
            "source": {
                "provider": "huggingface",
                "location": "https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct-GGUF"
            },
            "quantization": [
                "Q4_K_M"
            ],
            "gpuMemory": "4GB"
        }
    ],
    "runners": [
        {
            "name": "ACORN Research Runner",
            "repository": {
                "provider": "gitlab",
                "id": 24758,
                "uri": "https://code.ornl.gov/research-enablement"
            },
            "type": "group",
            "tags": ["acorn", "research"],
            "runUntagged": false
        }
    ]
}

.acorn.jsonc file

{
    // ACORN bucket configuration
    "buckets": [
        {
            "name": "bessd",
            "repository": {
                "provider": "gitlab",
                "id": 17603,
                "uri": "https://code.ornl.gov/research-enablement/buckets/bessd"
            }
        },
    ]
}

Tip

.jsonc files permit // line comments, /* block */ comments, and trailing commas. All other syntax follows standard JSON rules. Rename a .json file to .jsonc if you need comments. [!TIP] ACORN looks for .acorn.json, .acorn.jsonc, .acorn.yaml, .acorn.yml, then .acorn in the current working directory. The extensionless .acorn form uses JSONC. You can also specify a different configuration file using the --config <FILE> flag when running ACORN commands.

.env file and Environment Variables

The ACORN CLI tool can also be configured using .env files and/or environment variables.

Example

.env file

ACORN_LOG_LEVEL=info
READABILITY_METRIC=ari
MAX_ALLOWED_ARI=12

ACORN_CITATION_FORMAT selects the DOI citation family used by acorn gather --raw --resolve when --citation-format is not provided. Accepted case-insensitive values are apa, chicago, harvard, ieee, mla, and vancouver; IEEE is the default. The precedence is CLI option, environment variable, then IEEE. An unsupported environment value emits a warning and falls back to IEEE.

$env:ACORN_CITATION_FORMAT = "apa"
acorn gather report.pdf --raw --resolve

Commands

• ✅ Check
• 🏗️ Create
• 👨‍⚕️ Doctor
• 📥 Download
• 📤 Export
• 🤖 Format
• 🌾 Gather
• 📥 Import
• 🕸️ Link
• 📡 Serve
• 🧩 Skill
• 🧬 SWHID
• 🔄 Sync
• 🖥️ TUI

Command workflows

Research activity data

Persistent identifiers

Local AI And Agents

ACORN keeps its core research-data commands deterministic while offering optional tools for local AI and agent workflows:

• import model catalogs GGUF metadata without downloading weights.
• download model selects and downloads local GGUF weights.
• sync configures supported agent and inference applications to use those models.
• skill gives compatible AI agents ACORN-specific operating instructions.

✅ Check

In a Nutshell

Validate RAD structure, links, and prose with acorn check <PATH>.

Example Use

# Check a specific research activity index
acorn check path/to/project/index.json

# Check Markdown research activity data
acorn check path/to/project/index.md

# Check a Citation File Format file
acorn check path/to/project/CITATION.cff

# Check all research activity data in a directory
acorn check path/to/project/

# Check a remote document
acorn check https://example.org/project.json

HTTP and HTTPS inputs are downloaded to a temporary file and checked using the file extension in the URL. Remote inputs require network access and are rejected in global --offline mode.

ACORN recognizes .md and .markdown research activity files by their schema: acorn/research-activity YAML frontmatter discriminator. Legacy Markdown previously exported by ACORN is also accepted. Ordinary Markdown remains plain text and is not selected by RAD directory discovery.

Watch mode

Use the global --watch flag to run immediately and repeat the check whenever the effective input changes:

acorn --watch check path/to/project/
acorn check --watch --watch-mode poll https://example.org/project.json

--watch-mode auto uses native filesystem notifications for local inputs and polling for remote inputs, with polling as a fallback when native notifications fail. Use --watch-mode poll for network-mounted paths, containers, WSL-mounted paths, or other filesystems where native events are unreliable. Configure polling with --poll-interval (-p), such as --poll-interval 5s. Press q or Ctrl+C to stop watching.

Before checking, ACORN synchronizes the extensions used by the selected prose analyzer and tries up to three times when synchronization fails. Both one-shot and watch-mode checks use the configured --poll-interval between attempts; it defaults to one second. Watch mode does not repeat synchronization on later file changes. If all attempts fail, the check exits; use --ignore-sync-failure to let watch mode continue with locally available analyzer extensions instead. Use --skip prose to skip prose analyzer synchronization and analysis entirely.

Checking CITATION.cff

ACORN recognizes a directly supplied .cff file as Citation File Format (CFF) data. You do not need to select the standard explicitly:

acorn check ./CITATION.cff

Use --standard cff when CFF data is stored with a .yaml or .json extension:

acorn check ./citation.yaml --standard cff

For CFF input, ACORN checks:

• Schema: Parses the YAML or JSON, rejects unknown fields, and validates modeled values such as dates, DOIs, URLs, identifiers, licenses, and nested author or reference data.
• Prose and readability: Analyzes the title, abstract, and message text.
• Links: Checks repository, license, landing-page, DOI, URL identifier, and reference links.

Link checks require network access. Use acorn --offline check ./CITATION.cff or --disable-website-checks to skip them.

Note

Directory and Git-change discovery currently select .json, .jsonc, and .yaml files, but not .cff files. Pass each CITATION.cff path directly.

Check Categories

• 🏛️ Schema Validation: Ensure that all data files conform to the expected schema
• ✨ Prose Quality: Analyze written content for standards such as grammar, spelling, and word counts
• 👓 Readability: Evaluate readability of written content using established metrics¹
• 🔗 Link Integrity: Verify all hyperlinks within the content are valid and reachable
• 📊 Data Consistency: Check for dataset consistency and completeness
• 🚦 Convention Adherence: Ensure compliance with naming conventions and organization-specific standards

Customization Options

The check command supports several flags and options to customize its behavior (e.g., skipping certain checks, disabling certain behaviors, etc.)

Include --exit-on-first-error to stop execution upon encountering the first error.

Bypass verifying the checksum of downloaded artifacts with --skip-verify-checksum²

Skip Checks

• --skip schema : Skip schema validation checks
• --skip prose : Skip prose quality checks
• --skip readability : Skip readability checks
• --skip schema,prose : Skip both schema validation and prose quality checks (this works for any combination of categories)
• --disable-website-checks : Disable all website-related checks (link integrity, etc.)

Note

--disable-website-checks is redundant when acorn --offline is used for commands that need to be run in offline environments.

Configure Readability

Readability can be configured for desired metric and level by passing options directly to the command line or via a .env file. Command line options override .env settings.

• --readability-metric <METRIC> : Specify which readability metric to use
• Set READABILITY_METRIC in your .env file to choose the readability metric. Default metric is fkgl (Flesch-Kincaid Grade Level).
• Set MAX_ALLOWED_FKGL in your .env file to define the maximum acceptable FKGL score. Each metric has its own corresponding maximum score variable (e.g., MAX_ALLOWED_ARI for Automated Readability Index).

Example .env file

Configure ACORN to use the Coleman-Liau Index (CLI) readability metric with a maximum allowed score of 14.0 (default value is 12.0):

READABILITY_METRIC=cli
MAX_ALLOWED_CLI=14.0

Next stop: Normalize a checked record with Format.

1. See the readability module documentation for a full list of available readability metrics. ↩

2. ⚠️ Skipping checksum verification may expose you to security risks. Use this option with caution. ↩

🏗️ Create

In a Nutshell

Create an ACORN-backed runner or bot with acorn create <RESOURCE>.

Runner and bot creation are available:

# Register and start a GitLab runner from ACORN configuration
acorn create runner --config ./.acorn.json

# Create a runner directly for a GitLab group
acorn create runner --group 12345 --name research-runner

# Create a detached bot container for a GitLab project
acorn create bot 12345 --detach

Runner creation supports Docker, Podman, and Apptainer selection with --runtime. A remote Docker daemon can be selected with --remote; volumes and published ports then belong to the remote host.

Run acorn create <resource> --help for the exact authentication, runtime, and network options.

The CLI currently lists acorn create mcp, but that path returns an explicit “not yet implemented” error. Use serve bot or the supported runner and bot creation paths above.

Next stop: Run the bot you created with Serve.

👨‍⚕️ Doctor

In a Nutshell

Inspect the host environment and capture a support report with acorn doctor.

Start broad, then narrow the diagnostic category:

acorn doctor
acorn doctor --check software
acorn doctor --check system,memory,network
acorn doctor --report > acorn-doctor.json

--fix is exposed by the CLI but currently returns an “Autofix is not implemented yet” error. --fix --interactive opens the Doctor screen when ACORN was built with TUI support; use the diagnostic and report commands above for non-interactive environments.

Rescue: ACORN cannot find Chrome

PDF export needs Chrome or Chromium. Point ACORN at an existing executable instead of relying on automatic discovery:

# Linux
acorn --offline export index.json --format pdf \
  --chrome-path /usr/bin/google-chrome-stable

# macOS
acorn --offline export index.json --format pdf \
  --chrome-path "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

On Windows, pass the executable path with --chrome-path or set CHROME_PATH. Connected export can download ACORN’s pinned browser; offline export needs a configured, installed, or already cached browser. See Chrome selection.

Rescue: offline mode unexpectedly fails

Global --offline forbids network reads; it does not turn remote inputs into local ones. Check these common causes:

1. Replace HTTP(S) inputs and model-list URLs with local paths or file:// URIs.
2. Use check --skip prose if analyzer extensions have not already been synchronized.
3. Configure --chrome-path or cache the pinned browser before offline PDF export.
4. Do not combine gather --resolve, gather --merge-request, or gather --osti with offline mode.

Run the failing command with -vv to expose the resource ACORN attempted to resolve.

Rescue: a model sync target is not detected

With no target flags, acorn sync selects applications whose commands it detects. Request a target explicitly to make the decision visible:

acorn sync --vscode --dry-run
acorn sync --vscode --force --dry-run

--force bypasses command detection only for targets you explicitly include. If the application is detected but weights are elsewhere, set --models-dir; use --assume-models only when another system guarantees those paths exist. Continue with the Sync troubleshooting guide.

Next stop: Preview application routing with Sync.

📥 Download

In a Nutshell

Fetch bucket content or local-model weights with acorn download <SOURCE>.

• See the configuration documentation for details on configuring ACORN commands.
• By default, download will save files to ./content in the working directory unless an output path is specified via the --output flag.

Example Usage

# Download research activity data from a single bucket repository URL
acorn download https://code.ornl.gov/research-enablement/buckets/nssd

# Download research activity data from a list of buckets
acorn download --config /path/to/.acorn.json

# Download research activity data to a specific output directory
acorn download --config /path/to/.acorn.yml --output /path/to/output

# Download selected files directly beneath the output directory
acorn download https://github.com/example/project --filter '^examples/quest/' --flatten --output ./quest

# Replace selected paths that already exist in the output directory
acorn download https://github.com/example/project --output ./content --clobber

# Download using JSONC configuration (supports comments and trailing commas)
acorn download --config /path/to/.acorn.jsonc

Buckets

After a bucket transfer, ACORN ingests transferred JSON, JSONC, YAML, YML, and recognized Markdown research activity files into the local research_activities table. Unrelated Markdown documentation is ignored. Each row has a portable NanoID and retains the typed RAD JSON plus provenance for the bucket, repository, relative path, and observation time. Exact DOI, RAiD, ISBN, and patent metadata identities are used when present; a repository-qualified RAD identifier always identifies the transferred activity.

Repeated transfers are idempotent. A matching candidate gains missing fields and unique array values, while conflicting populated fields remain unchanged and are recorded as provenance. Filters and ignore rules apply before transfer, so only transferred RAD files are ingested.

Use --flatten to discard repository directory components and save every selected file as a direct child of the output directory. Filters and ignore rules continue to match the original repository-relative paths. If multiple selected paths have the same filename, the command fails.

By default, a bucket transfer also fails rather than overwrite an existing destination. Add --clobber to replace files, symlinks, or directories that conflict with selected output paths. ACORN obtains the replacement content before removing an existing destination, preserves unrelated contents beneath the output directory, and does not clear the output directory itself. This flag applies only to bucket downloads; the model subcommand’s existing --force flag retains its synchronization-specific meaning.

If a transferred RAD file cannot be parsed or persisted, the files already written to the output directory are preserved and the command fails. Global --no-local-database performs the transfer but skips RAD parsing and candidate persistence.

# Transfer bucket files without creating or updating local candidates
acorn --no-local-database download --config /path/to/.acorn.json

Local vs Remote

Top-level download accepts remote bucket repositories only and requires online mode. Use acorn import for local directories, local bucket entries in configuration, and offline local transfers. This policy does not apply to download model, which retains its documented local-file and offline behavior.

"buckets": [
    {
        "name": "test (local)",
        "repository": {
            "provider": "git",
            "location": "file:./tests/fixtures/data/bucket/"
        }
    },
    {
        "name": "nssd (remote)",
        "repository": {
            "provider": "gitlab",
            "location": {
                "scheme": "https",
                "uri": "https://code.ornl.gov/research-enablement/buckets/nssd"
            }
        }
    }
]

GitLab vs GitHub

The download command supports both GitLab and GitHub remote repositories for ACORN buckets. The configuration for each is similar, with the main difference being the provider field in the repository object.

"buckets": [
    {
        "name": "ccsd (gitlab)",
        "repository": {
            "provider": "gitlab",
            "id": 17410,
            "uri": "https://code.ornl.gov/research-enablement/buckets/ccsd"
        }
    },
    {
        "name": "test (github)",
        "repository": {
            "provider": "github",
            "uri": "https://github.com/jhwohlgemuth/bucket"
        }
    }
]

Models

Download model weights for use with ACORN research harnesses and local inference. By default, ACORN selects GGUF model files from Hugging Face repositories and prefers the Q4_K_M quantization. Python, pip, or the hf tool are not required.

For complete metadata-import options, configuration examples, authentication, and database behavior, see Import model.

# Import GGUF file metadata without downloading weights
acorn import model openai/gpt-oss-20b --search-limit 20

# Import metadata for repositories listed in a local or remote document
acorn import model --model-file https://example.org/models.json

# Download models listed in a local or remote document
acorn download model --model-file https://example.org/models.json

# Select an exact quantization that fits in available GPU memory
acorn download model openai/gpt-oss-20b --quantization Q4_K_M --gpu-memory 24GB

# Download default GGUF (Q4_K_M) from a Hugging Face repo
acorn download model meta-llama/Llama-3.1-8B

# Download model weights into a specific local directory
acorn download model meta-llama/Llama-3.1-8B --local-dir ./models

# Download a specific quantization
acorn download model meta-llama/Llama-3.1-8B --quantization Q8_0

# Exclude low-quality quantizations
acorn download model meta-llama/Llama-3.1-8B --ignore "Q2_|Q3_|imatrix"

# Download models from a config file
acorn download model --config .acorn.json

Use --model-file to load model IDs from a local path, file:// URI, or HTTP(S) URL. Plain-text lists and JSON/YAML lists of IDs or model details are accepted. Positional models, entries from --model-file, and supported --config entries are combined and deduplicated before download. Remote model-list documents cannot be loaded with --offline.

Pass --sync to add the unique model identifiers resolved by this invocation to the ACORN configuration’s models list and to both OpenCode and llama-swap configuration. Existing ACORN model entries are preserved and duplicate identifiers are omitted. Use --sync opencode or --sync llama-swap to select one inference target:

acorn download model openai/gpt-oss-20b --sync
acorn download model openai/gpt-oss-20b --sync opencode
acorn download model openai/gpt-oss-20b --sync llama-swap

--dry-run continues to avoid model downloads and prints ACORN and target-configuration diffs without writing them when combined with --sync. Only models already available in the selected output/models directory can appear in the inference-configuration diffs by default. Add --force to skip this existence check and assume each model is located at <models-dir>/<model-id>:

acorn download model openai/gpt-oss-20b --sync --dry-run --force

Inline --sync is additive and operates only on models resolved by the current download. The standalone acorn sync command remains the full reconciliation operation for every model in ACORN configuration, including target-path and models-directory overrides, independent dry runs, and removal of stale ACORN-managed entries with --prune.

Metadata import resolves the configured revision, records each GGUF file URL, quantization, and byte size, and inspects a selected fallback GGUF repository when the base repository is unavailable or has no GGUF files. It does not transfer model weights or checksum sidecars. --quantization is an ordered, comma-separated exact allowlist. When only --gpu-memory is supplied, ACORN evaluates Q4_K_M. Split shards are treated as one variant and their sizes are summed.

Detailed configuration entries can set the same constraints:

{
    "models": [{
        "name": "gpt-oss",
        "source": {
            "provider": "huggingface",
            "location": "https://huggingface.co/openai/gpt-oss-20b"
        },
        "quantization": ["Q5_K_M", "Q4_K_M"],
        "gpuMemory": "24GB"
    }]
}

OCI Model Artifacts

Explicit oci:// references download model artifacts from any OCI Distribution-compatible registry, including Harbor. ORAS 1.3.0 or newer must be installed and available on PATH; acorn doctor --check software reports its availability. Unqualified owner/repository values remain Hugging Face selectors.

# Resolve a tag and preview its immutable digest and selected files
acorn download model oci://savannah.ornl.gov/models/gpt-oss:20b --dry-run

# Pull an immutable artifact digest
acorn download model oci://registry.example.org/ai/models/qwen@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Tags are resolved during planning. Dry-run and raw output include the requested reference, resolved SHA-256 manifest digest, artifact type, selected files, and total size. Downloads pin the resolved digest, use ORAS digest verification, stage into a unique sibling directory, validate every materialized path, and publish with one rename. A non-empty existing destination is rejected. --skip-verify-checksum does not disable OCI descriptor verification.

ACORN accepts OCI artifact manifests whose files have safe org.opencontainers.image.title annotations and recognized model/config/tokenizer filenames. It also accepts KitOps ModelKits, including manifests that omit the optional top-level mediaType; ACORN reads the ModelKit config, fetches only its declared gzip-compressed model layer, and safely extracts the declared GGUF, SafeTensors, ONNX, or PyTorch model file. Ordinary runnable container images, unrecognized missing titles, absolute or traversal paths, unsupported files, symbolic links, and malformed digests are rejected. Digest integrity proves content identity; it does not authenticate the publisher or replace a future signature policy.

Custom Harbor endpoints

Use an explicit oci:// reference for a model in any Harbor registry. A named registry profile is optional for public artifacts, but enables Harbor metadata and registry-specific authentication or TLS settings. ORNL’s Savannah Harbor instance is one example:

# Inspect the tag, resolved digest, Ollama-store files, and total transfer size
acorn download model oci://savannah.ornl.gov/models/gpt-oss:20b --dry-run --raw

# Download into ACORN's digest-addressed model directory
acorn download model oci://savannah.ornl.gov/models/gpt-oss:20b --local-dir ./models

ACORN recognizes the extensionless blobs/sha256-* and manifests/... paths used by the Savannah model’s Ollama-store artifact. ACORN keeps the verified artifact in a registry/repository/digest-qualified directory so mutable tags cannot overwrite another resolution; the directory names are portable to Windows. Installing Ollama or Open WebUI and merging artifacts into an application’s own store are outside this command’s scope.

ORAS uses the normal Docker-compatible credential store by default. A named profile may instead identify a credential environment variable; ACORN passes that value through standard input and never places it in configuration, process arguments, or diagnostics. TLS verification stays enabled. Plain HTTP is allowed only by an explicit development profile.

{
    "registries": {
        "savannah": {
            "kind": "harbor",
            "endpoint": "https://savannah.ornl.gov",
            "credentialEnv": "ACORN_SAVANNAH_TOKEN"
        }
    },
    "models": [
        {
            "name": "gpt-oss-20b",
            "source": {
                "provider": "oci",
                "location": "oci://savannah.ornl.gov/models/gpt-oss:20b",
                "registry": "savannah"
            },
            "auth": "required"
        },
        {
            "name": "qwen-huggingface",
            "source": {
                "provider": "huggingface",
                "location": "Qwen/Qwen2.5-Coder-7B-Instruct-GGUF"
            }
        },
        "oci://ghcr.io/example/models/qwen:Q4_K_M"
    ]
}

The second entry continues to use the pre-OCI Hugging Face API. The final entry shows the simplified selector syntax for an OCI artifact that does not need a named registry profile.

Profiles also support username, registryConfig, caFile, paired clientCert/clientKey, and plainHttp. They intentionally have no password or token field. Harbor profiles enable its v2 artifact metadata API; content transfer always remains portable through ORAS. Global --offline rejects OCI access before ORAS or Harbor is contacted.

Command-line constraints override configuration. If neither constraint is present, download selection remains unchanged. With global --no-local-database, import reports metadata without persisting it and constrained downloads proceed with an eligibility-unknown warning.

Filter and Ignore Semantics

The --filter flag behaves as an include rule: only sources matching at least one pattern will be downloaded. The --ignore flag behaves as an exclude rule: sources matching any ignore pattern are excluded even if they match a filter pattern. Both flags accept regular expression patterns, not Hugging Face glob patterns. Simple patterns are automatically optimized to glob matching for Hugging Face repositories.

Note for Transformers/PyTorch Users

Users of Transformers or PyTorch typically need the full repository or a broader filter that includes config.json, tokenizer files, tokenizer_config.json, and optionally custom code files. The default GGUF-only filter is designed for llama.cpp inference.

Whitelists

A model whitelist restricts downloads to matching user-facing model names. ACORN uses the first non-empty whitelist source in this order: --whitelist or --whitelist-file, application configuration, then ACORN_MODEL_WHITELIST. The environment variable accepts comma-separated inline entries or one remote HTTP or HTTPS whitelist URI. An empty whitelist does not restrict downloads.

Use --whitelist-file to load a whitelist from a remote HTTP or HTTPS URI. For example, the following command allows the requested model only when it appears in the ORNL Research model catalog:

acorn download model openai/gpt-oss-20b --whitelist-file https://research.ornl.gov/api/models.json

The --whitelist option accepts inline model names; it does not fetch a URI supplied as its value.

Configure an inline whitelist with whitelist.models:

{
    "models": [
        "openai/gpt-oss-20b",
        "meta-llama/Llama-3.1-8B",
        "https://huggingface.co/Qwen/Qwen3-8B"
    ],
    "whitelist": {
        "models": [
            "openai/gpt-oss-20b",
            "https://huggingface.co/Qwen/Qwen3-8B"
        ]
    }
}

The models value in the whitelist object accepts either one string or an array of strings:

• One HTTP or HTTPS URL is treated as a remote whitelist document and fetched when the command runs.
• An array is treated as inline whitelist entries. Each string may be a model name, model ID, or model URL. URLs inside an array are entries and are not fetched as nested whitelist documents.
• One non-URL string is treated as one inline whitelist entry.

For example, this configuration loads the whitelist from a remote document:

{
    "models": [
        "openai/gpt-oss-20b",
        "meta-llama/Llama-3.1-8B"
    ],
    "whitelist": {
        "models": "https://example.org/acorn/models.json"
    }
}

The remote document may contain one model-details JSON object with a name or id:

{
    "name": "openai/gpt-oss-20b"
}

It may instead contain a JSON array of model names, IDs, or URLs:

[
    "openai/gpt-oss-20b",
    "meta-llama/Llama-3.1-8B",
    "https://huggingface.co/Qwen/Qwen3-8B"
]

An array of model-details objects is also accepted:

[
    {
        "name": "gpt-oss",
        "id": "openai/gpt-oss-20b"
    },
    {
        "id": "meta-llama/Llama-3.1-8B"
    }
]

For model-details objects, ACORN accepts both name and id as whitelist entries when both are present. At least one of these fields is required. YAML arrays and newline-separated plain-text entries are also supported.

Remote whitelist documents cannot be loaded with --offline. Use --whitelist-file <URI_OR_PATH> when the whitelist document is a local path or file:// URI. An explicitly supplied configuration path must exist; otherwise, ACORN reports Configuration file does not exist.

Next stop: Follow downloaded weights through the model workflow.

📤 Export

In a Nutshell

Turn one RAD source into a shareable artifact with acorn export <PATH> --format <FORMAT>.

This command allows you to export research activity data from ACORN into formats such as CFF, PDF, Markdown, YAML, or PPTX. With export, you can easily share your research with sponsors, collaborators, or the general public in a variety of contexts.

Markdown RAD is accepted as an input for the same RAD export targets as JSON and YAML. Exported Markdown uses YAML frontmatter with schema: acorn/research-activity; its generated ## ASPECT section includes nested data and model details.

export supports exporting individual research activity indices or entire directories containing multiple indices.

ACORN allows you to maintain research activity data as persistent, interconnected single sources of truth. As such, you can easily create a variety of output artifacts while ensuring consistency and accuracy across all selected formats.

Tip

You can see some export command results by visiting the ORNL Research Activity Index, which features a variety of research activity data presented in different formats.

Example Usage

# Export research activity data to PDF fact sheet
acorn export /path/to/index.json --format pdf

# Create PowerPoint presentations from all research activity data in a directory
acorn export /path/to/project/ --format powerpoint

# Create a CITATION.cff file from a research activity index
acorn export /path/to/project/index.json --format cff

Note

Most export formats use the --output option to specify the output file or directory path. If not provided, ACORN will generate a default output path based on the input path and selected format. For example, --format pdf and --format powerpoint will generate files in the default export location (./export/) with names based on the project parent folder(s), --format bag will add .zip to the output path (i.e., --output ./export will create ./export.zip and --output /path/to/bag will create /path/to/bag.zip). CFF output is the exception described below.

BagIt export supports 7z, ZIP, TAR, and TAR.GZ containers. A recognized --output suffix selects the format, while an output without an archive suffix defaults to ZIP. Use --archive-format 7z|zip|tar|tar.gz as an explicit override:

acorn export ./research --format bag --output ./deposit.tar.gz
acorn export ./research --format bag --output ./deposit.7z
acorn export ./research --format bag --archive-format tar --output ./deposit

An explicit format that conflicts with an output suffix is rejected. --archive-format is not accepted for non-BagIt exports.

Standard crosswalks

Use --to with JSON or YAML export to convert metadata between DataCite, DCAT, InvenioRDM, and HuWise. ACORN can infer the source standard from recognizable fields, but --from is recommended for repeatable scripts and for records with an ambiguous shape.

# Convert one DataCite JSON record to DCAT JSON
acorn export datacite.json --format json --from datacite --to dcat --output ./export

# Convert DCAT JSON to DataCite YAML
acorn export dataset.json --format yaml --from dcat --to datacite --output ./export

# Preview a directory conversion without writing files
acorn export ./metadata --format json --from invenio --to dcat --dry-run

The source and target may each be datacite, dcat, invenio, or huwise. Every pairing among those four standards is accepted. Some conversions use DataCite as an intermediate representation:

Crosswalk export has these constraints:

• The input and output must be JSON or YAML. PDF, PowerPoint, CFF, BagIt, and Markdown are not crosswalk targets.
• A single object or an array of objects is accepted. Directory export writes one target file for each resolved source file.
• Conversion can be lossy because the standards have different fields and cardinalities. Normal direct conversions report field-level crosswalk warnings when ACORN has a mapping for that pair.
• Warning collection is currently limited to direct DataCite mappings and DCAT → DataCite. Routed conversions can lose metadata without a complete end-to-end warning report.
• --strict is intended to fail when conversion loses data, but the current export path does not retain warnings in strict mode. Do not use it as a lossless-conversion guarantee until that behavior is corrected.
• CKAN package records are not currently a supported source or target standard. A CKAN API response is not DCAT merely because CKAN can expose DCAT through an extension; convert or export it to a supported DCAT representation before using --from dcat.

Run acorn check --standard <target> <output> after conversion when the target artifact must pass ACORN’s schema and validation checks.

Citation File Format (CITATION.cff)

Use --format cff to convert ACORN research activity data (RAD) into a CFF 1.2.0 citation file:

acorn export /path/to/project/index.json --format cff

The generated /path/to/project/CITATION.cff includes the RAD title, research purpose as the abstract, contact information as author and contact metadata, keywords, and DOI information when available. ACORN also supplies the CFF version and default citation message.

For CFF export:

• The input must be RAD in JSON, JSONC, YAML, or canonical/legacy ACORN Markdown. Existing .cff input is skipped because it is already in the target format.
• The output is always named CITATION.cff and written beside its source RAD file. --output does not relocate CFF output.
• ACORN generates at most one CITATION.cff per source directory. When several discovered RAD files share a directory, they resolve to the same output path and only one is exported.

Run acorn check /path/to/project/CITATION.cff after export to validate the generated citation metadata.

Chrome selection for PDF export

Use --chrome-path to select an installed Chrome or Chromium executable. CHROME_PATH provides the same setting through the environment, and an explicit command-line value takes precedence.

# macOS
acorn --offline export /path/to/index.json --format pdf \
    --chrome-path "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

# Linux
CHROME_PATH=/usr/bin/google-chrome-stable \
    acorn --offline export /path/to/index.json --format pdf

# Windows
acorn --offline export C:\path\to\index.json --format pdf `
    --chrome-path "$env:ProgramFiles\Google\Chrome\Application\chrome.exe"

When configured, this path is validated and used without checking ACORN’s browser cache or downloading Chrome. Without it, offline export uses the cached pinned browser when available and otherwise lets chromiumoxide detect an installed browser. Connected export retains the pinned browser download fallback.

PowerPoint Reference Template

Customize the PowerPoint export by providing a reference template using the --reference option. This allows you to define specific styles, layouts, and branding for your presentations.

acorn export /path/to/index.json \
    --format powerpoint \
    --reference /path/to/reference.pptx

The reference template allows you to specify which values are used and where, using placeholder text in the format {{ PLACEHOLDER_NAME }}. During export, ACORN will replace these placeholders with corresponding data from the associated research activity data. You can find an example PowerPoint reference template in the ACORN GitLab repository.

Available Placeholders

The following placeholders can be used in your PowerPoint reference template:

String values

• caption - First image caption
• challenge - Challenge description
• citation - DOI citation
• email - Contact email
• first - Contact first name
• focus - Research focus area
• last - Contact last name
• managers - Manager names (joined with "and")
• mission
• notes - Presentation notes (intended to be added PowerPoint speaker notes)
• partners - Partner names (joined with ", ")
• programs - Program names (joined with "and")
• subtitle
• title

Lists (bullet points)

• achievement
• areas - Research areas
• impact
• technical - Technical approach

Next stop: Practice the complete loop in the Quick Quest.

🤖 Format

In a Nutshell

Normalize RAD fields and controlled vocabulary values with acorn format <PATH>.

Example Usage

# Format a specific research activity index
acorn format path/to/project/index.json

# Format canonical or legacy Markdown RAD
acorn format path/to/project/index.md

# Format all research activity data in a directory
acorn format path/to/project/

# Preform dry-run to see proposed changes without modifying files
acorn format path/to/project/index.json --dry-run

Example Output

  meta:
    keywords:
-   - automatin
+   - automation
    technology:
-   - JavaScript
-   - TypeSpec
    - astro
+   - javascript
    - react
-   - rs
+   - rust
+   - typespec
    sponsors:
-   - DOD
+   - Department of Defense
    ...
  contact:
    jobTitle: Primary Investigator
    givenName: Jasdrey
    familyName: Wohlson
    email: me@example.com
-   telephone: '(123) 456-7890'
+   telephone: '123.456.7890'
    url: https://www.ornl.gov/staff-profile/jason-h-wohlgemuth
-   organization: GSHS
+   organization: Geospatial Science and Human Security Division
+   affiliation: National Security Sciences Directorate

Features

Markdown formatting rewrites the document into ACORN’s canonical representation. YAML frontmatter retains lossless structured metadata and ASPECT data, while the body contains the title, prose sections, research fields, contact details, and a generated ASPECT summary. This also upgrades Markdown produced by older ACORN releases.

• 🛠️ Auto-fixing: Automatically fix common inconsistencies in RAD structure and prose
• 🎨 Consistent Formatting: Ensure consistent JSON formatting across all data files
• 🩹 Resolve Values: Resolve certain values against controlled vocabularies to ensure correct meaning
• 🖼️ Resolve missing images: Find first image in associated RAD folders and add to metadata if missing

Resolved Values

• meta.keywords: Resolve keywords against ACORN Keywords Vocabulary
• meta.technology: Resolve technology against ACORN Technology Vocabulary
• meta.partners: Resolve partner names against ACORN Partners Vocabulary
• meta.sponsors: Resolve sponsor names against ACORN Sponsors Vocabulary
• contact.organization: Resolve organization name against a given org chart (currently only supports ORNL org chart)
• contact.affiliation: Resolve organization name against a given org chart (currently only supports ORNL org chart)

Examples

• Keywords: "ai" → resolves to "artificial-intelligence"
• Partners: "NREL" → resolves to "National Renewable Energy Laboratory"
• Technologies: "rs" → resolves to "rust"
• Sponsors: "Dept. of Energy" → resolves to "Department of Energy"

Next stop: Create a shareable artifact with Export.

🌾 Gather

In a Nutshell

Discover identifiers and candidate records from documents, URLs, or text with acorn gather <INPUT>.

Discover persistent identifiers in files, documents, URLs, standard input, and literal text.

Directory traversal

Directory inputs are searched recursively by default, including files in every descendant directory. When no input, --text, or standard input is supplied, gather recursively searches the current directory.

Use --max-depth to limit traversal. Direct children of an input directory have depth 1, grandchildren have depth 2, and so on. A depth of 0 processes no directory descendants but does not exclude explicitly supplied files.

# Search the complete directory tree
acorn gather path/to/project

# Search only files directly inside the directory
acorn gather path/to/project --max-depth 1

# Include one nested directory level
acorn gather path/to/project --max-depth 2

--filter and --ignore are applied to the paths found within the selected depth.

Other inputs

acorn gather report.docx
acorn gather --text "doi:10.1234/example hdl:10013/epic.10033"
printf 'https://ror.org/01qz5mb56' | acorn gather

Non-empty standard input is gathered automatically and can be combined with positional inputs. arXiv identifiers may use modern or legacy arXiv: forms or arxiv.org/abs/ and /pdf/ URLs. Remote URLs require network access. Global --offline mode rejects remote input and cannot be combined with --resolve.

Watch mode

Use the global --watch flag to run immediately and gather again only when effective source content changes:

acorn --watch gather path/to/project
acorn gather --watch --watch-mode poll https://example.org/report.json
acorn gather --watch --osti projects "ACORN"

--watch-mode auto uses native filesystem notifications for local-only inputs and polling for HTTP(S), resolved identifiers, DOE CODE searches, and merge-request selections. Use --watch-mode poll for network-mounted paths or environments where native events are unreliable. --poll-interval (-p) accepts durations such as 500ms or 5s. Press q or Ctrl+C to stop watching. Standard input cannot be replayed and is therefore rejected in watch mode; repeated --text values remain static inputs.

Output formats

Gather supports console, json, markdown, and yaml output. When --format is omitted, an interactive terminal receives a table containing only discoveries and remote provider matches; piped or file output uses JSON. Resolution checks are rendered separately using the same detailed format as acorn check. Use --terse to render compact checks without the discovery table. Warning and error states are visible by default, while -vv also shows informational transitions such as found, resolved, created, enriched, and unchanged.

Use --raw to print only the normalized identifiers, one per line, for piping to another command. Raw stdout remains machine-readable: check diagnostics are suppressed unless -v is present, and verbose diagnostics are written to stderr without a table. With --raw --resolve, arXiv and DOI lines become citations and ORCID lines become Given Family (https://orcid.org/...); other PID types retain their normalized form. Use --citation-format to select apa, chicago, harvard, ieee, mla, or vancouver. The CLI option takes precedence over ACORN_CITATION_FORMAT, and the default is IEEE. Unsupported environment values produce a warning and use IEEE; unsupported CLI values are rejected. Use -q or --quiet to suppress output.

acorn gather report.docx --format console
acorn gather report.docx --format yaml --output discoveries.yaml
acorn gather report.docx --terse
acorn gather report.docx --raw | sort -u
acorn gather report.docx --raw --resolve --citation-format apa

Resolved raw output remains machine-readable: successful values use one line each. Load or resolution failures retain a nonzero exit status; they are silent by default and are rendered to stderr when verbosity is enabled. A DOI without the selected citation style and an ORCID without public given/family or credit-name data falls back to its normalized identifier.

Research activity candidates

Unless global --no-local-database is set, ordinary gather appends every discovered identifier to discovery history and persists project-like discoveries as evolving research activity candidates. arXiv, DOI, RAiD, ISBN, patent, and ARK values can independently identify a candidate. arXiv revisions retain their versioned evidence but match the same unversioned candidate. Handle, ISNI, ORCID, ROR, PIDINST, unknown identifiers, and arbitrary URLs remain in the report and discovery history but do not create or merge candidates by themselves. Unstructured Handle discovery requires an explicit hdl: label or hdl.handle.net URL.

See the persistent identifier lifecycle for how ACORN finds, parses, validates, normalizes, classifies, and persists this evidence.

Candidates merge only when they share an exact normalized project identity. A new identity creates a row with a portable NanoID; one matching row gains missing fields and unique array values; repeated evidence is unchanged. Conflicting populated fields keep their stored value and record the observation as provenance. Evidence matching multiple rows is reported as a conflict without merging those rows.

Enrichment mapping

Enrichment is additive and evidence-driven. ACORN starts with the identifiers found locally or returned by the selected provider, calls only the resolvers applicable to that entity and URL, and maps explicitly asserted values into candidate fields. Identifiers are normalized before use; arrays are deduplicated; and websites are deduplicated by URL. Keywords and technologies are resolved to canonical values from ACORN’s embedded controlled vocabularies, including known aliases; values with no vocabulary match are omitted from the mapped candidate but remain in provider provenance when that source is persisted. At database persistence, a new scalar fills an empty field, while a conflict with an existing populated scalar preserves the stored value and records the new observation as provenance. Unmapped values are not coerced into unrelated fields. Failure of an optional ORCID, GitHub, or GitLab lookup leaves the original provider result intact.

RAiD organization classification is driven by the explicit organization role, not by the organization’s name. Funder maps to meta.sponsors; lead or other research organization, partner, contractor, facility, and other organization roles map to meta.partners. An organization carrying both funder and non-funder roles is represented in both lists. A single roleless organization is treated as the default lead organization and therefore as a partner; roleless entries in a multi-organization record are not classified. ACORN resolves a display name only when the ROR exists in its embedded sponsor or partner vocabulary. Otherwise, the normalized ROR remains in meta.ror without an invented name.

The persistent identifier lifecycle describes field precedence, identity matching, CFF intake, and provenance in more detail. JSON and YAML reports include each persisted candidate’s iid and action, plus created, enriched, unchanged, and conflicts totals under summary.candidates.

# Discover identifiers without writing discovery history or candidates
acorn --no-local-database gather --text "doi:10.1234/example" --format json

# Resolve supported metadata and create or enrich candidates
acorn gather report.docx --resolve --format yaml
acorn gather report.docx --raw --resolve

Candidates are internal evolving records. Database-backed candidate export and completeness scoring are not currently available.

DOE CODE searches

Use --osti to search DOE CODE for projects or to aggregate credited people and organizations from matching projects.

acorn gather --osti projects "ACORN"
acorn gather --osti people https://orcid.org/0000-0002-2057-9115
acorn gather --osti projects --organization ORNL --organization-role site-owner
acorn gather --osti organizations ORNL --all --format json
acorn gather --osti projects --lab ORNL --all

--lab restricts results to projects submitted by one of DOE’s 17 national laboratories. Laboratory acronyms are case-insensitive. It sets the organization role to site-owner and cannot be combined with --organization or --organization-role. Each persisted project candidate is enriched with the laboratory’s canonical ROR from ACORN’s partner and sponsor vocabularies.

DOE CODE searches return one page by default. --limit controls the upstream page size, --offset selects a later page, and --all retrieves every page sequentially. DOI and ORCID resolver URLs are normalized to the bare identifier expected by DOE CODE. --organization-role can restrict organization matching to site-owner, research, sponsor, contributor, or developer; the default matches any credited role.

Project matches create or enrich candidates using the DOE CODE project ID and DOI when available. Gather retains the project title and description, repository and related websites, sponsoring organizations, and research, contributing, and developing partner organizations. When the repository overtly uses github.com, gather queries the GitHub API for programming languages. A repository on the configured GitLab domain receives equivalent enrichment when GitLab credentials are available. Language names are recorded in meta.technology.

With --resolve, people searches enrich valid ORCID matches with the preferred name, public email, and institution data returned by the ORCID API; project repository links are checked and enriched with provider-reported languages when available. Canonical and additional provider links are also checked for liveness during this optional online stage. A failed lookup retains the original provider data. People and organization searches are report-only. Global --no-local-database keeps all DOE CODE results report-only.

OSTI mode treats positional inputs and --text values as direct queries rather than files or URLs. It requires network access and is incompatible with file filtering, merge-request gathering, and schema analysis options. With --resolve, project DOIs and person ORCIDs use the same raw rendering and structured resolution metadata as local discoveries.

Next stop: Validate a gathered candidate with Check.

📥 Import

In a Nutshell

Import local or remote research-content buckets and BagIt archives, or populate ACORN's model catalog.

Research content and BagIt archives

Use acorn import without a subcommand to transfer research content from a local directory, a remote repository, or a 7z, ZIP, TAR, or TAR.GZ BagIt archive:

acorn import ./local-bucket
acorn import https://github.com/example/research-data
acorn import https://example.org/deposit.tar.gz --output ./content
acorn import https://example.org/deposit.7z --output ./content

Archive type is inferred from a bounded content header. --archive-format 7z|zip|tar|tar.gz bypasses inference, which is useful for extensionless downloads. Extracted archives must contain valid BagIt metadata at their root or beneath one enclosing directory; their complete SHA-256 or SHA-512 payload manifest is verified before files are imported. Extraction rejects traversal paths, links, duplicate destinations, and writes through pre-existing symlink components.

--filter, --ignore, --flatten, and --clobber have the same transfer meaning as bucket download. --config loads bucket sources from an ACORN configuration. Offline import is accepted only when every selected source is local. The original archive URI is retained as transfer provenance.

Top-level acorn download remains for remote repository transfers and rejects local sources and offline operation. Model commands retain their own local and offline behavior.

Model metadata

acorn import model can populate the general model catalog or inspect selected Hugging Face repositories for GGUF metadata. Repository inspection records GGUF file URLs, exact quantizations, revisions, and byte sizes without downloading model weights or checksum sidecars.

Import the model catalog

Run the command without model selectors or a configuration file to populate the local database from the models.dev catalog:

acorn import model

If the model table is already populated, ACORN leaves the existing records in place.

Import selected Hugging Face models

Supply one or more Hugging Face repository IDs to inspect only those repositories:

acorn import model openai/gpt-oss-20b

# Comma-separated and space-separated repository IDs are accepted
acorn import model openai/gpt-oss-20b,Qwen/Qwen2.5-0.5B-Instruct-GGUF

Use --model-file to load repository IDs from a local path, file:// URI, or HTTP(S) URL:

acorn import model --model-file ./models.txt
acorn import model --model-file file:///path/to/models.yaml
acorn import model --model-file https://example.org/models.json

The document may be a newline-separated plain-text list, a JSON or YAML list of repository IDs, one model-details object, or a list of model-details objects. For minimal model details, id is preferred and name is used when id is absent:

[
    {
        "name": "gpt-oss",
        "id": "openai/gpt-oss-20b"
    },
    {
        "id": "Qwen/Qwen2.5-0.5B-Instruct-GGUF"
    }
]

For catalog records that declare open_weights or weights, ACORN uses explicit Hugging Face repository URLs from weights. When an open-weight record has no declared weight source, ACORN uses its id to search for a GGUF fallback, including when that ID is not itself a Hugging Face repository. Closed models and records with non-Hugging Face weight sources are skipped. Entries that still cannot resolve produce warnings without aborting the remaining catalog import. This allows catalogs containing both hosted and open-weight models to be used directly:

acorn import model --model-file https://research.ornl.gov/api/models.json

Positional repository IDs, entries from --model-file, and supported --config entries are combined and deduplicated before import.

Synchronize imported models

Pass --sync to add the unique model identifiers resolved by this invocation to the ACORN configuration’s models list and to both OpenCode and llama-swap configuration. Existing ACORN model entries are preserved and duplicate identifiers are omitted. Select one inference target with --sync opencode or --sync llama-swap:

acorn import model openai/gpt-oss-20b --sync
acorn import model openai/gpt-oss-20b --sync opencode
acorn import model openai/gpt-oss-20b --sync llama-swap

Import resolves and persists repository metadata; it does not download weights. Synchronization therefore adds only imported models whose GGUF files are already available in the configured models directory by default. Models without a resolvable local GGUF are reported and skipped.

Add --force to skip the local existence check and assume each imported model is located at <models-dir>/<model-id>:

acorn import model openai/gpt-oss-20b --sync --force

Use --dry-run without --sync to resolve and report model metadata without persisting it to the database:

acorn import model openai/gpt-oss-20b --dry-run

Combine --dry-run with --sync to also print ACORN and inference-configuration diffs without writing files:

acorn import model openai/gpt-oss-20b --sync --dry-run

Inline --sync is additive and operates only on models resolved by the current import. Use the standalone acorn sync command to reconcile every model in ACORN configuration, override target paths or the models directory, preview changes independently, or remove stale ACORN-managed entries with --prune.

When a repository has no GGUF files, ACORN searches for a GGUF repository derived from that model. Control fallback discovery with:

# Search at most 50 candidate repositories
acorn import model openai/gpt-oss-20b --search-limit 50

# Require GGUF files in the selected repository
acorn import model Qwen/Qwen2.5-0.5B-Instruct-GGUF --no-fallback

# Choose interactively when fallback discovery finds multiple candidates
acorn import model openai/gpt-oss-20b --interactive

The default search limit is 20 and can also be set with ACORN_SEARCH_LIMIT.

Import models from configuration

Use --config to inspect Hugging Face models listed in an ACORN configuration file:

acorn import model --config .acorn.json

A detailed entry can select a repository revision:

{
    "models": [{
        "name": "qwen-gguf",
        "source": {
            "provider": "huggingface",
            "location": "https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct-GGUF"
        },
        "revision": "main"
    }]
}

Individual model selectors must be Hugging Face repository identifiers. --model-file identifies a document containing selectors; it does not import a local weight file or a direct model-weight URL.

Database, authentication, and offline behavior

Use the global --database-path option to select the local database:

acorn --database-path ./acorn.db import model openai/gpt-oss-20b

With --no-local-database, selected repositories are still resolved and reported, but their metadata is not persisted. A catalog import without selectors is skipped:

acorn --no-local-database import model openai/gpt-oss-20b

For private or gated Hugging Face repositories, set HF_TOKEN, HF_API_TOKEN, or HUGGINGFACE_HUB_TOKEN. Global --offline mode rejects HTTP(S) model-list URLs and remote Hugging Face metadata import; local paths and file:// model lists can still be read.

Use imported metadata during download

After importing metadata, constrain the download by exact quantization and available GPU memory:

acorn import model openai/gpt-oss-20b --search-limit 20
acorn download model openai/gpt-oss-20b \
  --quantization Q4_K_M \
  --gpu-memory 24GB

See Download for download selection, filtering, split-shard sizing, and configuration details.

Next stop: Select model weights with Download.

🕸️ Link

In a Nutshell

Add linked-data context and create JSON-LD with acorn link <PATH>.

The link command augments user-input RAD with linked data context and outputs JSON-LD documents. This process involves mapping the input data to established ontologies and vocabularies, thereby enhancing its interoperability and depth of meaning.

ACORN helps prepare RAD for programmatic expansion. The link command makes input RAD machine-readable.

Tip

Linked Data creates a connected network of standards-based, machine-readable data across Web sites.

Example Usage

# Link a specific research activity index
acorn link path/to/project/index.json

# Create JSON-LD from Markdown RAD
acorn link path/to/project/index.md

# Link all research activity data in a directory
acorn link path/to/project/

Tip

The link command is almost identical to the format command, complete with support for the --dry-run flag to preview changes without creating files.

Example Output

    "contact": {
+     "@context": {
+       "jobTitle": "https://schema.org/jobTitle",
+       "givenName": "https://schema.org/givenName",
+       "familyName": "https://schema.org/familyName",
+       "identifier": "https://orcid.org",
+       "email": "https://schema.org/email",
+       "telephone": "https://schema.org/telephone",
+       "url": "https://schema.org/url",
+       "organization": "https://schema.org/worksFor",
+       "affiliation": "https://schema.org/affiliation"
+     },
+     "@type": "https://schema.org/person",
      "jobTitle": "Primary Investigator",
      "givenName": "Audson",
      "familyName": "Cargohlmuth",
      "email": "wohlgemuthjh@ornl.gov",
      "telephone": "865.576.7658",
      "url": "https://www.ornl.gov/staff-profile/jason-h-wohlgemuth",
      "organization": "Geospatial Science and Human Security Division",
      "affiliation": "National Security Sciences Directorate"
    }

Next stop: Turn linked RAD into an artifact with Export.

📡 Serve

In a Nutshell

Run an ACORN bot service with acorn serve bot <PROJECT_ID>.

Start a bot for a GitLab project:

acorn serve bot 12345
acorn serve bot 12345 --event-source webhook \
  --public-url https://bot.example.org --register-webhook

Bot event delivery can use polling, authenticated webhooks, or a hybrid of both. Use acorn serve bot --help to review bind, port, timestamp, polling, and webhook options before exposing the service.

The CLI currently lists acorn serve mcp, but the server path returns an explicit “not yet implemented” error. The bot server is the supported service path today.

Next stop: Diagnose the service host with Doctor.

🧩 Skill

In a Nutshell

Extract ACORN's bundled agent instructions with acorn skill.

acorn skill

The command writes the bundled SKILL.md into ACORN’s platform cache directory, prints its path, and attempts to copy agent instructions to the clipboard. A clipboard warning does not remove the extracted file; use the printed path when clipboard access is unavailable, such as in a headless session.

What The Skill Enables

The extracted skill gives compatible AI agents a current, task-oriented guide to ACORN’s schemas, commands, dry-run conventions, artifact checks, and offline behavior. It directs agents to verify syntax against the installed CLI or generated command help instead of inventing fields and flags.

acorn skill does not launch an agent, invoke a model, or grant access to files and services. It produces instructions that a user can load into a compatible agent under that agent’s existing permissions.

Next stop: Explore library integration on the Developer trail.

SWHID

In a Nutshell

Calculate or verify Software Hash Identifiers for local content with acorn swhid <PATH>.

Calculate or verify Software Hash Identifiers for local files, directories, and Git objects.

acorn swhid README.md --raw
acorn swhid ./src --kind directory
acorn swhid . --kind revision --reference HEAD
acorn swhid . --kind git-tree --reference HEAD
acorn swhid . --kind release --reference v1.0.0
acorn swhid . --kind snapshot

The default auto kind hashes a file as cnt or traverses a directory as dir. Git kinds use only objects already present in the repository: git-blob, git-tree, revision, release, and snapshot. Releases require annotated tags.

Use --verify to compare the calculated core object with an expected core or qualified SWHID:

acorn swhid README.md --verify swh:1:cnt:ce013625030ba8dba906f756967f9e9ca394464a

Calculation is read-only. It does not clone, fetch, materialize Git LFS, recurse into submodules, or hydrate partial clones. A filesystem directory represents current working-tree content; a Git tree represents committed state.

🔄 Sync

In a Nutshell

Route downloaded GGUF models into supported applications with acorn sync --dry-run.

acorn sync resolves model entries to GGUF files in the local models directory. With no target flags, it includes every application whose command is available: llama-swap, opencode, code, and goose. App-specific flags form an inclusion set, so --opencode --vscode includes both OpenCode and VS Code. Every included target must have its command available unless it was explicitly included alongside --force; --force without app-specific flags does not bypass command detection. Use --assume-models separately to skip model filesystem verification.

Unless overridden, llama-swap configuration is written to ~/.config/llama-swap/config.yaml. OpenCode uses an existing project or user opencode.jsonc/opencode.json configuration when available and otherwise writes ~/.config/opencode/opencode.jsonc. VS Code writes Code/User/chatLanguageModels.json beneath the platform configuration directory. Goose writes ~/.config/goose/config.yaml on macOS/Linux or %APPDATA%\Block\goose\config\config.yaml on Windows. Override those paths with --vscode-config and --goose-config.

VS Code receives a customendpoint provider using the Chat Completions API. Goose receives an active openai provider and the OPENAI_HOST and OPENAI_BASE_PATH settings; because Goose selects one active model, config.goose.defaultModel chooses it and otherwise the first synchronized model is used. Existing unrelated providers and settings are preserved. See the VS Code custom endpoint reference and Goose configuration guide.

config:
  vscode:
    path: ./chatLanguageModels.json
    url: http://localhost:8080/v1/chat/completions
    providerName: Local (llama-swap)
    maxInputTokens: 28672
    maxOutputTokens: 4096
  goose:
    path: ./goose.yaml
    host: http://localhost:8080
    basePath: v1/chat/completions
    defaultModel: acme/model

Generated llama-swap configuration follows the gold base configuration: health-check, proxy, and macro defaults are added when absent, and model commands enable its offline/tool-use launch profile. Existing root settings and per-model proxy values are preserved. Explicit extraArgs replace matching launch-profile options. Generated filesystem paths use the platform’s native form.

Model lists

Use --model-file to load model IDs from a local path, file:// URI, or HTTP(S) URL. Plain-text lists and JSON/YAML lists of IDs or model details are accepted:

acorn sync --model-file ./models.txt
acorn sync --model-file file:///path/to/models.yaml
acorn sync --model-file https://example.org/models.json

Entries from --model-file are combined with models from --config. Remote model-list documents cannot be loaded with global --offline mode.

Synchronization only includes models whose downloaded GGUF files can be resolved in --models-dir or the configured models directory by default. Unresolved entries are reported and skipped.

Use --assume-models to skip filesystem verification and assume each model is located at <models-dir>/<model-id>. For example, acme/model resolves to <models-dir>/acme/model:

acorn sync --model-file ./models.txt --assume-models

Preview changes

Use --dry-run to print configuration diffs without writing files:

acorn sync --model-file ./models.txt --dry-run

Use --prune to remove stale ACORN-managed models from the selected target configurations.

Next stop: See how every model stage connects in Model workflows.

🖥️ TUI

In a Nutshell

Open ACORN's interactive terminal workspace with acorn tui.

acorn tui

# Equivalent global shortcut
acorn --interactive

The TUI uses the configured local database and respects global database and offline options:

acorn --database-path ./acorn.db --offline tui

Use command mode instead when scripting or when the installed build does not include TUI support.

Next stop: Browse every automation path in the command reference.

Model workflows

ACORN separates model metadata, model files, and inference configuration into three operations. Choose the command based on the state you want to change:

Import and download accept positional model entries. All three commands can use configured entries and accept --model-file for a local path, file:// URI, or HTTP(S) document containing model IDs or model details.

Import metadata without downloading

Use import model to learn what GGUF files and quantizations are available, record that metadata in ACORN’s database, or find a GGUF fallback for a repository that does not provide one directly:

acorn import model openai/gpt-oss-20b
acorn import model --model-file ./models.json

Import does not transfer model weights. This makes it useful for catalog maintenance and for checking model availability before deciding what to download.

Add --dry-run to resolve and report metadata without writing to the local database. This does not require --sync.

Download model files

Use download model when the desired result is a local GGUF file. Download can constrain selection by quantization, GPU memory, filters, or whitelists:

acorn download model openai/gpt-oss-20b --quantization Q4_K_M
acorn download model --model-file ./models.json --gpu-memory 24GB

The command resolves metadata as part of the download, so a separate import is optional. Import first when you want to inspect or persist metadata independently.

Synchronize inference configuration

Use sync when model files are already present and OpenCode, VS Code, Goose, or llama-swap configuration needs to reflect ACORN’s model list:

acorn sync
acorn sync --model-file ./models.json --opencode
acorn sync --model-file ./models.json --llama-swap
acorn sync --model-file ./models.json --vscode
acorn sync --model-file ./models.json --goose

Standalone sync performs full reconciliation and supports target-path and models-directory overrides. Add --prune when stale ACORN-managed entries should be removed. Use --dry-run to preview configuration diffs without writing files:

acorn sync --dry-run
acorn sync --prune --dry-run

By default, synchronization includes only models whose local GGUF files can be resolved. --force skips that check and assumes each model exists at <models-dir>/<model-id>. This is useful when preparing configuration before files are mounted or copied, but the generated paths are not verified.

Download or import and sync in one step

Both model commands offer inline synchronization for the models resolved by that invocation. Inline sync also adds their identifiers to the ACORN configuration’s models list, preserving existing entries and omitting duplicate identifiers:

# Download weights, then add the downloaded models to supported configurations
acorn download model openai/gpt-oss-20b --sync

# Import metadata, then configure a model that will exist at the assumed path
acorn import model openai/gpt-oss-20b --sync --force

# Preview the configuration update without downloading or writing configuration
acorn download model openai/gpt-oss-20b --sync --dry-run --force

Inline --sync is additive and limited to the current import or download. --dry-run previews both the ACORN configuration update and inference-configuration updates without writing files. Use standalone acorn sync for repeated reconciliation of the complete configured model list, custom target paths, or pruning.

Which command should I use?

• To inspect or catalog model metadata without downloading weights, use import model.
• To place GGUF weights on this machine, use download model.
• To update inference configuration for models that are already present, use sync.
• To download and configure selected models in one invocation, use download model --sync.
• To prepare configuration before model paths exist, add --force, preferably with --dry-run first.

See Import, Download, and Sync for all command-specific options.

📦 Packages

To enable broad adoption of ACORN, we provide packages for multiple popular programming contexts.

graph LR
    A["acorn-lib</br>(Rust crate)"] -->|"&nbsp;is dependency of&nbsp;"|B["acorn-cli</br>(Rust crate)"]
    A -->|"generates</br>&nbsp;bindings for&nbsp;"|C["acorn-py</br>(Python package)"]
    A -->|"checks a portable</br>&nbsp;API subset for&nbsp;"|D["wasm32-unknown-unknown</br>(development target)"]

🦀 Rust crate

The ACORN CLI application is built on top of the acorn-lib Rust crate. The acorn-lib library provides core functionalities for working with ACORN schemas, processing persistent identifiers through their lifecycle, and generating artifacts.

AI And Agent APIs

The library also provides building blocks for optional AI-enabled applications:

• acorn::schema::agent models language models, providers, benchmark harnesses, prompt files, and agent-oriented OpenCode configuration.
• Embedded prompt templates support summarization, translation, teaching, claim extraction, and gap finding.
• acorn::io::api::openai provides a client for completions, chat completions, responses, embeddings, model discovery, and related operations using supported OpenAI-style HTTP endpoints and JSON formats. It can call OpenAI’s service or another compatible server, including a local one such as llama-swap; “OpenAI-compatible” describes the connection format, not the model provider.

These APIs complement ACORN’s deterministic schema and artifact workflows; applications decide when and how a model is invoked.

Important

When ACORN validates a PID, it does not rely only on recognition patterns. It also validates parsed structure and, for ISBNs¹, ISNIs², ORCIDs³, and RORs⁴, the check digits implemented for that identifier. Validation is local and does not confirm registration with an external authority.

The PID regression tests maintain shared test-vector parity with Metadata Tools for arXiv, DOI, ISBN, ISNI, ORCID, RAiD, and ROR, and with idutils for ARK, arXiv, DOI, Handle, ISBN, ISNI, ORCID, RAiD, ROR, and SWHID. This parity applies to the listed overlapping cases, not every behavior or identifier family supported by those projects.

Installation

• Add acorn-lib as a dependency⁵

  cargo add acorn-lib
  

• Use acorn-lib functions in your Rust code

  #![allow(unused)]
  fn main() {
  use acorn::schema::validate::{is_ark, is_arxiv, is_doi, is_isni, is_orcid, is_ror};
  
  assert!(is_ark("ark:/1234/w5678").is_ok());
  assert!(is_arxiv("arXiv:2106.09685").is_ok());
  assert!(is_doi("10.11578/dc.20250604.1").is_ok());
  assert!(is_isni("https://isni.org/isni/0000000492299539").is_ok());
  assert!(is_orcid("https://orcid.org/0000-0002-2057-9115").is_ok());
  assert!(is_ror("01qz5mb56").is_ok());
  }

• If you want to use the full capability of acorn-lib to build your own CLI app, be sure to enable the doctor and powerpoint features⁶

  cargo add acorn-lib --features doctor,powerpoint
  

1. ISBN ↩

2. ISNI ↩

3. ORCID ↩

4. ROR ↩

5. Check crates.io for the latest version ↩

6. See the Cargo.toml for more details. ↩

🐍 Python Bindings

ACORN seeks to meet scientists where they are in all aspects. This includes the programming languages they use. The acorn-py package provides Python bindings to the core ACORN functionalities provided by the acorn-lib Rust crate.

Installation

• See the PyPI page for installation and usage instructions
• Use acorn-lib functions in Python

  from acorn.schema.validate import is_ark, is_arxiv, is_doi, is_orcid, is_ror
  
  assert is_ark("ark:/1234/w5678")
  assert is_arxiv("arXiv:2106.09685")
  assert is_doi("10.11578/dc.20250604.1")
  assert is_orcid("https://orcid.org/0000-0002-2057-9115")
  assert is_ror("01qz5mb56")
  

Working with scientific artifact identifiers

The acorn-py package provides tools to work with common scientific artifact identifiers such as DOIs, arXiv identifiers, ARKs, ORCIDs, and RORs and other indirectly related identifiers such as patent numbers and books (e.g., ISBNs). You can validate these identifiers, work with their components, and even extract them from text.

Tip

Start with the persistent identifier lifecycle, then see the acorn-lib PID API for type-level details.

Example

Find all patent numbers in a string

🐍 Python

from acorn.schema.pid import Patent

text = "The patent number for my work is US1234567B1."
values = Patent.find_all(text)
patent = values[0]

assert str(patent) == "US 1234567 B1"
assert patent.country_code == "US"
assert patent.serial_number == "1234567"
assert patent.kind_code == "B1"

🦀 Rust

#![allow(unused)]
fn main() {
use acorn::schema::pid::Patent;

let text = "The patent number for my work is US1234567B1.";
let values = Patent::find_all(&text);
let patent = values[0];

assert_eq!(patent.to_string(), "US 1234567 B1");
}

API Consistency

The acorn-py API strives to adhere to the Rust API as closely as possible. If you know acorn-lib, you know acorn-py.

Validate DOIs

🦀 Rust

#![allow(unused)]
fn main() {
use acorn::schema::validate::is_doi;

assert!(is_doi("10.11578/dc.20250604.1").is_ok());
}

🐍 Python

from acorn.schema.validate import is_doi

assert is_doi("10.11578/dc.20250604.1")

Find all DOI values in a string

🦀 Rust

#![allow(unused)]
fn main() {
use acorn::schema::pid::{DOI, PersistentIdentifier, PersistentIdentifierParse};

let pid = "https://doi.org/10.11578/dc.20250604.1";
let text = format!("The DOI for ACORN is: {pid}");
let values = DOI::find_all(&text);
assert_eq!(values[0].identifier(), "10.11578/dc.20250604.1");
}

🐍 Python

from acorn.schema.pid import DOI

pid = "https://doi.org/10.11578/dc.20250604.1"
text = f"The DOI for ACORN is: {pid}"
values = DOI.find_all(text)
assert values[0].identifier == "10.11578/dc.20250604.1"

WebAssembly development

ACORN’s portable Rust surface can be checked for the wasm32-unknown-unknown target. This is currently a portability build for contributors, not a published JavaScript or browser package.

Important

make wasm runs cargo check. It verifies that the portable feature path compiles, but it does not link a .wasm artifact or generate JavaScript bindings.

Installation

Install the Rust toolchain and add the WASM target:

rustup target add wasm32-unknown-unknown

Clone the ACORN repository, then run the check from its root:

make wasm

The equivalent Cargo command is:

cargo check -p acorn-lib --no-default-features --features wasm --target wasm32-unknown-unknown

Rust projects that compile to WASM can select the same ACORN surface:

cargo add acorn-lib --no-default-features --features wasm

Currently available functionality

The WASM build exposes Rust APIs that operate on supplied in-memory values. It currently includes:

Schema types implement their normal Serde, JSON Schema, and validation traits in this configuration. Callers provide the strings, bytes, or already-deserialized values; ACORN does not fetch or read them in the WASM build.

For example, a Rust component compiled to WASM can use ACORN’s identifier validation directly:

#![allow(unused)]
fn main() {
use acorn::schema::validate::{is_arxiv, is_doi, is_isni, is_orcid, is_ror};

assert!(is_doi("10.11578/dc.20250604.1").is_ok());
assert!(is_arxiv("arXiv:2106.09685").is_ok());
assert!(is_isni("https://isni.org/isni/0000000492299539").is_ok());
assert!(is_orcid("https://orcid.org/0000-0002-2057-9115").is_ok());
assert!(is_ror("https://ror.org/01qz5mb56").is_ok());
}

What the check covers

The current wasm feature selects allocation-capable APIs without enabling ACORN’s native filesystem, process, terminal presentation, database, or network services. The check protects that dependency boundary on a browser-compatible compilation target.

The check does not currently provide:

• wasm-bindgen JavaScript bindings
• an npm package
• browser HTTP or storage adapters
• a supported browser application entry point
• native file or URL reads and writes
• analyzer, document conversion, database, process, download, or doctor services
• std-only agent definitions and embedded agent assets

Those capabilities are planned for a dedicated acorn-wasm adapter crate. Portable crates will remain independent of browser-specific dependencies, and acorn-wasm will compose supported ACORN services with browser implementations.

macOS sandbox warnings

Restricted macOS environments may report that xcrun could not create a cache file while locating MacOSX.sdk. This is a host toolchain warning rather than a WASM compilation failure. If Cargo prints Finished and the command exits successfully, the portability check passed.

Maintainer references

The public guide documents supported developer behavior. Implementation status and architectural decisions are tracked in the internal WASM feature path and no-std/WASM CI plan.