Agent-native programming language and runtime

Dana — The Agent-Native Evolution of AI Development¶

Beyond AI coding assistants: Write agents that learn, adapt, and improve themselves in production

What if your agents could learn, adapt, and improve itself in production—without you?

Welcome to the contributor guide for Dana! This is your comprehensive resource for understanding the architecture, extending capabilities, and contributing to the agent-native programming ecosystem.

Dana for Contributors¶

Whether you're looking to contribute code, extend functionality, or deeply understand Dana's agent-native architecture that bridges AI coding assistance with autonomous systems, this guide provides everything you need to become an effective contributor to the Dana ecosystem.

Quick Start for Contributors¶

1. Development Environment Setup¶

# Clone the repository
git clone https://github.com/aitomatic-oss/dana.git
cd dana

# Set up development environment and run tests to verify setup
make dev

Note: Use uv run before commands or activate the venv: source .venv/bin/activate

2. Understand the Agent-Native Architecture and Codebase¶

Dana represents the convergence of development-time AI assistance and runtime autonomy through: - Native agent primitives (not classes with AI bolted on) - Context-aware execution that adapts reason() output types automatically
- Self-improving pipeline composition with | operators - POET-enabled adaptive functions that learn from production

3. Make Your First Contribution¶

Overview¶

Dana is built on an agent-native, modular, extensible architecture that represents the convergence of AI coding assistance and autonomous execution:

┌──────────────────────────────────────────────────────────┐
│                    Application Layer                     │
├──────────────────────────────────────────────────────────┤
│                      Agent Layer                         │
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────┐ │
│ │    Agent    │ │ Capabilities │ │     Resources       │ │
│ │ Management  │ │    System    │ │    Management       │ │
│ └─────────────┘ └──────────────┘ └─────────────────────┘ │
├──────────────────────────────────────────────────────────┤
│                   Dana Execution Layer                   │
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────┐ │
│ │   Parser    │ │ Interpreter  │ │   Runtime Context   │ │
│ │    (AST)    │ │  (Executor)  │ │   (State Manager)   │ │
│ └─────────────┘ └──────────────┘ └─────────────────────┘ │
├──────────────────────────────────────────────────────────┤
│                     Resource Layer                       │
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────┐ │
│ │ LLM Resource│ │  Knowledge   │ │   External Tools    │ │
│ │Integration  │ │    Base      │ │     & Services      │ │
│ └─────────────┘ └──────────────┘ └─────────────────────┘ │
└──────────────────────────────────────────────────────────┘

Core Modules¶

`dana/dana/`¶

The heart of the Dana language implementation:

dana/
├── parser/ # Dana language parser and AST
├── interpreter/ # Dana program execution engine
├── sandbox/ # Execution context and state management
├── repl/ # Interactive development environment
└── transcoder/ # Natural language to Dana conversion

`opendxa/agent/`¶

Agent management and execution:

agent/
├── agent.py # Core Agent class and lifecycle
├── agent_runtime.py # Runtime execution environment
├── capability/ # Capability system implementation
└── resource/ # Resource management and integration

`opendxa/common/`¶

Shared utilities and base classes:

common/
├── config/ # Configuration management
├── resource/ # Base resource classes
├── utils/ # Utility functions and helpers
└── mixins/ # Reusable component mixins

Key Files to Understand¶

opendxa/dana/interpreter/interpreter.py - Core Dana program execution logic
opendxa/dana/parser/parser.py - Dana language grammar and parsing
opendxa/agent/agent.py - Agent lifecycle and configuration
opendxa/common/resource/llm_resource.py - LLM integration and management

Development Workflows¶

Testing¶

# Run all tests
make test

# Run fast tests only (excludes live/deep tests)
make test-fast

# Run live tests (requires API keys)
make test-live

# Run tests and check coverage
make test-cov

# Run tests in watch mode (reruns on file changes)
make test-watch

Code Quality¶

# Run linting checks
make lint

# Auto-fix linting issues
make lint-fix

# Format code with ruff
make format

# Run all code quality checks (lint + format-check + typecheck)
make check

# Auto-fix all fixable issues
make fix

🎨 Extension Development¶

Creating Custom Capabilities¶

Capabilities extend agent functionality with reusable, composable modules:

from opendxa.agent.capability.base_capability import BaseCapability

class CustomAnalysisCapability(BaseCapability):
    """Custom capability for specialized data analysis."""

    def __init__(self, config: dict = None):
        super().__init__(config)
        self.analysis_model = self._load_model()

    def get_functions(self) -> dict:
        """Return Dana functions provided by this capability."""
        return {
            "analyze_data": self.analyze_data,
            "generate_insights": self.generate_insights,
        }

 def analyze_data(self, data, analysis_type="standard"):
 """Analyze data using custom algorithms."""
 # Implementation here
 return analysis_results

 def generate_insights(self, analysis_results):
 """Generate insights from analysis results."""
 # Implementation here
 return insights

Creating Custom Resources¶

Resources provide external service integration:

from opendxa.common.resource.base_resource import BaseResource

class CustomAPIResource(BaseResource):
    """Resource for integrating with custom API service."""

    def __init__(self, api_key: str, base_url: str):
        super().__init__()
        self.api_key = api_key
        self.base_url = base_url
        self.client = self._initialize_client()

 def get_functions(self) -> dict:
 """Return Dana functions for API operations."""
 return {
 "fetch_data": self.fetch_data,
 "submit_request": self.submit_request,
 }

 def fetch_data(self, endpoint: str, params: dict = None):
 """Fetch data from the API."""
 # Implementation here
 return api_response

Dana Function Development¶

Add custom functions to the Dana language:

from opendxa.dana.interpreter.function_registry import register_function

@register_function("custom_transform")
def custom_transform(data, transformation_type="default"):
    """Custom data transformation function for Dana."""
    if transformation_type == "normalize":
        return normalize_data(data)
    elif transformation_type == "aggregate":
        return aggregate_data(data)
    else:
        return apply_default_transform(data)

Complete Extension Guide

🧪 Testing and Quality Assurance¶

Testing Strategy¶

Dana uses a comprehensive testing strategy to ensure reliability and quality:

from opendxa.dana.interpreter import DanaInterpreter

# Unit tests for Dana functions
def test_custom_function():
    interpreter = DanaInterpreter()
    result = interpreter.eval("custom_transform([1, 2, 3])")
    assert result == [1, 2, 3]

# Integration tests for capabilities
def test_capability_integration():
    capability = CustomAnalysisCapability()
    functions = capability.get_functions()
    assert "analyze_data" in functions

Quality Gates¶

Code Coverage: Minimum 80% coverage for new features
Type Safety: All Python code must pass mypy checks
Documentation: All public APIs must be documented
Performance: New features must not degrade performance by >5%

🤝 Contributing Process¶

1. Fork the Repository: Create your own fork of Dana¶

2. Create a Feature Branch¶

git checkout -b feature/your-feature-name

3. Make Your Changes¶

Follow the coding standards
Add tests for new functionality
Update documentation as needed

4. Test Your Changes¶

make test
make lint
make typecheck

5. Submit a Pull Request¶

Provide a clear description of changes
Link any related issues
Ensure all tests pass

📚 Learning Resources¶

Architecture Deep Dives¶

System Design - High-level architecture
Codebase Overview - Code organization
Extension Development - Building extensions

Development Guides¶

Development Setup - Environment setup
Contribution Guide - Contribution process

Community and Support¶

Getting Started¶

Look for issues labeled good first issue.*

Ready to contribute? Start with the Quick Start or explore our Extension Development Guide.