Develop

.Rbuildignore

@@ -21,3 +21,5 @@
 ^.repomixignore$
 ^noclocksai.code-workspace$
 repomix.config.json
+^CLAUDE\.md$
+^R/temp$

.Rprofile

@@ -0,0 +1,9 @@
+if (file.exists(".Renviron")) {
+  readRenviron(".Renviron")
+}
+
+if (require(acquaint)) {
+  acquaint::mcp_session()
+  acquaint::mcp_set_tools(btw::btw_tools())
+  cli::cli_alert_info("MCP session started.")
+}

.editorconfig

@@ -1,3 +1,6 @@
+# http://editorconfig.org
+root = true
+
 [*]
 indent_style = space
 indent_size = 2

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# .github/FUNDING.yml
+github: [noclocks, jimbrig]
+custom: ["https://www.paypal.me/noclocks", "https://pay.noclocks.dev/b/7sI5o93U4gng9gs5kl"]

.github/copilot-instructions.md

@@ -0,0 +1,19 @@
+# Copilot Instructions
+
+## Instruction Files
+
+Instructions are split out into multiple files for application across different contexts and use cases:
+
+- [Project Wide Instructions](instructions/project.instructions.md)
+- [Terminal Instructions](instructions/terminal.instructions.md)
+- [R Coding Instructions](instructions/r.instructions.md)
+- [Context and Memory Instructions](instructions/context.instructions.md)
+- [Tool Use Instructions](instructions/tools.instructions.md)
+
+## General Guidelines
+
+- Work incrementally by completing small, focused tasks.
+- Leverage your memory and sequential thinking for performing tasks and ensuring you have the necessary context.
+- Utilize available tools and resources effectively to enhance your productivity.
+- After completing a task, take a moment to reflect on what you've learned and how it can be applied to future tasks,
+  then update your memory with this knowledge.

.github/instructions/code.instructions.md

@@ -0,0 +1,11 @@
+---
+applyTo: "**"
+description: "Language-agnostic coding instructions."
+---
+
+# Coding Standards
+
+- **AVOID** excessive code comments.
+- **ALWAYS** use all lower-case for comments.
+- **ALWAYS** use meaningful, consistent variable names.
+- **ALWAYS** keep the project organized and maintain a clear directory structure.

.github/instructions/project.instructions.md

@@ -0,0 +1,143 @@
+---
+applyTo: "**"
+description: "Project-wide instructions."
+---
+
+# `noclocksai` Project Instructions
+
+## Overview
+
+The `noclocksai` R package provides a comprehensive AI agent framework for R that enables integration with multiple
+LLM providers, tool systems, and data management capabilities.
+
+This document covers the tech stack, high-level architecture, core components, and system relationships within the package.
+
+<!-- BEGIN:TECH_STACK -->
+
+## Tech Stack
+
+> **Maintenance Note**: This section should be updated when dependencies change. The authoritative source for current dependencies is the [`DESCRIPTION` file](../../DESCRIPTION). When updating, verify GitHub repository URLs and ensure package descriptions are accurate and current.
+
+`noclocksai` is an **R Package** that provides a comprehensive AI agent framework for R, enabling integration with multiple LLM providers, tool systems, and data management capabilities.
+
+The package leverages a carefully curated set of dependencies to support AI workflows, data handling, API communication, configuration management, and more. Dependencies are organized by their primary function within the system:
+
+### Core AI & LLM Integration
+
+- [`ellmer`](https://github.com/tidyverse/ellmer): Enables calling large language model (LLM) APIs from within R with a modern, tidyverse-compatible interface.
+
+### Data Manipulation & Analysis
+
+- [`dplyr`](https://github.com/tidyverse/dplyr): A grammar of data manipulation providing a consistent set of verbs for data transformation.
+- [`purrr`](https://github.com/tidyverse/purrr): Functional programming tools for working with functions and vectors in a consistent, type-safe way.
+- [`tibble`](https://github.com/tidyverse/tibble): Modern reimagining of data frames with enhanced printing and subsetting.
+- [`tibblify`](https://github.com/mgirlich/tibblify): Automates parsing of large, complex, nested data structures into rectangular, tidy tibbles using pre-defined specifications.
+- [`tidyselect`](https://github.com/tidyverse/tidyselect): Backend for selecting variables using tidy evaluation principles.
+- [`tidyxl`](https://github.com/nacnudus/tidyxl): Imports non-tabular data from Excel files while preserving cell formatting and structure.
+
+### Data Import/Export & Serialization
+
+- [`readr`](https://github.com/tidyverse/readr): Fast and friendly data import from delimited files with automatic type detection.
+- [`qs2`](https://github.com/qsbase/qs2): Fast serialization of R objects with compression for efficient storage and transfer.
+- [`jsonlite`](https://github.com/jeroen/jsonlite): Robust and flexible JSON parser and generator optimized for statistical data.
+- [`yaml`](https://github.com/vubiostat/r-yaml): Methods to convert R objects to and from YAML format for configuration files.
+- [`base64enc`](https://github.com/s-u/base64enc): Tools for base64 encoding and decoding of binary data.
+
+### Database Integration
+
+- [`DBI`](https://github.com/r-dbi/DBI): Database interface definition providing a common API for database communication in R.
+- [`RPostgres`](https://github.com/r-dbi/RPostgres): DBI-compliant interface to PostgreSQL databases with modern features.
+- [`dm`](https://github.com/r-dbi/dm): Tools for working with relational data models and managing multiple connected tables.
+- [`pool`](https://github.com/r-dbi/pool): Database connection pooling for improved performance and resource management.
+
+### HTTP & API Communication
+
+- [`httr2`](https://github.com/r-lib/httr2): Modern HTTP client for R with support for authentication, retries, rate limiting, and request/response pipelines.
+- [`googleway`](https://github.com/SymbolixAU/googleway): Interface to various Google APIs including Maps, Places, and Geocoding services.
+
+### Configuration & Environment Management
+
+- [`config`](https://github.com/rstudio/config): Flexible management of environment-specific configuration values with YAML support and inheritance.
+- [`rappdirs`](https://github.com/r-lib/rappdirs): Platform-appropriate paths for user data, config, cache, and log directories following OS conventions.
+
+### Process & System Management
+
+- [`sys`](https://github.com/jeroen/sys): Portable system utilities for running external commands with process control and stream management.
+- [`processx`](https://github.com/r-lib/processx): Advanced tools for running and controlling external processes with background job support.
+- [`callr`](https://github.com/r-lib/callr): Execute R scripts and expressions in separate R sessions for isolation and reproducibility.
+- [`withr`](https://github.com/r-lib/withr): Temporarily modify global state ensuring clean and reversible changes to options and environment.
+- [`parallel`](https://stat.ethz.ch/R-manual/R-devel/library/parallel/doc/parallel.pdf): Support for parallel computing in R (base R package).
+- [`future`](https://github.com/HenrikBengtsson/future): Unified parallel and distributed processing with multiple backend support.
+
+### Caching & Performance
+
+- [`cachem`](https://github.com/r-lib/cachem): High-performance, thread-safe caching for R objects with automatic memory management.
+- [`memoise`](https://github.com/r-lib/memoise): Function memoization for caching expensive computations and improving performance.
+
+### Text Processing & Templating
+
+- [`stringr`](https://github.com/tidyverse/stringr): Consistent, intuitive string manipulation functions built on top of stringi.
+- [`snakecase`](https://github.com/Tazinho/snakecase): Tools for converting strings between different case formats (snake_case, camelCase, etc.).
+- [`glue`](https://github.com/tidyverse/glue): String interpolation with embedded R expressions for readable templating.
+- [`whisker`](https://github.com/edwindj/whisker): Logicless templating system based on Mustache for generating dynamic content.
+
+### Web & UI Components
+
+- [`bslib`](https://github.com/rstudio/bslib): Bootstrap themes and components for modern web applications in R.
+- [`htmltools`](https://github.com/rstudio/htmltools): Tools for HTML generation and manipulation in R web applications.
+- [`shiny`](https://github.com/rstudio/shiny): Web application framework for R enabling interactive dashboards and applications.
+- [`shinychat`](https://github.com/jcheng5/shinychat): Chat interface components for Shiny applications with modern UI patterns.
+
+### Object-Oriented Programming
+
+- [`R6`](https://github.com/r-lib/R6): Encapsulated object-oriented programming system with reference semantics.
+- [`S7`](https://github.com/r-lib/S7): Modern object-oriented programming system for R with improved performance and features.
+
+### Utilities & Support
+
+- [`fs`](https://github.com/r-lib/fs): Cross-platform file system operations with a consistent API across operating systems.
+- [`formatR`](https://github.com/yihui/formatR): Tools for formatting R code with automatic indentation and style improvements.
+- [`uuid`](https://github.com/eddelbuettel/uuid): Generate universally unique identifiers for data tracking and identification.
+- [`skimr`](https://github.com/ropensci/skimr): Compact and flexible summary statistics for quick data exploration.
+- [`listviewer`](https://github.com/timelyportfolio/listviewer): Interactive visualization and exploration of nested list structures.
+
+### Image Processing
+
+- [`magick`](https://github.com/ropensci/magick): Advanced image processing capabilities with ImageMagick integration for R.
+
+### Date/Time Processing
+
+- [`lubridate`](https://github.com/tidyverse/lubridate): Simple and consistent tools for working with dates and times in R.
+
+### Logging & Monitoring
+
+- [`lgr`](https://github.com/s-fleck/lgr): Flexible logging framework with multiple backends and hierarchical loggers.
+- [`logger`](https://github.com/daroczig/logger): Lightweight logging utility with customizable output formats and levels.
+
+### Code Evaluation & Execution
+
+- [`evaluate`](https://github.com/r-lib/evaluate): Tools for parsing and evaluating R code with capture of output, warnings, and errors.
+- [`pkgload`](https://github.com/r-lib/pkgload): Simulates package loading for development workflows and testing.
+
+### Low-Level R Infrastructure
+
+- [`rlang`](https://github.com/r-lib/rlang): Tools for working with R language constructs, expressions, and environments.
+- [`cli`](https://github.com/r-lib/cli): Modern command line interface tools with styling, progress bars, and user interaction.
+- [`vctrs`](https://github.com/r-lib/vctrs): Vector types and operations providing the foundation for type-stable data analysis.
+
+### External System Requirements
+
+- **npm**: Node.js package manager required for JavaScript dependencies and build tools.
+- **npx**: Node.js package runner for executing npm packages without global installation.
+
+### Development Dependencies (Suggests)
+
+Additional packages used for development, testing, and documentation but not required for core functionality:
+
+- [`DiagrammeR`](https://github.com/rich-iannone/DiagrammeR): Graph and network visualization with Graphviz and mermaid support.
+- [`knitr`](https://github.com/yihui/knitr): Dynamic report generation combining R code with narrative text.
+- [`rmarkdown`](https://github.com/rstudio/rmarkdown): R Markdown format for reproducible research documents.
+- [`spelling`](https://github.com/ropensci/spelling): Spell checking for R packages and documentation.
+- [`testthat`](https://github.com/r-lib/testthat): Unit testing framework for R with hierarchical structure and rich output.
+
+<!-- END:TECH_STACK -->

.github/instructions/r.instructions.md

@@ -0,0 +1,25 @@
+---
+applyTo: "**/*.R"
+description: "R-specific coding instructions."
+---
+
+# R Coding Standards
+
+## General Guidelines
+
+- **AVOID** excessive code comments.
+- **ALWAYS** use all lower-case for comments.
+- **ALWAYS** use meaningful, consistent variable names.
+- **ALWAYS** ensure you are structuring the project's code abiding by R Package required conventions.
+
+## Package Guidelines
+
+- **ALWAYS** ensure the `DESCRIPTION` and `NAMESPACE` files are properly configured and up-to-date.
+- For exported functions, **ALWAYS** include appropriate documentation (e.g., using `roxygen2` comments) and examples.
+
+## Naming Conventions
+
+- Use snake_case for file names and function names.
+- Use descriptive names that convey the purpose of the file or function.
+- Include a prefix for related functions (i.e. `app_` for Shiny app functions, `mod_` for Shiny modules, `utils_` for utility functions).
+- Use `mod_` prefix for Shiny modules to indicate they are modular components (`mod_home_ui()`, `mod_home_server()`, `mod_home_demo()`).

.github/instructions/terminal.instructions.md

@@ -0,0 +1,53 @@
+---
+applyTo: "**"
+description: "Terminal Instructions"
+---
+
+# Terminal Instructions
+
+*Instructions for using the terminal effectively and avoiding common pitfalls.*
+
+Follow these guidelines to ensure reliable and efficient terminal operations.
+
+## Command Execution (Critical)
+
+- **ALWAYS** be extremely patient when waiting for command output, especially when a new terminal/shell is spawned.
+- **ALWAYS** set `isBackground: false` when running terminal commands.
+  - *This ensures commands run in the foreground and output is visible to both you and the user.*
+- **NEVER** set `isBackground: true` when running terminal commands, unless you need to run a long-running process.
+
+## Terminal Session Management
+
+- **REUSE** the same terminal session for all commands unless parallel execution is required.
+- **NEVER** spawn or launch new terminals when one is already available to you; this causes confusion and context loss.
+- **ALWAYS** use a single, dedicated "Copilot" terminal for all interactions.
+
+## Working Directory & Shell
+
+- The default shell is `pwsh` (PowerShell Core)
+- Use appropriate syntax and commands for PowerShell Core. Do not use bash or other shell syntax.
+- **ALWAYS** ensure you are in the correct working directory before running commands (`$PWD`, `Get-Location`, `Set-Location`, etc.)
+
+## Command Output
+
+- **ALWAYS** wait for command output before proceeding to the next step.
+- **NEVER** check for console output in your background terminal after running commands in the main terminal.
+- **ALWAYS** ask the user to provide the resulting console output if you are unable to see it.
+- **ALWAYS** be extremely patient when waiting for command output, especially when a new terminal/shell is spawned.
+- For sequential commands, **ALWAYS** use the same terminal and ensure each command completes, and you see the output before starting the next.
+
+## File & Context Awareness
+
+- Ensure all files needed by commands are saved and present in the workspace.
+- If working in a monorepo or ambiguous directory, clarify or confirm the intended subdirectory before running commands.
+
+## Error Handling
+
+- If a command fails, **review the output** and address the error before retrying.
+- **NEVER** automatically retry in a new terminal or directory.
+
+## Troubleshooting
+
+- If a command does not run, check if a new terminal was spawned—rerun the command in the existing terminal.
+- If output does not appear, press Enter in the terminal to prompt completion.
+- Restart the terminal or VS Code if persistent issues occur.

.github/instructions/tools.instructions.md

@@ -0,0 +1,29 @@
+---
+applyTo: "**"
+description: "MCP and Tool Usage Instructions"
+---
+
+# Tool Usage Instructions
+
+- Be sure you understand the tools available to you and how to use them effectively.
+
+Your MCP tools are configured in the [`.vscode/mcp.json`](../../.vscode/mcp.json) configuration file
+that you can reference to see the available tools and their configurations.
+
+## Sequential Thinking MCP
+
+- Break down complex problems into smaller, manageable parts.
+- Use for architectural planning and refactoring strategies.
+- Apply when designing system level integrations and features
+- Consider the impact of changes on the overall system architecture.
+- Document your thought process and decisions for future reference.
+
+## Memory MCP
+
+- Utilize memory effectively to retain context and information.
+- Store project-specific knowledge and insights for future use. This should be stored hierarchically for easy retrieval.
+- Document architectural decisions and rationale for future reference.
+- Document where you left off in your thought process or implementation details.
+- Track the project's file structure and organization. Update this regularly to reflect any changes.
+- Track project dependencies and impact analysis.
+- Maintain session continuity for longer tasks or discussions.

.github/prompts/build.prompt.md

@@ -0,0 +1,20 @@
+---
+mode: agent
+tools: ["codebase"]
+description: "Build the R Package."
+---
+
+Before building the package you should first perform the following:
+
+1. Ensure Package can load without any issues: `pkgload::load_all()` from the package root.
+2. [Document R Package](document.prompt.md) to apply roxygen and update NAMESPACE/DESCRIPTION.
+3. [Check R Package](check.prompt.md) to check for issues.
+4. [Test R Package](test.prompt.md) to run unit tests.
+
+then, you can build/install the package.
+
+Run from package root:
+
+```pwsh
+devtools::build()
+```

.github/prompts/check.prompt.md

@@ -0,0 +1,15 @@
+---
+mode: agent
+tools: ["codebase"]
+description: "Check the R Package"
+---
+
+To check the R package, run the following command from package root:
+
+```pwsh
+Rscript -e "devtools::check()"
+```
+
+IMPORTANT: This will take a long time. BE PATEIENT AND WAIT FOR IT TO COMPLETE BEFORE MOVING ON.
+
+Be sure to thoroughly review all console output and issues from the check.

.github/prompts/document.prompt.md

@@ -0,0 +1,16 @@
+---
+mode: agent
+tools: ["codebase"]
+description: "Roxygenize/document the R package."
+---
+To document the R package, run the following command from the root of the package:
+
+```pwsh
+Rscript -e "pkgload::load_all(); attachment::att_amend_desc(); devtools::document()"
+```
+
+Then,
+
+- Review the console output for any warnings or errors that may need to be addressed.
+- Review any changes in `DESCRIPTION` or `NAMESPACE` and ensure they are valid.
+- If needed, update your memory with any relevant details.

.github/prompts/memory.prompt.md

@@ -0,0 +1,9 @@
+---
+mode: agent
+tools: ["memory", "codebase", "mcp-memory"]
+description: "Update and maintain persistent project memory across sessions."
+---
+
+1. Review the current state of the memory and review the observations previously stored.
+2. Update and add new observations to the memory store using your active conversation's context and history.
+3. Periodically review and clean up the memory store to remove outdated or irrelevant observations.

.github/prompts/repomix.prompt.md

@@ -0,0 +1,13 @@
+---
+mode: agent
+tools: ["codebase", "mcp-repomix"]
+description: "Generate project-wide 'repomix' packed context file(s).
+---
+
+Generate project context `repomix` files using your `repomix` MCP tool.
+
+If the tools is not available or is having issues, fall back to the commands below:
+
+```pwsh
+repomix
+```