agentic-ai-kit 0.1.1__py3-none-any.whl

agentic_ai/__init__.py

@@ -0,0 +1,24 @@
+"""
+agentic_ai — A progressive framework for building agentic AI systems with Google Gemini.
+"""
+
+from agentic_ai.agents.base import BaseAgent
+from agentic_ai.agents.tool_agent import ToolAgent
+from agentic_ai.agents.json_agent import JsonAgent
+from agentic_ai.agents.reasoning_agent import ReasoningAgent
+from agentic_ai.memory.short_term import ShortTermMemory
+from agentic_ai.memory.long_term import LongTermMemory
+from agentic_ai.memory.shared import SharedMemory
+from agentic_ai.agents.auto_model_agent import AutoModelAgent
+
+__version__ = "0.1.0"
+__all__ = [
+    "BaseAgent",
+    "ToolAgent",
+    "JsonAgent",
+    "ReasoningAgent",
+    "ShortTermMemory",
+    "LongTermMemory",
+    "SharedMemory",
+    "AutoModelAgent",
+]

agentic_ai/agents/__init__.py

@@ -0,0 +1,17 @@
+from agentic_ai.agents.base import BaseAgent
+from agentic_ai.agents.tool_agent import ToolAgent
+from agentic_ai.agents.json_agent import JsonAgent
+from agentic_ai.agents.reasoning_agent import ReasoningAgent
+from agentic_ai.agents.analyst_agent import AnalystAgent
+from agentic_ai.agents.mle_agent import MLEAgent
+from agentic_ai.agents.auto_model_agent import AutoModelAgent
+
+__all__ = [
+    "BaseAgent",
+    "ToolAgent",
+    "JsonAgent",
+    "ReasoningAgent",
+    "AnalystAgent",
+    "MLEAgent",
+    "AutoModelAgent",
+]

agentic_ai/agents/analyst_agent.py

@@ -0,0 +1,239 @@
+"""
+AnalystAgent: dataframe-aware analytics specialist agent.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from agentic_ai.agents.base import BaseAgent
+
+
+_ANALYST_PROMPT = """
+You are an elite Decision Scientist.
+
+You help users analyze pandas DataFrames and business datasets.
+
+You are expected to reason using:
+- dataframe schema
+- row counts
+- missing values
+- numeric summaries
+- categorical distributions
+- group-level metrics
+- data quality risks
+- business interpretation
+
+Always separate:
+1. what the data says
+2. what it might mean
+3. what should be checked next
+
+Preferred response structure:
+
+BUSINESS QUESTION
+DATA READ
+KEY OBSERVATIONS
+DATA QUALITY RISKS
+RECOMMENDED ANALYSIS
+DECISION SUMMARY
+
+Do not invent numbers.
+If dataframe context is provided, use it explicitly.
+""".strip()
+
+
+class AnalystAgent(BaseAgent):
+    """Analytics-focused specialist agent with dataframe tools."""
+
+    def __init__(
+        self,
+        name: str = "Analyst",
+        domain_context: str | None = None,
+        model: str = "gemini-2.5-flash-lite",
+        api_key: str | None = None,
+        memory_window: int = 3,
+        max_turns: int | None = None,
+        thinking_budget: int = 0,
+    ):
+        prompt = _ANALYST_PROMPT
+
+        if domain_context:
+            prompt += f"\n\nDOMAIN CONTEXT:\n{domain_context.strip()}"
+
+        super().__init__(
+            name=name,
+            sys_prompt=prompt,
+            model=model,
+            api_key=api_key,
+            memory_window=memory_window,
+            max_turns=max_turns,
+            thinking_budget=thinking_budget,
+        )
+
+    # ------------------------------------------------------------------
+    # DataFrame tools
+    # ------------------------------------------------------------------
+
+    def profile_dataframe(self, df: pd.DataFrame) -> dict[str, Any]:
+        """Return a consistent dataframe profile."""
+
+        self._validate_dataframe(df)
+
+        return {
+            "rows": int(df.shape[0]),
+            "columns": int(df.shape[1]),
+            "column_names": list(df.columns),
+            "dtypes": {col: str(dtype) for col, dtype in df.dtypes.items()},
+            "missing_values": df.isna().sum().to_dict(),
+            "missing_percentage": (
+                df.isna().mean().mul(100).round(2).to_dict()
+            ),
+            "duplicate_rows": int(df.duplicated().sum()),
+            "numeric_columns": list(df.select_dtypes(include="number").columns),
+            "categorical_columns": list(
+                df.select_dtypes(include=["object", "category", "bool"]).columns
+            ),
+            "datetime_columns": list(
+                df.select_dtypes(include=["datetime", "datetimetz"]).columns
+            ),
+        }
+
+    def numeric_summary(self, df: pd.DataFrame) -> dict[str, Any]:
+        """Return numeric column summary."""
+
+        self._validate_dataframe(df)
+
+        numeric_df = df.select_dtypes(include="number")
+
+        if numeric_df.empty:
+            return {"message": "No numeric columns found."}
+
+        return numeric_df.describe().round(4).to_dict()
+
+    def categorical_summary(
+        self,
+        df: pd.DataFrame,
+        top_n: int = 10,
+    ) -> dict[str, Any]:
+        """Return top category counts for categorical columns."""
+
+        self._validate_dataframe(df)
+
+        categorical_df = df.select_dtypes(include=["object", "category", "bool"])
+
+        if categorical_df.empty:
+            return {"message": "No categorical columns found."}
+
+        summary = {}
+
+        for col in categorical_df.columns:
+            summary[col] = (
+                categorical_df[col]
+                .value_counts(dropna=False)
+                .head(top_n)
+                .to_dict()
+            )
+
+        return summary
+
+    def groupby_summary(
+        self,
+        df: pd.DataFrame,
+        group_col: str,
+        metric_col: str,
+        agg: str = "mean",
+    ) -> dict[str, Any]:
+        """Return grouped metric summary."""
+
+        self._validate_dataframe(df)
+        self._validate_columns(df, [group_col, metric_col])
+
+        allowed_aggs = {"mean", "sum", "count", "median", "min", "max"}
+
+        if agg not in allowed_aggs:
+            raise ValueError(f"agg must be one of {sorted(allowed_aggs)}")
+
+        result = (
+            df.groupby(group_col, dropna=False)[metric_col]
+            .agg(agg)
+            .reset_index()
+            .sort_values(metric_col, ascending=False)
+        )
+
+        return result.to_dict(orient="records")
+
+    def correlation_summary(self, df: pd.DataFrame) -> dict[str, Any]:
+        """Return numeric correlation matrix."""
+
+        self._validate_dataframe(df)
+
+        numeric_df = df.select_dtypes(include="number")
+
+        if numeric_df.shape[1] < 2:
+            return {"message": "At least two numeric columns are needed."}
+
+        return numeric_df.corr().round(4).to_dict()
+
+    def dataframe_context(
+        self,
+        df: pd.DataFrame,
+        include_numeric: bool = True,
+        include_categorical: bool = True,
+    ) -> str:
+        """Create dataframe context for the LLM."""
+
+        context = {
+            "profile": self.profile_dataframe(df),
+        }
+
+        if include_numeric:
+            context["numeric_summary"] = self.numeric_summary(df)
+
+        if include_categorical:
+            context["categorical_summary"] = self.categorical_summary(df)
+
+        return str(context)
+
+    def analyze_dataframe(
+        self,
+        df: pd.DataFrame,
+        question: str,
+        stream: bool = True,
+    ) -> str:
+        """Analyze a dataframe using generated dataframe context."""
+
+        context = self.dataframe_context(df)
+
+        prompt = f"""
+Analyze the dataframe for the following question.
+
+QUESTION:
+{question}
+
+DATAFRAME CONTEXT:
+{context}
+""".strip()
+
+        return self.think(prompt, stream=stream)
+
+    # ------------------------------------------------------------------
+    # Validation helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _validate_dataframe(df: pd.DataFrame) -> None:
+        if not isinstance(df, pd.DataFrame):
+            raise TypeError("Expected a pandas DataFrame.")
+
+        if df.empty:
+            raise ValueError("DataFrame is empty.")
+
+    @staticmethod
+    def _validate_columns(df: pd.DataFrame, columns: list[str]) -> None:
+        missing = [col for col in columns if col not in df.columns]
+
+        if missing:
+            raise ValueError(f"Missing columns: {missing}")

agentic_ai/agents/auto_model_agent.py

@@ -0,0 +1,156 @@
+"""
+AutoModelAgent: end-to-end dataframe-to-model agent.
+
+The user gives:
+- dataframe
+- target column
+- business objective
+
+The agent:
+- profiles the data
+- designs modeling policy
+- trains models using MLEAgent
+- returns results and interpretation
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from agentic_ai.agents.mle_agent import MLEAgent
+
+
+class AutoModelAgent(MLEAgent):
+    """End-to-end modeling agent built on top of MLEAgent."""
+
+    def run(
+        self,
+        df: pd.DataFrame,
+        target_col: str,
+        objective: str,
+        drop_columns: list[str] | None = None,
+        test_size: float = 0.2,
+        random_state: int = 42,
+        stream: bool = True,
+        interpret: bool = True,
+    ) -> dict[str, Any]:
+        """Look at data, design policy, train model, and explain results."""
+
+        self._validate_dataframe(df)
+        self._validate_columns(df, [target_col])
+
+        profile = self.profile_dataframe(df)
+        target = self.target_summary(df, target_col)
+        features = self.feature_summary(df, target_col)
+        leakage = self.leakage_scan(df, target_col)
+        
+
+        if not interpret:
+            model_result = self.train_model(
+            df=df,
+            target_col=target_col,
+            test_size=test_size,
+            random_state=random_state,
+            drop_columns=drop_columns,
+        )
+
+            return {
+                "objective": objective,
+                "target_column": target_col,
+                "data_profile": profile,
+                "target_summary": target,
+                "feature_summary": features,
+                "leakage_scan": leakage,
+                "modeling_policy": None,
+                "interpretation": None,
+                "model_result": model_result,
+                "best_model": model_result["best_model"],
+                "best_score": model_result["best_score"],
+                "best_pipeline": model_result["best_pipeline"],
+            }
+
+        policy_prompt = f"""
+You are about to create a machine learning model.
+
+BUSINESS OBJECTIVE:
+{objective}
+
+TARGET COLUMN:
+{target_col}
+
+DATA PROFILE:
+{profile}
+
+TARGET SUMMARY:
+{target}
+
+FEATURE SUMMARY:
+{features}
+
+LEAKAGE SCAN:
+{leakage}
+
+Design a concise modeling policy before training.
+
+Include:
+1. problem type
+2. usable features
+3. columns to drop, if any
+4. leakage risks
+5. train/test approach
+6. model candidates
+7. evaluation metric
+8. expected limitations
+
+Return a practical modeling policy.
+""".strip()
+
+        modeling_policy = self.think(policy_prompt, stream=stream)
+
+        model_result = self.train_model(
+            df=df,
+            target_col=target_col,
+            test_size=test_size,
+            random_state=random_state,
+            drop_columns=drop_columns,
+        )
+
+        result_prompt = f"""
+A model has now been trained.
+
+BUSINESS OBJECTIVE:
+{objective}
+
+MODELING POLICY:
+{modeling_policy}
+
+MODEL RESULT:
+{self._safe_model_result_for_llm(model_result)}
+
+Explain:
+1. what model was created
+2. which model performed best
+3. what the metrics mean
+4. whether the result is usable
+5. what should be improved next
+6. how this could be deployed
+""".strip()
+
+        interpretation = self.think(result_prompt, stream=stream)
+
+        return {
+            "objective": objective,
+            "target_column": target_col,
+            "data_profile": profile,
+            "target_summary": target,
+            "feature_summary": features,
+            "leakage_scan": leakage,
+            "modeling_policy": modeling_policy,
+            "model_result": model_result,
+            "interpretation": interpretation,
+            "best_model": model_result["best_model"],
+            "best_score": model_result["best_score"],
+            "best_pipeline": model_result["best_pipeline"],
+        }

agentic_ai/agents/base.py

@@ -0,0 +1,280 @@
+"""
+BaseAgent: the foundation for all agents in agentic_ai.
+
+Every agent has:
+- A name and system prompt that define its persona
+- Short-term memory for recent context
+- Optional max-turn retention at the interface level
+- LLM-based fact extraction for lightweight user memory
+- A `think(input_text)` method that streams a Gemini response
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+from google import genai
+from google.genai import types
+
+
+class BaseAgent:
+    """Core agent backed by a Gemini model."""
+
+    def __init__(
+        self,
+        name: str,
+        sys_prompt: str,
+        model: str = "gemini-2.5-flash-lite",
+        api_key: str | None = None,
+        memory_window: int = 3,
+        max_turns: int | None = None,
+        max_facts: int = 50,
+        extract_memory: bool = True,
+        thinking_budget: int = 0,
+    ):
+        self.name = name
+        self.sys_prompt = sys_prompt
+        self.model = model
+        self.memory_window = memory_window
+        self.max_turns = max_turns
+        self.max_facts = max_facts
+        self.extract_memory = extract_memory
+        self.thinking_budget = thinking_budget
+
+        self.memory: list[tuple[str, str]] = []
+        self.facts_store: list[dict[str, object]] = []
+
+        key = api_key or os.environ.get("GEMINI_API_KEY")
+        if not key:
+            raise ValueError(
+                "No Gemini API key found. Pass api_key= or set GEMINI_API_KEY."
+            )
+
+        self.client = genai.Client(api_key=key)
+
+    # ------------------------------------------------------------------
+    # Memory helpers
+    # ------------------------------------------------------------------
+
+    def extract_facts(self, text: str) -> None:
+        """Extract durable user facts from input using Gemini."""
+
+        if not self.extract_memory:
+            return
+
+        extraction_prompt = f"""
+You are a memory extraction system.
+
+Extract durable facts from the user's message.
+
+A durable fact is something likely to remain useful in future conversations.
+
+Examples of durable facts:
+- User works as a data scientist.
+- User prefers Python.
+- User is building an agentic AI framework.
+- User is learning PyTorch.
+- User works on retail analytics.
+
+Do not extract:
+- Temporary requests
+- Greetings
+- One-off questions
+- Generic statements
+- Facts about the assistant
+- Very sensitive personal information
+
+Return ONLY valid JSON in this exact format:
+
+[
+  {{
+    "fact": "User is building an agentic AI framework.",
+    "confidence": 0.95
+  }}
+]
+
+If there are no durable facts, return:
+
+[]
+
+User message:
+{text}
+""".strip()
+
+        try:
+            response = self.client.models.generate_content(
+                model=self.model,
+                contents=extraction_prompt,
+                config=types.GenerateContentConfig(
+                    temperature=0,
+                    thinking_config=types.ThinkingConfig(thinking_budget=0),
+                ),
+            )
+
+            raw_output = (response.text or "").strip()
+            extracted = json.loads(raw_output)
+
+            if not isinstance(extracted, list):
+                return
+
+            for item in extracted:
+                if not isinstance(item, dict):
+                    continue
+
+                fact = str(item.get("fact", "")).strip()
+                confidence = item.get("confidence", 0.0)
+
+                try:
+                    confidence = float(confidence)
+                except (TypeError, ValueError):
+                    confidence = 0.0
+
+                if not fact:
+                    continue
+
+                if confidence < 0.6:
+                    continue
+
+                if self._fact_exists(fact):
+                    continue
+
+                self.facts_store.append(
+                    {
+                        "fact": fact,
+                        "confidence": confidence,
+                        "source": text,
+                    }
+                )
+
+            self.trim_facts()
+
+        except Exception:
+            # Memory extraction should never break the main agent response.
+            return
+
+    def _fact_exists(self, new_fact: str) -> bool:
+        """Check whether a fact already exists in memory."""
+
+        normalized_new = new_fact.lower().strip().rstrip(".")
+
+        for item in self.facts_store:
+            existing = str(item.get("fact", "")).lower().strip().rstrip(".")
+            if existing == normalized_new:
+                return True
+
+        return False
+
+    def build_context(self, input_text: str) -> str:
+        """Assemble facts, recent history, and the new message."""
+
+        recent_turns = self.memory[-self.memory_window :]
+
+        history = "\n".join(
+            f"user: {user_input}\nassistant: {agent_output}"
+            for user_input, agent_output in recent_turns
+        )
+
+        if self.facts_store:
+            facts_text = "\n".join(
+                f"- {item['fact']}" for item in self.facts_store
+            )
+        else:
+            facts_text = "(none)"
+
+        return (
+            f"FACTS:\n{facts_text}\n\n"
+            f"HISTORY:\n{history}\n\n"
+            f"NEW MESSAGE:\n{input_text}"
+        )
+
+    def trim_memory(self) -> None:
+        """Limit retained conversation turns at the interface level."""
+
+        if self.max_turns is not None:
+            if self.max_turns < 0:
+                raise ValueError("max_turns must be None or a non-negative integer.")
+
+            self.memory = self.memory[-self.max_turns :]
+
+    def trim_facts(self) -> None:
+        """Limit number of stored facts."""
+
+        if self.max_facts < 0:
+            raise ValueError("max_facts must be a non-negative integer.")
+
+        self.facts_store = self.facts_store[-self.max_facts :]
+
+    def clear_memory(self) -> None:
+        """Wipe short-term memory and facts store."""
+
+        self.memory.clear()
+        self.facts_store.clear()
+
+    # ------------------------------------------------------------------
+    # Core generation
+    # ------------------------------------------------------------------
+
+    def think(
+        self,
+        input_text: str,
+        use_memory: bool = True,
+        stream: bool = True,
+    ) -> str:
+        """Send input to Gemini and return the full response string."""
+
+        self.extract_facts(input_text)
+        prompt = self.build_context(input_text) if use_memory else input_text
+
+        contents = [
+            types.Content(
+                role="user",
+                parts=[types.Part.from_text(text=prompt)],
+            )
+        ]
+
+        config = types.GenerateContentConfig(
+            thinking_config=types.ThinkingConfig(
+                thinking_budget=self.thinking_budget
+            ),
+            system_instruction=[
+                types.Part.from_text(text=self.sys_prompt)
+            ],
+        )
+
+        response_text = ""
+
+        if stream:
+            for chunk in self.client.models.generate_content_stream(
+                model=self.model,
+                contents=contents,
+                config=config,
+            ):
+                if chunk.text:
+                    print(chunk.text, end="", flush=True)
+                    response_text += chunk.text
+
+            print()
+
+        else:
+            response = self.client.models.generate_content(
+                model=self.model,
+                contents=contents,
+                config=config,
+            )
+            response_text = response.text or ""
+
+        self.memory.append((input_text, response_text))
+        self.trim_memory()
+
+        return response_text
+
+    def __repr__(self) -> str:
+        return (
+            f"<{self.__class__.__name__} "
+            f"name={self.name!r} "
+            f"model={self.model!r} "
+            f"memory_window={self.memory_window!r} "
+            f"max_turns={self.max_turns!r} "
+            f"max_facts={self.max_facts!r}>"
+        )