zero-agent 0.1.0__py3-none-any.whl

agentz/profiles/base.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+import re
+from typing import Optional, List, Type, Set
+from pydantic import BaseModel, Field, model_validator
+
+
+class ToolAgentOutput(BaseModel):
+    """Standard output for all tool agents"""
+    output: str
+    sources: list[str] = Field(default_factory=list)
+
+
+class Profile(BaseModel):
+    instructions: str = Field(description="The agent's system prompt/instructions that define its behavior")
+    runtime_template: str = Field(description="The runtime template for the agent's behavior")
+    model: Optional[str] = Field(default=None, description="Model override for this profile (e.g., 'gpt-4', 'claude-3-5-sonnet')")
+    output_schema: Optional[Type[BaseModel]] = Field(default=None, description="Pydantic model class for structured output validation")
+    input_schema: Optional[Type[BaseModel]] = Field(default=None, description="Pydantic model class for input validation")
+    tools: Optional[List[str]] = Field(default=None, description="List of tools to use for this profile")
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    @model_validator(mode='after')
+    def validate_runtime_template_placeholders(self) -> 'Profile':
+        """Validate that all placeholders in runtime_template match fields in input_schema."""
+        if not self.runtime_template or not self.input_schema:
+            return self
+
+        # Extract placeholders from runtime_template (format: [[FIELD_NAME]])
+        placeholder_pattern = r'\[\[([A-Z_]+)\]\]'
+        placeholders: Set[str] = set(re.findall(placeholder_pattern, self.runtime_template))
+
+        # Get field names from input_schema and convert to uppercase
+        schema_fields: Set[str] = {field_name.upper() for field_name in self.input_schema.model_fields.keys()}
+
+        # Check for mismatches
+        missing_in_schema = placeholders - schema_fields
+
+        if missing_in_schema:
+            raise ValueError(
+                f"Runtime template contains placeholders that don't match input_schema fields: "
+                f"{missing_in_schema}. Available fields in input_schema (uppercase): {schema_fields}"
+            )
+
+        return self
+
+    def render(self, **kwargs) -> str:
+        """Render the runtime template with provided keyword arguments.
+
+        Args:
+            **kwargs: Values to substitute for placeholders in the template.
+                     Keys are matched case-insensitively with [[PLACEHOLDER]] patterns.
+
+        Returns:
+            Rendered template string with all placeholders replaced.
+
+        Examples:
+            profile.render(QUERY="What is AI?", HISTORY="Previous context...")
+        """
+        result = self.runtime_template
+        # Replace [[KEY]] placeholders with provided values
+        for key, value in kwargs.items():
+            placeholder = f"[[{key.upper()}]]"
+            result = result.replace(placeholder, str(value))
+        return result
+
+
+def load_all_profiles():
+    """Load all Profile instances from the profiles package.
+
+    Returns:
+        Dict with shortened keys (e.g., "observe" instead of "observe_profile")
+        Each profile has a _key attribute added for automatic name derivation
+    """
+    import importlib
+    import inspect
+    from pathlib import Path
+
+    profiles = {}
+    package_path = Path(__file__).parent
+
+    # Recursively find all .py files in the profiles directory
+    for py_file in package_path.rglob('*.py'):
+        if py_file.name == 'base.py' or py_file.name.startswith('_'):
+            continue
+
+        # Convert file path to module name (need to find 'agentz' root)
+        # Go up from current file: profiles/base.py -> profiles -> agentz
+        agentz_root = package_path.parent
+        relative_path = py_file.relative_to(agentz_root)
+        module_name = 'agentz.' + str(relative_path.with_suffix('')).replace('/', '.')
+
+        try:
+            module = importlib.import_module(module_name)
+            for name, obj in inspect.getmembers(module):
+                if isinstance(obj, Profile) and not name.startswith('_'):
+                    # Strip "_profile" suffix from key for cleaner access
+                    key = name.replace('_profile', '') if name.endswith('_profile') else name
+                    # Add _key attribute to profile for automatic name derivation
+                    obj._key = key
+                    profiles[key] = obj
+        except Exception:
+            pass
+
+    return profiles
+
+

agentz/profiles/data/data_analysis.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from agentz.profiles.base import Profile, ToolAgentOutput
+
+
+class TaskInput(BaseModel):
+    """Input schema for task-based runtime template."""
+    task: str = Field(description="The task to perform")
+
+
+# Profile instance for data analysis agent
+data_analysis_profile = Profile(
+    instructions="""You are an exploratory data analysis specialist. Your task is to analyze data patterns and relationships.
+
+Steps:
+1. Use the analyze_data tool (it automatically uses the currently loaded dataset)
+   - If a target_column is mentioned in the task, pass it as a parameter
+   - The tool will analyze the dataset that was previously loaded
+2. The tool returns: distributions, correlations, outliers (IQR method), patterns, recommendations
+3. Write a 3+ paragraph summary covering:
+   - Key statistical insights (means, medians, distributions)
+   - Important correlations (>0.7) and relationships
+   - Outlier percentages and potential impact
+   - Data patterns and anomalies identified
+   - Preprocessing recommendations based on findings
+
+Include specific numbers, correlation values, and percentages.
+
+Output JSON only following this schema:
+[[OUTPUT_SCHEMA]]""",
+    runtime_template="[[TASK]]",
+    output_schema=ToolAgentOutput,
+    input_schema=TaskInput,
+    tools=["analyze_data"],
+    model=None
+)

agentz/profiles/data/data_loader.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from agentz.profiles.base import Profile, ToolAgentOutput
+
+
+class TaskInput(BaseModel):
+    """Input schema for task-based runtime template."""
+    task: str = Field(description="The task to perform")
+
+
+# Profile instance for data loader agent
+data_loader_profile = Profile(
+    instructions="""You are a data loading specialist. Your task is to load and inspect datasets.
+
+Steps:
+1. Use the load_dataset tool with the provided file path
+2. The tool returns: shape, columns, dtypes, missing values, sample data, statistics, memory usage, duplicates
+3. Write a 2-3 paragraph summary covering:
+   - Dataset size and structure
+   - Data types and columns
+   - Data quality issues (missing values, duplicates)
+   - Key statistics and initial observations
+
+Include specific numbers and percentages in your summary.
+
+Output JSON only following this schema:
+[[OUTPUT_SCHEMA]]""",
+    runtime_template="[[TASK]]",
+    output_schema=ToolAgentOutput,
+    input_schema=TaskInput,
+    tools=["load_dataset"],
+    model=None
+)

agentz/profiles/data/evaluation.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from agentz.profiles.base import Profile, ToolAgentOutput
+
+
+class TaskInput(BaseModel):
+    """Input schema for task-based runtime template."""
+    task: str = Field(description="The task to perform")
+
+
+# Profile instance for evaluation agent
+evaluation_profile = Profile(
+    instructions="""You are a model evaluation specialist. Your task is to assess model performance comprehensively.
+
+Steps:
+1. Use the evaluate_model tool (it automatically uses the currently loaded dataset)
+   - Required: target_column (which column was predicted)
+   - Optional: model_type (default: random_forest)
+   - The tool will evaluate on the dataset that was previously loaded/preprocessed
+2. The tool returns:
+   - Classification: accuracy, precision, recall, F1, confusion matrix, per-class metrics, CV results
+   - Regression: R², RMSE, MAE, MAPE, error analysis, CV results
+3. Write a 3+ paragraph summary covering:
+   - Overall performance with key metrics
+   - Confusion matrix or error distribution analysis
+   - Per-class/per-feature insights
+   - Cross-validation and generalization
+   - Model strengths and weaknesses
+   - Improvement recommendations
+   - Production readiness
+
+Include specific numbers and identify weak areas.
+
+Output JSON only following this schema:
+[[OUTPUT_SCHEMA]]""",
+    runtime_template="[[TASK]]",
+    output_schema=ToolAgentOutput,
+    input_schema=TaskInput,
+    tools=["evaluate_model"],
+    model=None
+)

agentz/profiles/data/model_training.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from agentz.profiles.base import Profile, ToolAgentOutput
+
+
+class TaskInput(BaseModel):
+    """Input schema for task-based runtime template."""
+    task: str = Field(description="The task to perform")
+
+
+# Profile instance for model training agent
+model_training_profile = Profile(
+    instructions="""You are a machine learning specialist. Your task is to train and evaluate models.
+
+Model types:
+- auto: Auto-detect best model
+- random_forest: Random Forest (classification/regression)
+- logistic_regression: Logistic Regression
+- linear_regression: Linear Regression
+- decision_tree: Decision Tree
+
+Steps:
+1. Use the train_model tool (it automatically uses the currently loaded dataset)
+   - Required: target_column (which column to predict)
+   - Optional: model_type (default: auto)
+   - The tool will train on the dataset that was previously loaded/preprocessed
+2. The tool returns: model type, problem type, train/test scores, CV results, feature importance, predictions
+3. Write a 3+ paragraph summary covering:
+   - Model selection and problem type
+   - Train/test performance with interpretation
+   - Cross-validation results and stability
+   - Top feature importances
+   - Overfitting/underfitting analysis
+   - Improvement recommendations
+
+Include specific metrics (accuracy, R², CV mean±std).
+
+Output JSON only following this schema:
+[[OUTPUT_SCHEMA]]""",
+    runtime_template="[[TASK]]",
+    output_schema=ToolAgentOutput,
+    input_schema=TaskInput,
+    tools=["train_model"],
+    model=None
+)

agentz/profiles/data/preprocessing.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from agentz.profiles.base import Profile, ToolAgentOutput
+
+
+class TaskInput(BaseModel):
+    """Input schema for task-based runtime template."""
+    task: str = Field(description="The task to perform")
+
+
+# Profile instance for preprocessing agent
+preprocessing_profile = Profile(
+    instructions="""You are a data preprocessing specialist. Your task is to clean and transform datasets.
+
+Available operations:
+- handle_missing: Fill missing values (mean/median/mode)
+- remove_duplicates: Remove duplicate rows
+- encode_categorical: Encode categorical variables
+- scale_standard: Z-score normalization
+- scale_minmax: Min-max scaling [0, 1]
+- remove_outliers: IQR method
+- feature_engineering: Create interaction features
+
+Steps:
+1. Use the preprocess_data tool (it automatically uses the currently loaded dataset)
+   - Required: operations list (which operations to perform)
+   - Optional: target_column (if mentioned in the task)
+   - The tool will preprocess the dataset that was previously loaded
+2. The tool returns: operations applied, shape changes, summary of changes
+3. Write a 2-3 paragraph summary covering:
+   - Operations performed and justification
+   - Shape changes and data modifications
+   - Impact on data quality
+   - Next steps (modeling, further preprocessing)
+
+Include specific numbers (rows removed, values filled, etc.).
+
+Output JSON only following this schema:
+[[OUTPUT_SCHEMA]]""",
+    runtime_template="[[TASK]]",
+    output_schema=ToolAgentOutput,
+    input_schema=TaskInput,
+    tools=["preprocess_data"],
+    model=None
+)

agentz/profiles/data/visualization.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from agentz.profiles.base import Profile, ToolAgentOutput
+
+
+class TaskInput(BaseModel):
+    """Input schema for task-based runtime template."""
+    task: str = Field(description="The task to perform")
+
+
+# Profile instance for visualization agent
+visualization_profile = Profile(
+    instructions="""You are a data visualization specialist. Your task is to create insightful visualizations.
+
+Plot types:
+- distribution: Histograms for numerical columns
+- correlation: Heatmap for feature relationships
+- scatter: 2D relationship plot (needs 2 columns)
+- box: Outlier detection
+- bar: Categorical data comparison
+- pairplot: Pairwise relationships
+
+Steps:
+1. Use the create_visualization tool (it automatically uses the currently loaded dataset)
+   - Required: plot_type (which type of visualization to create)
+   - Optional: columns (which columns to include), target_column (for coloring)
+   - The tool will visualize the dataset that was previously loaded/preprocessed
+2. The tool returns: plot type, columns plotted, output path, visual insights
+3. Write a 2-3 paragraph summary covering:
+   - Visualization type and purpose
+   - Key patterns observed
+   - Data interpretation and context
+   - Actionable recommendations
+   - Suggestions for additional plots
+
+Include specific observations (correlation values, outlier %, distribution shapes).
+
+Output JSON only following this schema:
+[[OUTPUT_SCHEMA]]""",
+    runtime_template="[[TASK]]",
+    output_schema=ToolAgentOutput,
+    input_schema=TaskInput,
+    tools=["create_visualization"],
+    model=None
+)

agentz/profiles/manager/evaluate.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import List
+from pydantic import BaseModel, Field
+
+from agentz.profiles.base import Profile
+
+
+class EvaluateInput(BaseModel):
+    """Input schema for evaluate agent runtime template."""
+    iteration: int = Field(description="Current iteration number")
+    elapsed_minutes: float = Field(description="Time elapsed in minutes")
+    max_minutes: float = Field(description="Maximum allowed minutes")
+    query: str = Field(description="Original user query")
+    history: str = Field(description="History of actions, findings and thoughts")
+
+
+class EvaluateOutput(BaseModel):
+    """Output schema for evaluate agent."""
+    research_complete: bool = Field(description="Boolean indicating if research is done")
+    outstanding_gaps: List[str] = Field(description="List of specific gaps that still need addressing", default_factory=list)
+    reasoning: str = Field(description="Clear explanation of the evaluation")
+
+
+# Profile instance for evaluate agent
+evaluate_profile = Profile(
+    instructions="""You are a research evaluation agent. Analyze research progress and determine if goals have been met.
+
+Your responsibilities:
+1. Assess whether the research task has been completed
+2. Identify any remaining knowledge gaps
+3. Provide clear reasoning for your evaluation
+4. Suggest specific next steps if research is incomplete
+
+Evaluate the research state and provide structured output with:
+- research_complete: boolean indicating if research is done
+- outstanding_gaps: list of specific gaps that still need addressing
+- reasoning: clear explanation of your evaluation""",
+    runtime_template="""Current Iteration Number: [[ITERATION]]
+Time Elapsed: [[ELAPSED_MINUTES]] minutes of maximum [[MAX_MINUTES]] minutes
+
+ORIGINAL QUERY:
+[[QUERY]]
+
+HISTORY OF ACTIONS, FINDINGS AND THOUGHTS:
+[[HISTORY]]""",
+    output_schema=EvaluateOutput,
+    input_schema=EvaluateInput,
+    tools=None,
+    model=None
+)

agentz/profiles/manager/memory.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from agentz.profiles.base import Profile
+
+
+class MemoryInput(BaseModel):
+    """Input schema for memory agent runtime template."""
+    iteration: int = Field(description="Current iteration number")
+    query: str = Field(description="Original user query")
+    last_summary: str = Field(description="Last generated summary")
+    conversation_history: str = Field(description="Recent conversation history")
+
+
+class MemoryAgentOutput(BaseModel):
+    """Output schema for memory agent."""
+    summary: str = Field(description="Summary of the conversation history", default="")
+
+
+# Profile instance for memory agent
+memory_profile = Profile(
+    instructions="""You are a memory agent. Your role is to store and retrieve information from the conversation history.
+
+Your responsibilities:
+1. Thoroughly evaluate the conversation history and current question
+2. Provide a comprehensive summary that will help answer the question.
+3. Analyze progress made since the last summary
+4. Generate a useful summary that combines previous and new information
+5. Maintain continuity, especially when recent conversation history is limited
+
+Task Guidelines
+
+1. Information Analysis:
+  - Carefully analyze the conversation history to identify truly useful information.
+  - Focus on information that directly contributes to answering the question.
+  - Do NOT make assumptions, guesses, or inferences beyond what is explicitly stated.
+  - If information is missing or unclear, do NOT include it in your summary.
+  - Use the last summary as a baseline when recent history is sparse.
+
+2. Summary Requirements:
+  - Extract only the most relevant information that is explicitly present in the conversation.
+  - Synthesize information from multiple exchanges when relevant.
+  - Only include information that is certain and clearly stated.
+  - Do NOT output or mention any information that is uncertain, insufficient, or cannot be confirmed.
+
+Strictly avoid fabricating, inferring, or exaggerating any information not present in the conversation. Only output information that is certain and explicitly stated.""",
+    runtime_template="""You are at the end of iteration [[ITERATION]]. You need to generate a comprehensive and useful summary.
+
+ORIGINAL QUERY:
+[[QUERY]]
+
+LAST SUMMARY:
+[[LAST_SUMMARY]]
+
+CONVERSATION HISTORY:
+[[CONVERSATION_HISTORY]]""",
+    output_schema=MemoryAgentOutput,
+    input_schema=MemoryInput,
+    tools=None,
+    model=None
+)

agentz/profiles/manager/observe.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from agentz.profiles.base import Profile
+
+
+class ObserveInput(BaseModel):
+    """Input schema for observe agent runtime template."""
+    iteration: int = Field(description="Current iteration number")
+    query: str = Field(description="Original user query")
+    history: str = Field(description="History of actions, findings and thoughts")
+
+
+# Profile instance for observe agent
+observe_profile = Profile(
+    instructions="""You are a research observation agent. Your role is to analyze the current state of research and provide thoughtful observations.
+
+Your responsibilities:
+1. Reflect on the progress made so far
+2. Identify patterns and insights from previous iterations
+3. Consider what has been learned and what remains unclear
+4. Provide strategic thinking about next steps
+5. Generate actionable observations that guide the research process
+
+Analyze the provided context including:
+- The original query/task
+- Current iteration number and time elapsed
+- Background context
+- Previous iterations, actions, findings, and thoughts
+
+Provide concise but insightful observations that help guide the research process. Focus on:
+- What we've learned so far
+- What patterns are emerging
+- What areas need deeper investigation
+- Strategic recommendations for next steps""",
+    runtime_template="""You are starting iteration [[ITERATION]] of your research process.
+
+ORIGINAL QUERY:
+[[QUERY]]
+
+HISTORY OF ACTIONS, FINDINGS AND THOUGHTS:
+[[HISTORY]]""",
+    output_schema=None,
+    input_schema=ObserveInput,
+    tools=None,
+    model=None
+)

agentz/profiles/manager/routing.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import List, Optional
+from pydantic import BaseModel, Field
+
+from agentz.profiles.base import Profile
+
+
+class AgentTask(BaseModel):
+    """Task definition for routing to specific agents."""
+    agent: str = Field(description="Name of the agent to use")
+    query: str = Field(description="Query/task for the agent")
+    gap: str = Field(description="The knowledge gap this task addresses")
+    entity_website: Optional[str] = Field(description="Optional entity or website context", default=None)
+
+
+class AgentSelectionPlan(BaseModel):
+    """Plan containing multiple agent tasks to address knowledge gaps."""
+    tasks: List[AgentTask] = Field(description="List of tasks for different agents", default_factory=list)
+    reasoning: str = Field(description="Reasoning for the agent selection", default="")
+
+
+class RoutingInput(BaseModel):
+    """Input schema for routing agent runtime template."""
+    query: str = Field(description="Original user query")
+    gap: str = Field(description="Knowledge gap to address")
+    history: str = Field(description="History of actions, findings and thoughts")
+
+
+# Profile instance for routing agent
+routing_profile = Profile(
+    instructions="""You are a task routing agent. Your role is to analyze knowledge gaps and route appropriate tasks to specialized agents.
+
+Available agents: data_loader_agent, data_analysis_agent, preprocessing_agent, model_training_agent, evaluation_agent, visualization_agent, code_generation_agent, research_agent
+
+Agent capabilities:
+- data_loader_agent: Load and inspect datasets, understand data structure
+- data_analysis_agent: Perform exploratory data analysis, statistical analysis
+- preprocessing_agent: Clean data, handle missing values, feature engineering
+- model_training_agent: Train machine learning models, hyperparameter tuning
+- evaluation_agent: Evaluate model performance, generate metrics
+- visualization_agent: Create charts, plots, and visualizations
+- code_generation_agent: Generate code snippets and complete implementations
+- research_agent: Research methodologies, best practices, domain knowledge
+
+Your task:
+1. Analyze the knowledge gap that needs to be addressed
+2. Select the most appropriate agent(s) to handle the gap
+3. Create specific, actionable tasks for each selected agent
+4. Ensure tasks are clear and focused
+
+Create a routing plan with appropriate agents and tasks to address the knowledge gap.""",
+    runtime_template="""ORIGINAL QUERY:
+[[QUERY]]
+
+KNOWLEDGE GAP TO ADDRESS:
+[[GAP]]
+
+
+HISTORY OF ACTIONS, FINDINGS AND THOUGHTS:
+[[HISTORY]]""",
+    output_schema=AgentSelectionPlan,
+    input_schema=RoutingInput,
+    tools=None,
+    model=None
+)

agentz/profiles/manager/writer.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import Optional
+from pydantic import BaseModel, Field
+
+from agentz.profiles.base import Profile
+
+
+class WriterInput(BaseModel):
+    """Input schema for writer agent runtime template."""
+    user_prompt: str = Field(description="Original user query/prompt")
+    data_path: str = Field(description="Path to the dataset")
+    findings: str = Field(description="Research findings to synthesize")
+    guidelines_block: Optional[str] = Field(default="", description="Optional formatting guidelines")
+
+
+# Profile instance for writer agent
+writer_profile = Profile(
+    instructions="""You are a technical writing agent specialized in creating comprehensive data science reports.
+
+Your responsibilities:
+1. Synthesize findings from multiple research iterations
+2. Create clear, well-structured reports with proper formatting
+3. Include executive summaries when appropriate
+4. Present technical information in an accessible manner
+5. Follow specific formatting guidelines when provided
+6. Ensure all key insights and recommendations are highlighted
+
+Report Structure Guidelines:
+- Start with a clear summary of the task/objective
+- Present methodology and approach
+- Include key findings and insights
+- Provide actionable recommendations
+- Use proper markdown formatting when appropriate
+- Include code examples when relevant
+- Ensure technical accuracy while maintaining readability
+
+Focus on creating professional, comprehensive reports that effectively communicate the research findings and their practical implications.""",
+    runtime_template="""Provide a response based on the query and findings below with as much detail as possible[[GUIDELINES_BLOCK]]
+
+QUERY: [[USER_PROMPT]]
+
+DATASET: [[DATA_PATH]]
+
+FINDINGS:
+[[FINDINGS]]""",
+    output_schema=None,
+    input_schema=WriterInput,
+    tools=None,
+    model=None
+)

agentz/profiles/mcp/browser.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from agentz.profiles.base import Profile
+
+
+class InstructionsInput(BaseModel):
+    """Input schema for instructions-based runtime template."""
+    instructions: str = Field(description="The instructions to follow")
+
+
+# Profile instance for browser agent
+browser_profile = Profile(
+    instructions="You are a browser agent. Your task is to interact with the browser MCP server following the instructions provided.",
+    runtime_template="[[INSTRUCTIONS]]",
+    output_schema=None,
+    input_schema=InstructionsInput,
+    tools=None,
+    model=None
+)