Merge pull request #6 from Cyb3rWard0g/docs/home-page

Add Core Principles and Clarify Dapr Local Initialization

docs/home/concepts/floki.md

@@ -1,4 +1,4 @@
-# Enter Floki!
+# Enter Floki
 
 Floki is an open-source framework for building and orchestrating LLM-based autonomous agents, designed to simplify the complexity of creating scalable agentic workflows and microservices. Inspired by the growing need for frameworks that integrate seamlessly with distributed systems, Floki enables developers to focus on designing intelligent agents without getting bogged down by infrastructure concerns.
 

docs/home/concepts/principles.md

@@ -1,41 +1,81 @@
 # Core Principles
 
-## 1. Powered by Dapr
+## 1. Agent-Centric Design
 
-Floki leverages Dapr’s modular and scalable architecture to provide a foundation that simplifies:
+Floki is designed to place agents, powered by LLMs, at the core of task execution and workflow orchestration. This principle emphasizes:
 
-* Service communication: Built-in APIs for service-to-service invocation reduce the complexity of connecting agents and services.
-* Cloud integration: Deploy seamlessly across local, cloud, or hybrid environments.
-* Event-driven collaboration: Agents communicate effectively through Pub/Sub messaging, enabling dynamic task distribution and real-time updates.
+* LLM-Powered Agents: Floki enables the creation of agents that leverage LLMs for reasoning, dynamic decision-making, and natural language interactions.
+* Adaptive Task Handling: Agents in Floki are equipped with flexible patterns like tool calling and reasoning loops (e.g., ReAct), allowing them to autonomously tackle complex and evolving tasks.
+* Seamless Integration: Floki’s framework allows agents to act as modular, reusable building blocks that integrate seamlessly into workflows, whether they operate independently or collaboratively.
 
-## 2. Modular Component Architecture
+While Floki centers around agents, it also recognizes the versatility of using LLMs directly in deterministic workflows or simpler task sequences. In scenarios where the agent's built-in task-handling patterns, like `tool calling` or `ReAct` loops, are unnecessary, LLMs can act as core components for reasoning and decision-making. This flexibility ensures users can adapt Floki to suit diverse needs without being confined to a single approach.
 
-Floki inherits Dapr’s pluggable architecture, allowing developers to:
+!!! info
+    Agents are not standalone; they are building blocks in larger, orchestrated workflows.
 
-* Swap components like Pub/Sub systems (e.g., RabbitMQ → Kafka) or state stores (e.g., Redis → DynamoDB) without modifying application code.
-* Experiment with different setups locally or in the cloud, ensuring flexibility and adaptability.
-* Scale effortlessly by relying on modular, production-ready building blocks.
+## 2. Decoupled Infrastructure Design
 
-## 3. Virtual Actor Model for Agents
+Floki ensures a clean separation between agents and the underlying infrastructure, emphasizing simplicity, scalability, and adaptability:
 
-Floki uses Dapr’s Virtual Actor model to enable agents to act as:
+* Agent Simplicity: Agents focus purely on reasoning and task execution, while Pub/Sub messaging, routing, and validation are managed externally by modular infrastructure components.
+* Scalable and Adaptable Systems: By offloading non-agent-specific responsibilities, Floki allows agents to scale independently and adapt seamlessly to new use cases or integrations.
 
-* Stateful entities: Agents can retain context across interactions, ensuring continuity in workflows.
-* Independent units: Each agent processes tasks sequentially, simplifying concurrency management.
-* Scalable services: Agents scale seamlessly across nodes in a cluster, adapting to distributed environments.
+!!! info
+    Decoupling infrastructure keeps agents focused on tasks while enabling seamless scalability and integration across systems.
 
-## 4. Message-Driven Communication
+![](../../img/home_concepts_principles_decoupled.png)
 
-Floki emphasizes the use of Pub/Sub messaging to empower both event-driven and deterministic workflows. This principle ensures:
+## 3. Modular Component Model
 
-* Decoupled Architecture: Agents and services can communicate asynchronously, promoting scalability and flexibility.
-* Event-Driven Interactions: Agents respond to real-time events, allowing workflows to adapt dynamically.
-* Workflow Enablement: Pub/Sub acts as a backbone for coordinating agents in centralized or decentralized workflows.
+Floki utilizes [Dapr's pluggable component framework](https://docs.dapr.io/concepts/components-concept/) and building blocks to simplify development and enhance flexibility:
 
-## 5. Workflow-Oriented Design
+* Building Blocks for Core Functionality: Dapr provides API building blocks, such as Pub/Sub messaging, state management, service invocation, and more, to address common microservice challenges and promote best practices.
+* Interchangeable Components: Each building block operates on swappable components (e.g., Redis, Kafka, Azure CosmosDB), allowing you to replace implementations without changing application code.
+* Seamless Transitions: Develop locally with default configurations and deploy effortlessly to cloud environments by simply updating component definitions.
+* Scalable Foundations: Build resilient and adaptable architectures using Dapr’s modular, production-ready building blocks.
 
-Floki integrates Dapr’s Workflow API to orchestrate:
+!!! info
+    Developers can easily switch between different components (e.g., Redis to DynamoDB) based on their deployment environment, ensuring portability and adaptability.
 
-* Deterministic workflows: Define repeatable processes for agents to follow.
-* Dynamic decision-making: Combine rule-based logic with LLM-driven reasoning to handle complex, adaptive tasks.
-* Multi-agent collaboration: Coordinate agents across workflows for shared goals and efficient task execution.
+![](../../img/home_concepts_principles_modular.png)
+
+## 4. Actor-Based Model for Agents
+
+Floki leverages [Dapr’s Virtual Actor model](https://docs.dapr.io/developing-applications/building-blocks/actors/actors-overview/) to enable agents to function efficiently and flexibly within distributed environments. Each agent in Floki is instantiated as an instance of a class, wrapped and managed by a virtual actor. This design offers:
+
+* Stateful Agents: Virtual actors allow agents to store and recall information across tasks, maintaining context and continuity for workflows.
+* Dynamic Lifecycle Management: Virtual actors are automatically instantiated when invoked and deactivated when idle. This eliminates the need for explicit creation or cleanup, ensuring resource efficiency and simplicity.
+* Location Transparency: Agents can be accessed and operate seamlessly, regardless of where they are located in the system. The underlying runtime handles their mobility, enabling fault-tolerance and dynamic load balancing.
+* Scalable Execution: Agents process one task at a time, avoiding concurrency issues, and scale dynamically across nodes to meet workload demands.
+
+This model ensures agents remain focused on their core logic, while the infrastructure abstracts complexities like state management, fault recovery, and resource optimization.
+
+!!! info
+    Floki’s use of virtual actors makes agents always addressable and highly scalable, enabling them to operate reliably and efficiently in distributed, high-demand environments.
+
+## 5. Message-Driven Communication
+
+Floki emphasizes the use of Pub/Sub messaging for event-driven communication between agents. This principle ensures:
+
+* Decoupled Architecture: Asynchronous communication for scalability and modularity.
+* Real-Time Adaptability: Agents react dynamically to events for faster, more flexible task execution.
+* Seamless Collaboration: Agents share updates, distribute tasks, and respond to events in a highly coordinated way.
+
+!!! info
+    Pub/Sub messaging serves as the backbone for Floki’s event-driven workflows, enabling agents to communicate and collaborate in real time.
+
+![](../../img/home_concepts_principles_message.png)
+
+## 6. Workflow-Oriented Design
+
+Floki embraces workflows as a foundational concept, integrating [Dapr Workflows](https://docs.dapr.io/developing-applications/building-blocks/workflow/workflow-overview/) to support both deterministic and event-driven task orchestration. This dual approach enables robust and adaptive systems:
+
+* Deterministic Workflows: Floki uses Dapr Workflows for stateful, predictable task sequences. These workflows ensure reliable execution, fault tolerance, and state persistence, making them ideal for structured, multi-step processes that require clear, repeatable logic.
+* Event-Driven Workflows: By combining Dapr Workflows with Pub/Sub messaging, Floki supports workflows that adapt to real-time events. This facilitates decentralized, asynchronous collaboration between agents, allowing workflows to dynamically adjust to changing scenarios.
+
+By integrating these paradigms, Floki enables workflows that combine the reliability of deterministic execution with the adaptability of event-driven processes, ensuring flexibility and resilience in a wide range of applications.
+
+!!! info
+    Floki workflows blend structured, predictable logic with the dynamic responsiveness of event-driven systems, empowering both centralized and decentralized workflows.
+
+![](../../img/home_concepts_principles_workflows.png)

docs/home/installation.md

@@ -42,7 +42,9 @@ dapr -h
 !!! info
     Make sure you have [Docker](https://docs.docker.com/get-started/get-docker/) already installed. I use [Docker Desktop](https://www.docker.com/products/docker-desktop/).
 
-Initialize Dapr locally to set up a self-hosted environment for development. This process installs Dapr sidecar binaries, runs essential services like Redis (state store and message broker) and Zipkin (observability), and prepares a default components folder. For detailed steps, see the official [guide on initializing Dapr locally](https://docs.dapr.io/getting-started/install-dapr-selfhost/).
+Initialize Dapr locally to set up a self-hosted environment for development. This process fetches and installs the Dapr sidecar binaries, runs essential services as Docker containers, and prepares a default components folder for your application. For detailed steps, see the official [guide on initializing Dapr locally](https://docs.dapr.io/getting-started/install-dapr-selfhost/).
+
+![](../img/home_installation_init.png)
 
 To initialize the Dapr control plane containers and create a default configuration file, run:
 

mkdocs.yml

@@ -137,6 +137,6 @@ nav:
       - LLM-based Task Workflows: home/quickstarts/llm_workflows.md
       - Event-Driven Agentic Workflows: home/quickstarts/agentic_workflows.md
     - Concepts:
-      - Enter Floki!: home/concepts/floki.md
+      - Enter Floki: home/concepts/floki.md
       - Core Principles: home/concepts/principles.md
       - Agents: home/concepts/agents.md