Development Setup & Conventions

This guide provides comprehensive instructions for setting up your development environment and understanding the codebase conventions for JuliaOS.

Setting Up Development Environment

Prerequisites

Before you begin, ensure you have the following installed on your system:

Git: For version control (Download)
Node.js: v16+ (Download)
npm: v7+ (Usually included with Node.js)
Julia: v1.8+ (Download)
Python: v3.8+ (for Python wrapper) (Download)

Step 1: Clone the Repository

git clone https://github.com/Juliaoscode/JuliaOS.git
cd JuliaOS

Step 2: Install Node.js Dependencies

JuliaOS uses a monorepo structure managed by npm workspaces. Install all dependencies with:

npm install

This will install dependencies for all packages in the /packages directory.

Step 3: Install Julia Dependencies

Activate the Julia environment and install all required packages:

julia -e 'using Pkg; Pkg.activate("julia"); Pkg.instantiate()'

If you encounter any issues with Julia package installation, you can try resolving them with:

julia -e 'using Pkg; Pkg.activate("julia"); Pkg.resolve(); Pkg.instantiate()'

Step 4: Install Python Dependencies (Optional)

If you plan to use or develop the Python wrapper:

pip install -e ./packages/python-wrapper

For development with LangChain integration:

pip install -e "./packages/python-wrapper[langchain]"

Step 5: Configure Environment Variables

Create a .env file in the project root:

cp .env.example .env  # If .env.example exists
# Otherwise, create a new .env file

Edit the .env file to include necessary configuration:

# Ethereum and EVM chains
ETHEREUM_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY
ETHEREUM_SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY
POLYGON_RPC_URL=https://polygon-mainnet.g.alchemy.com/v2/YOUR_API_KEY
ARBITRUM_RPC_URL=https://arb-mainnet.g.alchemy.com/v2/YOUR_API_KEY
OPTIMISM_RPC_URL=https://opt-mainnet.g.alchemy.com/v2/YOUR_API_KEY
BASE_RPC_URL=https://mainnet.base.org
AVALANCHE_RPC_URL=https://api.avax.network/ext/bc/C/rpc
BSC_RPC_URL=https://bsc-dataseed.binance.org
FANTOM_RPC_URL=https://rpc.ftm.tools

# Solana
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com

# API Keys (if needed)
ALCHEMY_API_KEY=YOUR_ALCHEMY_API_KEY
INFURA_API_KEY=YOUR_INFURA_API_KEY

# Server Configuration
JULIAOS_SERVER_PORT=8052
JULIAOS_SERVER_HOST=localhost

# Storage Configuration
STORAGE_PATH=~/.juliaos

# LLM Configuration (if using)
OPENAI_API_KEY=YOUR_OPENAI_API_KEY

For development purposes, you can use public RPC endpoints or free tier API keys from providers like Alchemy, Infura, or QuickNode.

Step 6: Start Development Servers

Start the Julia backend server:

cd julia
julia julia_server.jl

In a separate terminal, start the interactive CLI:

cd /path/to/JuliaOS
node packages/cli/interactive.cjs

Step 7: Verify Installation

To verify that your development environment is set up correctly:

The Julia server should be running without errors on port 8052 (or your configured port)
The CLI should connect to the server and display the main menu
Run a simple test command in the CLI to verify connectivity

Development Workflow

Running Tests

Julia Tests

cd julia
julia -e 'using Pkg; Pkg.activate("."); Pkg.test()'

Or run specific test files:

julia -e 'using Pkg; Pkg.activate("."); include("test/runtests.jl")'

TypeScript/JavaScript Tests

npm test

Or for a specific package:

cd packages/framework
npm test

Python Tests

cd packages/python-wrapper
python -m pytest

Building Packages

npm run build

This will build all packages in the monorepo. To build a specific package:

cd packages/framework
npm run build

Development Commands

Linting: npm run lint
Formatting: npm run format
Type Checking: npm run typecheck
Watch Mode: npm run dev (for packages that support it)

Codebase Structure

Directory Structure

JuliaOS/
├── julia/                  # Julia backend code
│   ├── src/                # Main Julia source code
│   │   ├── JuliaOS.jl      # Main module definition
│   │   ├── Agents.jl       # Agent system implementation
│   │   ├── Swarms.jl       # Swarm algorithms implementation
│   │   ├── Blockchain.jl   # Blockchain interaction
│   │   ├── Bridge.jl       # Cross-chain bridge functionality
│   │   ├── DEX.jl          # DEX integration
│   │   ├── Storage.jl      # Storage functionality
│   │   ├── Wallet.jl       # Wallet management
│   │   └── ...            # Other modules
│   ├── test/               # Julia tests
│   ├── config/             # Configuration files
│   └── julia_server.jl     # Main server entry point
├── packages/               # TypeScript/JavaScript packages
│   ├── cli/                # Interactive CLI
│   ├── framework/          # Core framework for JS/TS applications
│   │   ├── src/            # Source code
│   │   │   ├── agents.ts   # Agent management
│   │   │   ├── swarms.ts   # Swarm management
│   │   │   ├── bridge.ts   # Bridge functionality
│   │   │   ├── dex.ts      # DEX integration
│   │   │   ├── wallet.ts   # Wallet management
│   │   │   └── ...        # Other modules
│   │   └── tests/          # Tests
│   ├── bridges/            # Bridge implementations
│   ├── wallets/            # Wallet integrations
│   └── python-wrapper/     # Python bindings
│       ├── juliaos/        # Python package
│       │   ├── agents/     # Agent functionality
│       │   ├── swarms/     # Swarm functionality
│       │   ├── blockchain/ # Blockchain functionality
│       │   ├── langchain/  # LangChain integration
│       │   └── ...        # Other modules
│       └── tests/          # Python tests
├── docs/                   # Documentation
│   └── gitbook/            # GitBook documentation
└── .env                    # Environment variables

Component Architecture

JuliaOS follows a modular architecture with clear separation of concerns:

Backend (Julia): High-performance core functionality
- Agent and swarm implementation
- Blockchain interaction
- Storage management
- Server implementation
Bridge Layer: Communication between backend and clients
- WebSocket server/client
- Command handling
- Event propagation
Client Interfaces:
- TypeScript/JavaScript framework
- Python wrapper
- Interactive CLI
Extensions:
- Bridge implementations
- Wallet integrations
- DEX connectors

Coding Conventions

Julia Conventions

Follow the Julia Style Guide
Use module-level organization for related functionality
Implement comprehensive error handling
Write docstrings for all public functions
Use type annotations where appropriate
Write unit tests for all functionality

Example:

"""
    create_agent(name::String, type::String, config::Dict) -> Dict

Create a new agent with the specified name, type, and configuration.

# Arguments
- `name::String`: The name of the agent
- `type::String`: The type of agent (e.g., "trading", "research")
- `config::Dict`: Configuration parameters for the agent

# Returns
- `Dict`: The created agent object with an assigned ID

# Examples
```julia
agent = create_agent("MyAgent", "trading", Dict("risk_level" => "medium"))

""" function create_agent(name::String, type::String, config::Dict) # Implementation end


### TypeScript/JavaScript Conventions

- Use TypeScript for type safety
- Follow ESLint and Prettier configurations
- Use async/await for asynchronous code
- Document functions with JSDoc comments
- Write unit tests for all functionality
- Use named exports for better tree-shaking

Example:

```typescript
/**
 * Creates a new agent with the specified parameters
 * @param {string} name - The name of the agent
 * @param {string} type - The type of agent (e.g., "trading", "research")
 * @param {object} config - Configuration parameters for the agent
 * @returns {Promise<Agent>} The created agent object
 */
export async function createAgent(
  name: string,
  type: string,
  config: Record<string, any>
): Promise<Agent> {
  // Implementation
}

Python Conventions

Follow PEP 8 style guidelines
Use type hints (PEP 484)
Document functions with docstrings
Use async/await for asynchronous code
Write unit tests for all functionality

Example:

async def create_agent(
    name: str,
    agent_type: AgentType,
    config: Dict[str, Any]
) -> Agent:
    """Create a new agent with the specified parameters.

    Args:
        name: The name of the agent
        agent_type: The type of agent (e.g., TRADING, RESEARCH)
        config: Configuration parameters for the agent

    Returns:
        The created agent object

    Raises:
        ConnectionError: If connection to the backend fails
        AgentError: If agent creation fails
    """
    # Implementation

Git Workflow

Branching Strategy:
- main: Stable production code
- develop: Integration branch for features
- feature/xxx: Feature branches
- fix/xxx: Bug fix branches
- docs/xxx: Documentation updates
Commit Messages: Follow conventional commit standards:
- feat: add new agent type
- fix: resolve bridge transfer bug
- docs: update architecture diagram
- refactor: improve swarm algorithm performance
- test: add tests for wallet integration
- chore: update dependencies
Pull Requests:
- Create descriptive PR titles
- Include detailed descriptions
- Reference related issues
- Ensure all tests pass
- Request reviews from appropriate team members

Troubleshooting Common Issues

Julia Package Installation Issues

If you encounter issues with Julia package installation:

julia -e 'using Pkg; Pkg.activate("julia"); Pkg.update(); Pkg.resolve(); Pkg.instantiate()'

Node.js Dependency Issues

If you encounter issues with Node.js dependencies:

rm -rf node_modules
npm cache clean --force
npm install

Server Connection Issues

If the CLI cannot connect to the Julia server:

Ensure the server is running on the correct port
Check for firewall or network issues
Verify the .env configuration
Check server logs for errors

Python Wrapper Issues

If you encounter issues with the Python wrapper:

pip uninstall juliaos
pip install -e ./packages/python-wrapper

Next Steps

Now that you have set up your development environment, you can:

Explore the CLI Guide to learn how to use the CLI
Check out the Framework Modules to understand the core components
Read the Extending Guide to learn how to extend JuliaOS
Review the Best Practices for development guidelines

PreviousExtending JuliaOS NextTesting & Debugging