flock-core 0.5.20__tar.gz → 0.5.21__tar.gz

{flock_core-0.5.20 → flock_core-0.5.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.5.20
+Version: 0.5.21
 Summary: Flock: A declrative framework for building and orchestrating AI agents.
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License: MIT
@@ -1071,7 +1071,7 @@ We're building enterprise infrastructure for AI agents and tracking the work pub
 ```python
 import os
 from flock import Flock, flock_type
-from flock.visibility import PrivateVisibility, TenantVisibility, LabelledVisibility
+from flock.core.visibility import PrivateVisibility, TenantVisibility, LabelledVisibility
 from flock.identity import AgentIdentity
 from pydantic import BaseModel
 

{flock_core-0.5.20 → flock_core-0.5.21}/README.md

@@ -1038,7 +1038,7 @@ We're building enterprise infrastructure for AI agents and tracking the work pub
 ```python
 import os
 from flock import Flock, flock_type
-from flock.visibility import PrivateVisibility, TenantVisibility, LabelledVisibility
+from flock.core.visibility import PrivateVisibility, TenantVisibility, LabelledVisibility
 from flock.identity import AgentIdentity
 from pydantic import BaseModel
 

{flock_core-0.5.20 → flock_core-0.5.21}/ROADMAP.md

@@ -96,7 +96,7 @@ Stay tuned to the issue tracker for milestone updates. We'll publish detailed re
 ```python
 import os
 from flock import Flock, flock_type
-from flock.visibility import PrivateVisibility, TenantVisibility, LabelledVisibility
+from flock.core.visibility import PrivateVisibility, TenantVisibility, LabelledVisibility
 from flock.identity import AgentIdentity
 from pydantic import BaseModel
 

{flock_core-0.5.20 → flock_core-0.5.21}/USECASES.md

@@ -121,7 +121,7 @@ Medical diagnostic systems require:
 
 ```python
 from flock import Flock
-from flock.visibility import PrivateVisibility, TenantVisibility, LabelledVisibility
+from flock.core.visibility import PrivateVisibility, TenantVisibility, LabelledVisibility
 from flock.registry import flock_type
 from pydantic import BaseModel
 
@@ -359,7 +359,7 @@ Multi-tenant platforms need:
 
 ```python
 from flock import Flock
-from flock.visibility import TenantVisibility
+from flock.core.visibility import TenantVisibility
 from flock.subscription import JoinSpec
 from flock.registry import flock_type
 from pydantic import BaseModel

{flock_core-0.5.20 → flock_core-0.5.21}/docs/about/changelog.md

@@ -448,7 +448,7 @@ class ResearchFindings(BaseModel):
 
 #### Public Visibility
 ```python
-from flock.visibility import PublicVisibility
+from flock.core.visibility import PublicVisibility
 
 @flock_type
 class PublicAnnouncement(BaseModel):
@@ -459,7 +459,7 @@ class PublicAnnouncement(BaseModel):
 
 #### Private Visibility
 ```python
-from flock.visibility import PrivateVisibility
+from flock.core.visibility import PrivateVisibility
 
 @flock_type
 class PrivateNote(BaseModel):
@@ -470,7 +470,7 @@ class PrivateNote(BaseModel):
 
 #### Tenant Visibility
 ```python
-from flock.visibility import TenantVisibility
+from flock.core.visibility import TenantVisibility
 
 @flock_type
 class PatientData(BaseModel):
@@ -482,7 +482,7 @@ class PatientData(BaseModel):
 
 #### Labelled Visibility
 ```python
-from flock.visibility import LabelledVisibility
+from flock.core.visibility import LabelledVisibility
 
 @flock_type
 class InternalReport(BaseModel):
@@ -493,7 +493,7 @@ class InternalReport(BaseModel):
 
 #### After Visibility
 ```python
-from flock.visibility import AfterVisibility
+from flock.core.visibility import AfterVisibility
 from datetime import datetime, timedelta
 
 @flock_type

{flock_core-0.5.20 → flock_core-0.5.21}/docs/getting-started/quick-start.md

@@ -269,7 +269,7 @@ trend_analyzer = (
 Control who sees what:
 
 ```python
-from flock.visibility import PrivateVisibility
+from flock.core.visibility import PrivateVisibility
 
 # Only specific agents can see this
 sensitive_data = (

{flock_core-0.5.20 → flock_core-0.5.21}/docs/guides/batch-processing.md

@@ -419,7 +419,7 @@ quality_control = (
 **Batch with access control:**
 
 ```python
-from flock.visibility import TenantVisibility
+from flock.core.visibility import TenantVisibility
 
 # Multi-tenant batch processing
 tenant_batcher = (

{flock_core-0.5.20 → flock_core-0.5.21}/docs/guides/blackboard.md

@@ -507,7 +507,7 @@ for artifact in artifacts:
 
 ```python
 # Get artifacts matching criteria
-from flock.visibility import TenantVisibility
+from flock.core.visibility import TenantVisibility
 
 patient_diagnoses = await flock.store.get_artifacts_by_type(
     "Diagnosis",

{flock_core-0.5.20 → flock_core-0.5.21}/docs/guides/context-providers.md

@@ -905,7 +905,7 @@ flock = Flock("openai/gpt-4.1", context_provider=global_provider)
 **Challenge:** Ensure Customer A's agents never see Customer B's data.
 
 ```python
-from flock.visibility import TenantVisibility
+from flock.core.visibility import TenantVisibility
 from flock.context_provider import FilteredContextProvider
 from flock.store import FilterConfig
 
@@ -1162,7 +1162,7 @@ for item in context:
 
 ```python
 # Test visibility filtering
-from flock.visibility import PrivateVisibility, PublicVisibility, AgentIdentity
+from flock.core.visibility import PrivateVisibility, PublicVisibility, AgentIdentity
 
 # Create test artifacts
 public_artifact = Artifact(visibility=PublicVisibility(), ...)
@@ -1366,7 +1366,7 @@ Here's everything together—a multi-tenant SaaS with role-based filtering and s
 import asyncio
 from pydantic import BaseModel
 from flock import Flock
-from flock.visibility import TenantVisibility, AgentIdentity, LabelledVisibility
+from flock.core.visibility import TenantVisibility, AgentIdentity, LabelledVisibility
 from flock.context_provider import FilteredContextProvider
 from flock.store import FilterConfig
 from examples.context_provider import PasswordRedactorProvider

{flock_core-0.5.20 → flock_core-0.5.21}/docs/guides/fan-out.md

@@ -546,7 +546,7 @@ notifier = (
 ### Dynamic Visibility
 
 ```python
-from flock.visibility import PrivateVisibility
+from flock.core.visibility import PrivateVisibility
 
 @flock_type
 class Notification(BaseModel):
@@ -579,7 +579,7 @@ notifier = (
 #### Role-Based Dynamic Visibility
 
 ```python
-from flock.visibility import LabelledVisibility
+from flock.core.visibility import LabelledVisibility
 
 @flock_type
 class Report(BaseModel):
@@ -610,7 +610,7 @@ report_generator = (
 #### Tenant-Based Dynamic Visibility
 
 ```python
-from flock.visibility import TenantVisibility
+from flock.core.visibility import TenantVisibility
 
 @flock_type
 class CustomerData(BaseModel):

{flock_core-0.5.20 → flock_core-0.5.21}/docs/guides/join-operations.md

@@ -471,7 +471,7 @@ quality_control = (
 **Correlate with access control:**
 
 ```python
-from flock.visibility import TenantVisibility
+from flock.core.visibility import TenantVisibility
 
 # Multi-tenant: Correlate orders + shipments per tenant
 tenant_notifications = (

{flock_core-0.5.20 → flock_core-0.5.21}/docs/guides/patterns.md

@@ -1048,7 +1048,7 @@ editor = (
 **Example:**
 
 ```python
-from flock.visibility import PrivateVisibility, LabelledVisibility, TenantVisibility
+from flock.core.visibility import PrivateVisibility, LabelledVisibility, TenantVisibility
 from flock.runtime import AgentIdentity
 
 @flock_type

{flock_core-0.5.20 → flock_core-0.5.21}/docs/guides/testing.md

@@ -290,7 +290,7 @@ async def test_batch_processing():
 Test access control with visibility types.
 
 ```python
-from flock.visibility import PrivateVisibility, TenantVisibility
+from flock.core.visibility import PrivateVisibility, TenantVisibility
 from flock.identity import AgentIdentity
 
 @pytest.mark.asyncio

{flock_core-0.5.20 → flock_core-0.5.21}/docs/guides/use-cases.md

@@ -121,7 +121,7 @@ Medical diagnostic systems require:
 
 ```python
 from flock import Flock
-from flock.visibility import PrivateVisibility, TenantVisibility, LabelledVisibility
+from flock.core.visibility import PrivateVisibility, TenantVisibility, LabelledVisibility
 from flock.registry import flock_type
 from pydantic import BaseModel
 
@@ -359,7 +359,7 @@ Multi-tenant platforms need:
 
 ```python
 from flock import Flock
-from flock.visibility import TenantVisibility
+from flock.core.visibility import TenantVisibility
 from flock.subscription import JoinSpec
 from flock.registry import flock_type
 from pydantic import BaseModel

{flock_core-0.5.20 → flock_core-0.5.21}/docs/guides/visibility.md

@@ -112,7 +112,7 @@ graph TB
 **Everyone can see the artifact.**
 
 ```python
-from flock.visibility import PublicVisibility
+from flock.core.visibility import PublicVisibility
 
 agent = (
     flock.agent("reporter")
@@ -136,7 +136,7 @@ agent = (
 **Only specified agents can see the artifact.**
 
 ```python
-from flock.visibility import PrivateVisibility
+from flock.core.visibility import PrivateVisibility
 
 field_agent = (
     flock.agent("field_agent")
@@ -163,7 +163,7 @@ field_agent = (
 **Only agents belonging to the same tenant can see the artifact.**
 
 ```python
-from flock.visibility import TenantVisibility
+from flock.core.visibility import TenantVisibility
 
 analyzer = (
     flock.agent("analyzer")
@@ -190,7 +190,7 @@ analyzer = (
 **Only agents with required labels can see the artifact.**
 
 ```python
-from flock.visibility import LabelledVisibility, AgentIdentity
+from flock.core.visibility import LabelledVisibility, AgentIdentity
 
 # Agent with security clearance
 analyst = (
@@ -223,7 +223,7 @@ analyst = (
 
 ```python
 from datetime import timedelta
-from flock.visibility import AfterVisibility, PublicVisibility
+from flock.core.visibility import AfterVisibility, PublicVisibility
 
 pr_team = (
     flock.agent("pr_team")
@@ -253,7 +253,7 @@ pr_team = (
 Agents need **identities** to interact with visibility controls:
 
 ```python
-from flock.visibility import AgentIdentity
+from flock.core.visibility import AgentIdentity
 
 agent = (
     flock.agent("analyst")
@@ -409,7 +409,7 @@ visible_artifacts = [
 **Challenge:** Patient data must only be accessible to treating physicians.
 
 ```python
-from flock.visibility import PrivateVisibility, LabelledVisibility
+from flock.core.visibility import PrivateVisibility, LabelledVisibility
 
 # Patient record only for treating physician
 doctor = (
@@ -438,7 +438,7 @@ lab_tech = (
 **Challenge:** Complete data isolation between customers.
 
 ```python
-from flock.visibility import TenantVisibility
+from flock.core.visibility import TenantVisibility
 
 # Each customer's portfolio is isolated
 trading_agent = (
@@ -458,7 +458,7 @@ trading_agent = (
 **Challenge:** Free users see basic features, pro users see advanced analytics.
 
 ```python
-from flock.visibility import LabelledVisibility
+from flock.core.visibility import LabelledVisibility
 
 # Basic reports for free and pro users
 analyzer = (
@@ -489,7 +489,7 @@ advanced_analyzer = (
 **Challenge:** Multi-level security clearances (Unclassified → Secret → Top Secret).
 
 ```python
-from flock.visibility import LabelledVisibility, AgentIdentity
+from flock.core.visibility import LabelledVisibility, AgentIdentity
 
 # Field agent collects classified intel
 field_ops = (
@@ -519,7 +519,7 @@ analyst = (
 
 ```python
 from datetime import timedelta
-from flock.visibility import AfterVisibility, PublicVisibility
+from flock.core.visibility import AfterVisibility, PublicVisibility
 
 # Embargo for 7 days, then public
 pr_team = (
@@ -788,7 +788,7 @@ import asyncio
 from datetime import timedelta
 from pydantic import BaseModel, Field
 from flock import Flock, flock_type
-from flock.visibility import (
+from flock.core.visibility import (
     PublicVisibility,
     PrivateVisibility,
     TenantVisibility,

{flock_core-0.5.20 → flock_core-0.5.21}/docs/reference/index.md

@@ -173,7 +173,7 @@ class BotResponse(BaseModel):
 ## Visibility Enums
 
 ```python
-from flock.visibility import (
+from flock.core.visibility import (
     Visibility,      # Base visibility enum
     PublicVisibility,
     PrivateVisibility,

{flock_core-0.5.20/examples/00-patterns → flock_core-0.5.21/examples/00-patterns/publish}/01-single_publish.py

@@ -32,7 +32,6 @@ flock = Flock()
 
 # Single Publish
 single_movie_master = flock.agent("single_movie_master").consumes(Idea).publishes(Movie)
-single_book_master = flock.agent("single_book_master").consumes(Idea).publishes(Book)
 
 
 async def main():

{flock_core-0.5.20/examples/00-patterns → flock_core-0.5.21/examples/00-patterns/publish}/02-multi_publish.py

@@ -14,12 +14,9 @@ class Idea(BaseModel):
 @flock_type
 class Character(BaseModel):
     name: str
-    potential_actors: dict[str, str] = Field(
-        ..., description="Potential actors and reasons why they are a good fit"
-    )
+    potential_actors: dict[str, str] = Field(..., description="Potential actors and reasons why they are a good fit")
     backstory: str
 
-
 @flock_type
 class Movie(BaseModel):
     title: str
@@ -39,9 +36,7 @@ class MovieScript(BaseModel):
 
 @flock_type
 class MovieCampaign(BaseModel):
-    taglines: list[str] = Field(
-        ..., description="Catchy phrases to promote the movie. IN ALL CAPS"
-    )
+    taglines: list[str] = Field(..., description="Catchy phrases to promote the movie. IN ALL CAPS")
     poster_descriptions: list[str] = Field(max_length=3)
 
 
@@ -50,9 +45,7 @@ flock = Flock()
 
 # Multi-Publish
 multi_master = (
-    flock.agent("multi_master")
-    .consumes(Idea)
-    .publishes(Movie, MovieScript, MovieCampaign)
+    flock.agent("multi_master").consumes(Idea).publishes(Movie, MovieScript, MovieCampaign)
 )
 
 

{flock_core-0.5.20/examples/00-patterns → flock_core-0.5.21/examples/00-patterns/publish}/03-multi-artifact-multi-publish.py

@@ -14,12 +14,9 @@ class Idea(BaseModel):
 @flock_type
 class Character(BaseModel):
     name: str
-    potential_actors: dict[str, str] = Field(
-        ..., description="Potential actors and reasons why they are a good fit"
-    )
+    potential_actors: dict[str, str] = Field(..., description="Potential actors and reasons why they are a good fit")
     backstory: str
 
-
 @flock_type
 class Movie(BaseModel):
     title: str
@@ -39,9 +36,7 @@ class MovieScript(BaseModel):
 
 @flock_type
 class MovieCampaign(BaseModel):
-    taglines: list[str] = Field(
-        ..., description="Catchy phrases to promote the movie. IN ALL CAPS"
-    )
+    taglines: list[str] = Field(..., description="Catchy phrases to promote the movie. IN ALL CAPS")
     poster_descriptions: list[str] = Field(max_length=3)
 
 
@@ -50,11 +45,7 @@ flock = Flock()
 
 # Multi-Publish
 multi_master = (
-    flock.agent("multi_master")
-    .consumes(Idea)
-    .publishes(Movie)
-    .publishes(MovieScript)
-    .publishes(MovieCampaign)
+    flock.agent("multi_master").consumes(Idea).publishes(Movie).publishes(MovieScript).publishes(MovieCampaign)
 )
 
 

{flock_core-0.5.20/examples/00-patterns → flock_core-0.5.21/examples/00-patterns/publish}/04-fan-out.py

@@ -20,12 +20,11 @@ class Movie(BaseModel):
     plot_summary: str
 
 
+
 flock = Flock()
 
 # Single Publish
-fan_out_movie_master = (
-    flock.agent("fan_out_movie_master").consumes(Idea).publishes(Movie, fan_out=4)
-)
+fan_out_movie_master = flock.agent("fan_out_movie_master").consumes(Idea).publishes(Movie,fan_out=4)
 
 
 async def main():

{flock_core-0.5.20/examples/00-patterns → flock_core-0.5.21/examples/00-patterns/publish}/05-multi-fan-out.py

@@ -14,12 +14,9 @@ class Idea(BaseModel):
 @flock_type
 class Character(BaseModel):
     name: str
-    potential_actors: dict[str, str] = Field(
-        ..., description="Potential actors and reasons why they are a good fit"
-    )
+    potential_actors: dict[str, str] = Field(..., description="Potential actors and reasons why they are a good fit")
     backstory: str
 
-
 @flock_type
 class Movie(BaseModel):
     title: str
@@ -31,6 +28,7 @@ class Movie(BaseModel):
 
 @flock_type
 class MovieScript(BaseModel):
+    title: str
     characters: list[str] = Field(min_length=5)
     chapter_headings: list[str] = Field(min_length=5)
     scenes: list[str] = Field(min_length=5)
@@ -39,9 +37,8 @@ class MovieScript(BaseModel):
 
 @flock_type
 class MovieCampaign(BaseModel):
-    taglines: list[str] = Field(
-        ..., description="Catchy phrases to promote the movie. IN ALL CAPS"
-    )
+    title: str
+    taglines: list[str] = Field(..., description="Catchy phrases to promote the movie. IN ALL CAPS")
     poster_descriptions: list[str] = Field(max_length=3)
 
 
@@ -54,11 +51,20 @@ flock = Flock()
 # - Pydantic validation on every field (min_length, ge/le constraints, custom descriptions)
 # - All generated coherently in ONE LLM call!
 multi_master = (
-    flock.agent("multi_master")
-    .consumes(Idea)
-    .publishes(Movie, MovieScript, MovieCampaign, fan_out=3)
+    flock.agent("multi_master").consumes(Idea).publishes(Movie, MovieScript, MovieCampaign, fan_out=3)
 )
 
+# compare with
+
+# multi_master = (
+#     flock.agent("multi_master").consumes(Idea).publishes(Movie, MovieScript, MovieCampaign).publishes(Movie, MovieScript, MovieCampaign).publishes(Movie, MovieScript, MovieCampaign)
+# )
+
+# or
+
+# multi_master = (
+#     flock.agent("multi_master").consumes(Idea).publishes(Movie, fan_out=3).publishes(MovieScript, fan_out=3).publishes(MovieCampaign, fan_out=3)
+# )
 
 async def main():
     idea = Idea(story_idea="An action thriller set in space")

{flock_core-0.5.20/examples/08-context-provider → flock_core-0.5.21/examples/00-patterns/visibility}/01_basic_visibility.py

@@ -55,14 +55,14 @@ async def main():
         flock.agent("public_agent")
         .description("A regular agent without security clearance")
         .consumes(Message)
-        .publishes(Report)
+        .publishes(Report, visibility=PrivateVisibility(agents={"hidden"}))
     )
 
     classified_agent = (
         flock.agent("classified_agent")
         .description("An agent with security clearance")
         .consumes(Message)
-        .publishes(Report)
+        .publishes(Report, visibility=PrivateVisibility(agents={"hidden"})) # important since report may contain classified info
     )
 
     # Publish some messages - mix of public and classified

flock_core-0.5.21/examples/01-getting-started/01_declarative_pizza.py

@@ -0,0 +1,65 @@
+"""
+Getting Started: Declarative Pizza Generation
+
+This example demonstrates the core concept of Flock: agents declaring what they
+consume and produce, with the orchestrator handling the rest.
+
+🎛️  CONFIGURATION: Set USE_DASHBOARD to switch between CLI and Dashboard modes
+"""
+
+import asyncio
+
+from pydantic import BaseModel, Field
+
+from flock import Flock
+from flock.registry import flock_type
+
+# ============================================================================
+# 🎛️  CONFIGURATION: Switch between CLI and Dashboard modes
+# ============================================================================
+USE_DASHBOARD = True  # Set to True for dashboard mode, False for CLI mode
+# ============================================================================
+
+
+@flock_type
+class MyDreamPizza(BaseModel):
+    pizza_idea: str = Field(
+        default="Pizza with pineapple", description="A short description of your dream pizza"
+    )
+
+
+@flock_type
+class Pizza(BaseModel):
+    ingredients: list[str]
+    size: str
+    crust_type: str
+    step_by_step_instructions: list[str]
+
+
+flock = Flock()
+
+pizza_master = flock.agent("pizza_master").consumes(MyDreamPizza).publishes(Pizza)
+
+
+async def main_cli():
+    """CLI mode: Run agents and display results in terminal"""
+    pizza_idea = MyDreamPizza(pizza_idea="pizza with pineapple")
+    await flock.publish(pizza_idea)
+    await flock.run_until_idle()
+    print("✅ Pizza generation complete! Check the dashboard for results.")
+
+
+async def main_dashboard():
+    """Dashboard mode: Serve with interactive web interface"""
+    await flock.serve(dashboard=True)
+
+
+async def main():
+    if USE_DASHBOARD:
+        await main_dashboard()
+    else:
+        await main_cli()
+
+
+if __name__ == "__main__":
+    asyncio.run(main(), debug=True)

{flock_core-0.5.20/examples/01-cli → flock_core-0.5.21/examples/01-getting-started}/02_input_and_output.py

@@ -1,3 +1,12 @@
+"""
+Getting Started: Input and Output
+
+This example shows how to create agents that consume input and produce output,
+with proper type definitions and documentation.
+
+🎛️  CONFIGURATION: Set USE_DASHBOARD to switch between CLI and Dashboard modes
+"""
+
 import asyncio
 
 from pydantic import BaseModel, Field
@@ -5,6 +14,12 @@ from pydantic import BaseModel, Field
 from flock import Flock
 from flock.registry import flock_type
 
+# ============================================================================
+# 🎛️  CONFIGURATION: Switch between CLI and Dashboard modes
+# ============================================================================
+USE_DASHBOARD = False  # Set to True for dashboard mode, False for CLI mode
+# ============================================================================
+
 
 @flock_type
 class UserRequest(BaseModel):
@@ -29,7 +44,8 @@ assistant = (
 )
 
 
-async def main():
+async def main_cli():
+    """CLI mode: Run agents and display results in terminal"""
     request = UserRequest(
         message="What are the key benefits of async programming?", priority="high"
     )
@@ -50,5 +66,17 @@ async def main():
             print(f"   {i}. {source}")
 
 
+async def main_dashboard():
+    """Dashboard mode: Serve with interactive web interface"""
+    await flock.serve(dashboard=True)
+
+
+async def main():
+    if USE_DASHBOARD:
+        await main_dashboard()
+    else:
+        await main_cli()
+
+
 if __name__ == "__main__":
     asyncio.run(main())