Sync from dana-internal (2026-01-12)

.gitignore

@@ -11,6 +11,7 @@ __pycache__/
 .ruff_cache/
 
 # Environment
+.cursor/
 .tmp/
 tmp/
 .venv

.vscode/launch.json

@@ -35,8 +35,9 @@
       "name" : "Debug Dana Backend",
       "type": "python",
       "request": "launch",
+      "justMyCode": false,
       "module": "dana.apps.cli.__main__",
-      "args": ["studio"],
+      "args": ["studio", "--reload"],
       "console": "integratedTerminal",
       "env" : {
         "DANAPATH" : "${workspaceFolder}"

Makefile

@@ -366,7 +366,7 @@ check-dist: ## Validate built distribution files
 publish: check-dist ## Upload to PyPI
 	@echo "🚀 Publishing to PyPI..."
 	$(UV_CMD) run twine upload --verbose dist/*
-run: dana ## Alias for 'dana' command 
+run: dana ## Alias for 'dana' command
 
 build-frontend: ## Build the frontend (Vite React app) and copy to backend static
 	cd dana/contrib/ui && npm i && npm run build

adana/__init__.py

@@ -0,0 +1,19 @@
+"""
+Adana - Minimal LLM Library
+
+A simple, clean interface for interacting with any LLM provider.
+Follows KISS principle with just the essential methods most clients need.
+"""
+
+# Import library initialization FIRST (loads .env automatically)
+from .__init__ import initialize
+
+
+initialize()
+
+from .common import LLM, LLMMessage, LLMResponse
+from .core import STARAgent
+
+
+__version__ = "0.1.0"
+__all__ = ["LLM", "LLMMessage", "LLMResponse", "STARAgent"]

adana/__init__/__init__.py

@@ -0,0 +1,7 @@
+def initialize():
+    from .dotenv import init as dotenv_init
+
+    dotenv_init()
+
+
+all = ["initialize"]

adana/__init__/dotenv.py

@@ -0,0 +1,46 @@
+"""
+Adana Library Initialization Module
+
+This module handles all library startup and initialization tasks.
+It can be run directly as: python -m adana.__init__
+
+This module is automatically imported when the main adana library is imported.
+"""
+
+# Import startup functions directly
+from pathlib import Path
+import sys
+
+
+# Add the project root to Python path
+project_root = Path(__file__).parent.parent.parent
+sys.path.insert(0, str(project_root))
+
+# Import startup functions directly
+from dotenv import find_dotenv, load_dotenv
+
+
+def load_env():
+    """
+    Load environment variables from .env file.
+
+    Searches for .env file up the directory tree until it finds one
+    or reaches the home directory. This function is called automatically
+    when the library is imported, but you can call it explicitly if needed.
+    """
+    dotenv_path = find_dotenv()
+    if dotenv_path:
+        load_dotenv(dotenv_path)
+    else:
+        load_dotenv()
+
+
+def init():
+    """
+    Initialize the Adana library.
+
+    This function handles all startup tasks including:
+    - Loading environment variables from .env files
+    - Any other library initialization tasks
+    """
+    load_env()

adana/apps/__init__.py

@@ -0,0 +1 @@
+"""Adana applications package."""

adana/apps/cli/__init__.py

@@ -0,0 +1 @@
+"""Adana CLI application."""

adana/apps/cli/__main__.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""
+Adana Command Line Interface - Main Entry Point
+
+Simple CLI router that decides whether to:
+- Execute a Python script
+- Launch the interactive REPL
+
+Usage:
+  adana                    Start Dana conversational agent
+  adana script.py          Execute a Python script
+  adana-repl               Start interactive Python REPL
+  adana --help             Show help message
+"""
+
+import argparse
+from pathlib import Path
+import sys
+
+
+def main():
+    """Main entry point for the Adana CLI."""
+    parser = argparse.ArgumentParser(
+        description="Adana - Domain-Aware Neurosymbolic Agent Framework",
+        add_help=False,
+    )
+    parser.add_argument("file", nargs="?", help="Python script to execute")
+    parser.add_argument("-h", "--help", action="store_true", help="Show help message")
+    parser.add_argument("--version", action="store_true", help="Show version")
+
+    args = parser.parse_args()
+
+    # Show help
+    if args.help:
+        show_help()
+        return 0
+
+    # Show version
+    if args.version:
+        from adana import __version__
+
+        print(f"Adana {__version__}")
+        return 0
+
+    # Execute file or start REPL
+    if args.file:
+        return execute_file(args.file)
+    else:
+        return start_repl()
+
+
+def show_help():
+    """Display help information."""
+    print("""
+╔═══════════════════════════════════════════════════════════╗
+║  Adana - Domain-Aware Neurosymbolic Agent Framework       ║
+╚═══════════════════════════════════════════════════════════╝
+
+Usage:
+  adana                    Start Dana conversational agent
+  adana-repl               Start interactive Python REPL
+  adana script.py          Execute a Python script
+  adana --help             Show this help message
+  adana --version          Show version information
+
+Dana is a conversational AI that helps you manage agents, resources,
+and workflows through natural language interaction.
+
+Use 'adana-repl' for a Python REPL with pre-imported Adana classes.
+""")
+
+
+def execute_file(file_path: str) -> int:
+    """Execute a Python script.
+
+    Args:
+        file_path: Path to the Python script to execute
+
+    Returns:
+        Exit code (0 for success, 1 for error)
+    """
+    path = Path(file_path)
+
+    if not path.exists():
+        print(f"Error: File '{file_path}' not found")
+        return 1
+
+    if not path.suffix == ".py":
+        print("Error: File must have .py extension")
+        return 1
+
+    try:
+        # Read and execute the file
+        code = path.read_text()
+        exec(code, {"__name__": "__main__", "__file__": str(path)})
+        return 0
+    except Exception as e:
+        print(f"Error executing script: {e}")
+        import traceback
+
+        traceback.print_exc()
+        return 1
+
+
+def start_repl() -> int:
+    """Start the Dana conversational agent.
+
+    Returns:
+        Exit code (0 for success)
+    """
+    try:
+        from adana.apps.dana.__main__ import main as dana_main
+
+        dana_main()
+        return 0
+    except ImportError as e:
+        print(f"Error: Failed to import Dana module: {e}")
+        return 1
+    except Exception as e:
+        print(f"Error starting Dana: {e}")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

adana/apps/dana/DanaAgent.prt

@@ -0,0 +1,30 @@
+<PUBLIC_DESCRIPTION>
+Dana is a conversational coordinator for multi-agent systems. Dana helps users:
+- Discuss goals and translate them into structured actions
+- Create, configure, and manage specialized agents
+- Invoke resources and workflows to perform tasks
+- Orchestrate multi-step, cross-agent operations
+- Provide progress updates, results, and transparent provenance on request
+</PUBLIC_DESCRIPTION>
+
+<PRIVATE_IDENTITY>
+You are Dana, a conversational coordinator for multi-agent systems. You help users
+navigate complex tasks by breaking them down, delegating to appropriate agents,
+and orchestrating the results into coherent outcomes.
+</PRIVATE_IDENTITY>
+
+<THINKING_RULES>
+You operate according to the STAR loop:
+- SEE: Understand the user's request and current context
+- THINK: Plan the approach and identify required agents/resources
+- ACT: Execute the plan through structured tool calls
+- REFLECT: Summarize outcomes and suggest next steps
+</THINKING_RULES>
+
+<CONFIGURATION_INFO>
+Maintain continuity across turns and refer back to relevant context.
+Clarify ambiguous inputs briefly, then proceed.
+When a task involves multiple steps, summarize the plan before execution.
+Be proactive but predictable: take actions only when clearly needed.
+Always explain what you're doing and why in concise natural language.
+</CONFIGURATION_INFO>