Enterprise Security

• Input Guardrails: Content filtering and validation
• Output Guardrails: Response sanitization
• Permission System: Role-based access control
• Audit Logging: Complete interaction tracing
• Proxy Support: Corporate proxy integration with authentication

Observability & Monitoring

• Real-time Tracing: Event-driven observability
• OpenTelemetry Integration: Distributed tracing with OTLP
• Langfuse Tracing: LLM observability and analytics
• Structured Logging: JSON-formatted logs
• Error Handling: Comprehensive error types and recovery
• Performance Metrics: Built-in timing and counters

Agent-as-Tool Architecture

• Hierarchical Orchestration: Use agents as tools in other agents
• Conditional Tool Enabling: Enable/disable agent tools based on context
• Session Management: Configurable session inheritance for sub-agents
• Flexible Output Extraction: Custom extractors for agent tool outputs

Developer Experience

• CLI Tools: Project initialization and management
• Hot Reload: Development server with auto-reload
• Type Hints: Full mypy compatibility
• Rich Examples: RAG, multi-agent, agent-as-tool, and server demos
• Visual Architecture: Graphviz-powered agent and tool diagrams

Core Philosophy

• Immutability: All core data structures are deeply immutable
• Pure Functions: Core logic expressed as pure, predictable functions
• Effects at the Edge: Side effects isolated in Provider modules
• Composition over Configuration: Build complex behavior by composing simple functions
• Type-Safe by Design: Leverages Python's type system with Pydantic for runtime safety

Quick Start

Installation

# Install from GitHub (development version)
pip install git+https://github.com/xynehq/jaf-py.git

# Or install with all optional dependencies
pip install "jaf-py[all] @ git+https://github.com/xynehq/jaf-py.git"

# Install specific feature sets
pip install "jaf-py[server] @ git+https://github.com/xynehq/jaf-py.git"        # FastAPI server support
pip install "jaf-py[memory] @ git+https://github.com/xynehq/jaf-py.git"        # Redis/PostgreSQL memory providers
pip install "jaf-py[visualization] @ git+https://github.com/xynehq/jaf-py.git" # Graphviz visualization tools
pip install "jaf-py[tracing] @ git+https://github.com/xynehq/jaf-py.git"       # OpenTelemetry and Langfuse tracing
pip install "jaf-py[dev] @ git+https://github.com/xynehq/jaf-py.git"           # Development tools

CLI Usage

JAF includes a powerful CLI for project management:

# Initialize a new JAF project
jaf init my-agent-project

# Run the development server
jaf server --host 0.0.0.0 --port 8000

# Show version and help
jaf version
jaf --help

Development Setup

git clone https://github.com/xynehq/jaf-py
cd jaf-py
pip install -e ".[dev]"

# Run tests
pytest

# Type checking and linting
mypy jaf/
ruff check jaf/
black jaf/

# Documentation
pip install -r requirements-docs.txt
./docs.sh serve  # Start documentation server
./docs.sh deploy # Deploy to GitHub Pages

Documentation

Official Documentation Website

The complete, searchable documentation is available at xynehq.github.io/jaf-py with:

• Interactive navigation with search and filtering
• Dark/light mode with automatic system preference detection
• Mobile-responsive design for documentation on any device
• Live code examples with syntax highlighting
• API reference with auto-generated documentation
• Always up-to-date with automatic deployments

Local Documentation

For offline access, documentation is also available in the docs/ directory:

• Documentation Hub - Your starting point for all documentation
• Getting Started - Installation and first agent tutorial
• Core Concepts - JAF's functional architecture principles
• API Reference - Complete Python API documentation
• Tools Guide - Creating and using tools
• Memory System - Persistence and memory providers
• Model Providers - LiteLLM integration
• Monitoring - Observability, metrics, and alerting
• Server API - FastAPI endpoints reference
• Deployment - Production deployment guide
• Examples - Detailed example walkthroughs
• Troubleshooting - Common issues and solutions

Project Structure

jaf-py/
├── docs/                    # Complete documentation
├── jaf/                     # Core framework package
│   ├── core/               # Core types and engine
│   ├── memory/             # Conversation persistence
│   ├── providers/          # External integrations (LiteLLM, MCP)
│   ├── policies/           # Validation and security
│   ├── server/             # FastAPI server
│   └── cli.py              # Command-line interface
├── examples/               # Example applications
└── tests/                  # Test suite

Architectural Visualization

JAF includes powerful visualization capabilities to help you understand and document your agent systems.

Prerequisites

First, install the system Graphviz dependency:

# macOS
brew install graphviz

# Ubuntu/Debian  
sudo apt-get install graphviz

# Windows (via Chocolatey)
choco install graphviz

Then install JAF with visualization support:

pip install "jaf-py[visualization]"

Quick Start

import asyncio
from jaf import Agent, Tool, generate_agent_graph, GraphOptions

# Create your agents
agent = Agent(
    name='MyAgent',
    instructions=lambda state: "I am a helpful assistant.",
    tools=[my_tool],
    handoffs=['OtherAgent']
)

# Generate visualization
async def main():
    result = await generate_agent_graph(
        [agent],
        GraphOptions(
            title="My Agent System",
            output_path="./my-agents.png",
            color_scheme="modern",
            show_tool_details=True
        )
    )
    
    if result.success:
        print(f" Visualization saved to: {result.output_path}")
    else:
        print(f"❌ Error: {result.error}")

asyncio.run(main())

Features

• Multiple Color Schemes: Choose from default, modern, or minimal themes
• Agent Architecture: Visualize agents, tools, and handoff relationships
• Tool Ecosystems: Generate dedicated tool interaction diagrams
• Runner Architecture: Show complete system architecture with session layers
• Multiple Formats: Export as PNG, SVG, or PDF
• Customizable Layouts: Support for various Graphviz layouts (dot, circo, neato, etc.)

Example Output

The visualization system generates clear, professional diagrams showing:

• Agent Nodes: Rounded rectangles with agent names and model information
• Tool Nodes: Ellipses showing tool names and descriptions
• Handoff Edges: Dashed lines indicating agent handoff relationships
• Tool Connections: Colored edges connecting agents to their tools
• Cluster Organization: Grouped components in runner architecture views

Advanced Usage

from jaf.visualization import run_visualization_examples

# Run comprehensive examples
await run_visualization_examples()

# This generates multiple example files:
# - ./examples/agent-graph.png (agent system overview)
# - ./examples/tool-graph.png (tool ecosystem)  
# - ./examples/runner-architecture.png (complete system)
# - ./examples/agent-modern.png (modern color scheme)

Key Components

Core Types

from dataclasses import dataclass
from pydantic import BaseModel, Field
from jaf import Agent, Tool, RunState, run

# Define your context type
@dataclass
class MyContext:
    user_id: str
    permissions: list[str]

# Define tool schema
class CalculateArgs(BaseModel):
    expression: str = Field(description="Math expression to evaluate")

# Create a tool
class CalculatorTool:
    @property
    def schema(self):
        return type('ToolSchema', (), {
            'name': 'calculate',
            'description': 'Perform mathematical calculations',
            'parameters': CalculateArgs
        })()
    
    async def execute(self, args: CalculateArgs, context: MyContext) -> str:
        result = eval(args.expression)  # Don't do this in production!
        return f"{args.expression} = {result}"

# Define an agent
def create_math_agent():
    def instructions(state):
        return 'You are a helpful math tutor'
    
    return Agent(
        name='MathTutor',
        instructions=instructions,
        tools=[CalculatorTool()]
    )

Running the Framework

import asyncio
from jaf import run, make_litellm_provider, generate_run_id, generate_trace_id
from jaf.core.types import RunState, RunConfig, Message

async def main():
    model_provider = make_litellm_provider('http://localhost:4000')
    math_agent = create_math_agent()
    
    config = RunConfig(
        agent_registry={'MathTutor': math_agent},
        model_provider=model_provider,
        max_turns=10,
        on_event=lambda event: print(event),  # Real-time tracing
    )
    
    initial_state = RunState(
        run_id=generate_run_id(),
        trace_id=generate_trace_id(),
        messages=[Message(role='user', content='What is 2 + 2?')],
        current_agent_name='MathTutor',
        context=MyContext(user_id='user123', permissions=['user']),
        turn_count=0,
    )
    
    result = await run(initial_state, config)
    print(result.outcome.output if result.outcome.status == 'completed' else result.outcome.error)

asyncio.run(main())

Security & Validation

Composable Validation Policies

from jaf.policies.validation