ArtReactor


Purpose

ArtReactor Core aim to be the backbone framework for the modern Game Asset Pipeline, designed to be extensible and modular. Its primary goal is to allow developers to "write once and expose" functionality for other tools to use, enforced with strict security controls. It facilitates communication between different software and treats Agentic AI as a first-class citizen, enabling complex, cross-application workflows.

Tech Stack

• Language: Python 3.10+
• Framework: FastAPI
• Agent Framework: PydanticAI (formerly smolagents)
• Server: uvicorn
• Package Manager: uv
• Build System: hatchling
• Key Libraries:
  • pydantic-ai (AI agent framework with type safety)
  • litellm (LLM abstraction)
  • pystray, pillow (System tray integration)
  • pyyaml, toml (Configuration)
  • aiofiles (Async file I/O)

Project Conventions

Code Style

• Python: Follows standard Python conventions (PEP 8).
• Imports: Use absolute imports from the artreactor package (e.g., from artreactor.core import ...).
• Async: Heavy use of async/await for I/O bound operations, especially in API endpoints and plugin interactions.
• Type Hinting: Extensive use of type hints for clarity and IDE support.

Architecture Patterns

• Plugin Architecture: Core functionality is extended via plugins (CorePlugin, ToolPlugin, AgentPlugin, ModelPlugin, UIPlugin).
• Managers: Centralized managers (AgentManager, PluginManager, ModelManager) handle lifecycle and registry of components.
• Dependency Injection: Services and managers are often passed or accessed via a central hub or context.
• Src-Layout: Source code is located in src/artreactor.

Testing Strategy

• Framework: pytest
• Async Testing: pytest-asyncio for async tests.
• Structure:
  • tests/unit: Isolated tests for individual components.
  • tests/integration: Tests ensuring components (e.g., Agents and Tools) work together.
  • tests/mocks: Mock implementations (e.g., MockModel) to simulate external dependencies like LLMs.
• Command: uv run pytest

Domain Context

• Game Asset Pipeline: The system is central to managing and automating the flow of game assets between various DCC (Digital Content Creation) tools and engines.
• Agentic AI: Agents are first-class citizens, capable of orchestrating complex pipelines and interacting with external tools securely.
• Inter-Software Communication: Facilitates data exchange and command execution between different software applications in the pipeline.
• Security: Strict access controls and permissions are enforced for all plugin and agent interactions.
• MCP (Model Context Protocol): Support for exposing functionality via MCP.
• Plugins:
  • Manifest: Plugins are defined by a plugin.toml.
  • Discovery: See "Plugin Management" section.

Important Constraints

• Windows OS: The primary development and deployment environment is Windows.
• Local Focus: Designed to run locally or as a self-hosted service.

External Dependencies

• LLM Providers: Relies on external or local LLM providers (OpenAI, Anthropic, Ollama, etc.) via litellm.

Desktop Application (ArcVision)

ArteCore includes a native desktop frontend ArcVision (located in src/ArcVision).

• Framework: Tauri v2
• Function: Wrapper/Manager for the Core Service.
• Build: Run .\scripts\build.ps1 to build the full desktop application.

Event System

The Event System allows decoupled communication between components.

• Decorators: @event to define events, @on to bind listeners.
• Features: Async support, Unbind (off), Fire-and-Forget listeners.
• Performance: Capable of handling 1M+ listeners and 100k+ events efficiently.

CLI Usage (Arte)

ArtReactor Core provides a CLI tool arte for managing the service and plugins.

# Start the service
arte start

# List available plugin templates
arte plugin templates

# Create a new plugin in a host project
arte plugin create my-plugin --type core

# Initialize a standalone plugin repository
arte plugin init-project my-plugin --type core

# Install a plugin from git
arte plugin install https://github.com/user/plugin-repo.git

# Install a plugin from local path (copy mode)
arte plugin install /path/to/plugin

# Install a plugin in dev mode (symlink)
arte plugin install /path/to/plugin --link

Plugin Management

Plugins are the core extensibility mechanism.

• Manifest: Plugins are defined by a plugin.toml.
• Discovery: Plugins are auto-discovered from:
  1. ./plugins (Project root)
  2. src/artreactor/plugins (System plugins)
  3. Custom paths defined in config.toml under plugin_dirs.

Creating Plugins

In a Host Project

Use arte plugin create to scaffold a new plugin in the current project:

arte plugin create my-plugin --type core

This creates plugins/my-plugin/ with the necessary files.

As a Standalone Repository

Use arte plugin init-project to create a complete standalone plugin repository:

# Create a new directory or navigate to an existing repo
mkdir my-plugin && cd my-plugin

# Initialize the plugin project
arte plugin init-project my-plugin --type core

This creates a complete project structure:

my-plugin/
├── plugins/
│   └── my-plugin/         # Your plugin code
│       ├── plugin.toml
│       ├── __init__.py
│       └── SKILL.md
├── tests/
│   └── test_plugin_load.py  # Basic plugin loading test
├── pyproject.toml         # Dependencies (includes artreactor)
├── README.md              # Usage instructions
└── .gitignore

Available Plugin Types: core, router, app, model, agent, ui.

Installing Plugins

From Git Repository

arte plugin install https://github.com/user/plugin-repo.git

Clones the repository into ./plugins/.

From Local Path

# Copy mode (for deployment)
arte plugin install /path/to/plugin

# Dev mode with symlink (for development)
arte plugin install /path/to/plugin --link

Plugin Repository Detection:

• If the path contains plugin.toml at the root, it's treated as a plugin.
• If the path contains plugins/<name>/plugin.toml, the plugin is auto-detected.
• If multiple plugins are found, you'll be prompted to specify which one.

Dev Mode (--link):

• Creates a symlink instead of copying files.
• Allows editing the plugin in its original location.
• Changes are immediately reflected in the host project.
• Perfect for developing a plugin in its own repository.

Plugin Development Workflow

Two-Repository Development Pattern

1. Plugin Repository (standalone):

   # Initialize plugin project
   mkdir my-awesome-plugin && cd my-awesome-plugin
   arte plugin init-project my-awesome-plugin --type core
   
   # Install dependencies
   pip install -e .
   
   # Run tests
   pytest
   

2. Host Project (uses the plugin):

   # Link the plugin for development
   arte plugin install ../my-awesome-plugin --link
   
   # Start the service
   arte start
   
   # When done developing, unlink and install normally
   rm -rf plugins/my-awesome-plugin
   arte plugin install ../my-awesome-plugin
   

This workflow allows you to:

• Develop and test the plugin independently
• Use version control on just the plugin
• Share the plugin as a separate package
• Iterate quickly with --link mode

Agent Skills

Agent Skills is a powerful feature that allows plugins to expose their capabilities to AI agents through SKILL.md files. This enables agents to automatically discover and use plugin functionality based on context.

What is a SKILL.md?

A SKILL.md file is a markdown document that describes what a plugin can do, when it should be used, and how to use it. It follows the Anthropic Agent Skills format with YAML frontmatter for metadata.

Structure of SKILL.md

---
name: Skill Name
description: Brief description of what this skill provides
---

## Context Keywords

- keyword1
- keyword2
- keyword3

## Tools

- `tool_name_1` - Description
- `tool_name_2` - Description

## Instructions

Detailed instructions on how to use this skill effectively.

## Examples

Concrete examples showing how to use the skill.

Key Components:

• YAML Frontmatter: Contains name and description metadata (required)
• Context Keywords: List of keywords for context-based skill discovery
• Tools: Available tools/functions that the skill provides
• Instructions: Step-by-step guide for using the skill
• Examples: Concrete usage examples with code snippets

Creating Plugins with Skills

When you create a new plugin using arte plugin create, a SKILL.md template is automatically included. Simply fill in the sections with relevant information about your plugin's capabilities.

How Agents Use Skills

1. Discovery: When a plugin loads, its SKILL.md is parsed and registered with the SkillManager
2. Context Matching: When an agent processes a request, it searches for skills whose keywords match the request context
3. Contextual Injection: Matching skills are automatically added to the agent's context, providing instructions and tool information
4. Execution: The agent can then use the described tools to complete the task

Example

See plugins/example-git-skill/SKILL.md for a complete example of a well-documented skill.

Configuration

The service is configured via config.toml in the project root.

Structure

# Additional plugin search paths
plugin_dirs = ["./my_plugins", "C:/path/to/plugins"]

# Logging Configuration
[logging]
level = "INFO" # DEBUG, INFO, WARNING, ERROR, CRITICAL
enabled = true
providers = ["console"]

# Plugin Configuration
[plugins.core-git]
enabled = true
priority = 100

[plugins.my-plugin]
enabled = false # Disable specific plugins

Key Settings

• plugin_dirs: List of additional directories to scan for plugins.
• [plugins.<name>]: Configure specific plugins. enabled and priority are supported by default.
• [logging]: Configure global logging levels and providers.