agentic-ai-kit 0.1.1__tar.gz

agentic_ai_kit-0.1.1/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: agentic-ai-kit
+Version: 0.1.1
+Summary: A progressive framework for building agentic AI systems with Google Gemini.
+Author-email: Shashank Singh <shashank14581@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/shashank14581/agentic-ai-kit
+Project-URL: Repository, https://github.com/shashank14581/agentic-ai-kit
+Keywords: agentic-ai,llm,gemini,agents,rag,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: scikit-learn>=1.3.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# agentic-ai
+
+A progressive Python framework for building **agentic AI systems with Google Gemini**.
+
+`agentic-ai` turns common agentic AI patterns into reusable Python components: talking agents, memory, tool use, structured JSON output, reasoning workflows, supervisor delegation, parallel execution, debate, RAG, MCP tool servers, and applied data science agents.
+
+This project started with a simple question: what happens if two agents talk and one of them is a dog that can bark? From that playful starting point, the patterns evolved into a reusable framework for building composable agentic systems.
+
+---
+
+## Installation
+
+```bash
+pip install agentic-ai
+```
+
+For the latest GitHub version:
+
+```bash
+pip install --upgrade --force-reinstall git+https://github.com/shashank14581/agentic-ai-kit.git
+```
+
+Set your Gemini API key:
+
+```bash
+export GEMINI_API_KEY="your-key-here"
+```
+
+In Google Colab, store `GEMINI_API_KEY` in Colab Secrets and load it into `os.environ`.
+
+---
+
+## Quick start
+
+```python
+from agentic_ai.agents import BaseAgent
+
+agent = BaseAgent(
+    name="Alfred",
+    sys_prompt="You are a witty British butler.",
+    model="gemini-1.5-flash",
+    extract_memory=False,
+)
+
+agent.think("Good morning! What should I do today?", stream=False)
+```
+
+---
+
+## What it supports
+
+| Capability | Component |
+|---|---|
+| Simple conversational agents | `BaseAgent` |
+| Persona and short-term memory | `BaseAgent`, `ShortTermMemory` |
+| LLM-extracted durable facts | `BaseAgent.facts_store` |
+| SQLite-backed long-term memory | `LongTermMemory` |
+| Shared state across agents | `SharedMemory` |
+| Gemini function-calling tools | `ToolAgent`, `ToolRegistry` |
+| Structured JSON output | `JsonAgent` |
+| Reasoning / planning workflows | `ReasoningAgent` |
+| Round-robin conversations | `run_conversation` |
+| Supervisor delegation | `run_supervisor` |
+| Parallel fan-out execution | `run_parallel` |
+| Debate and judge pattern | `run_debate` |
+| Chunking, embeddings, vector search | `chunk_text`, `embed_texts`, `VectorStore` |
+| Retrieval-augmented generation | `RAGAgent` |
+| MCP-style tool server and client | `MCPServer`, `MCPClient` |
+| DataFrame analysis | `AnalystAgent` |
+| Machine learning model training | `MLEAgent` |
+| End-to-end auto modeling workflow | `AutoModelAgent` |
+
+---
+
+## Package layout
+
+```text
+agentic_ai/
+├── agents/
+│   ├── base.py              # BaseAgent — memory, streaming, durable facts
+│   ├── tool_agent.py        # ToolAgent — Gemini function-calling
+│   ├── json_agent.py        # JsonAgent — structured JSON responses
+│   ├── reasoning_agent.py   # ReasoningAgent — planning-style workflows
+│   ├── analyst_agent.py     # AnalystAgent — dataframe profiling and analysis
+│   ├── mle_agent.py         # MLEAgent — train and compare sklearn models
+│   └── auto_model_agent.py  # AutoModelAgent — profile data, train model, summarize results
+├── memory/
+│   ├── short_term.py        # Sliding-window turn memory
+│   ├── long_term.py         # SQLite-backed persistent memory
+│   └── shared.py            # Thread-safe shared state across agents
+├── tools/
+│   ├── registry.py          # @tool decorator and ToolRegistry
+│   └── builtins.py          # get_weather, add_numbers, search_wikipedia
+├── patterns/
+│   ├── orchestrator.py      # run_conversation, run_supervisor
+│   ├── parallel.py          # run_parallel fan-out execution
+│   └── debate.py            # run_debate with debaters and judge
+├── rag/
+│   ├── chunker.py           # chunk_text
+│   ├── embedder.py          # embed_texts using Gemini embeddings
+│   ├── vector_store.py      # In-memory cosine-similarity vector store
+│   └── rag_agent.py         # RAGAgent ingest → retrieve → generate
+└── mcp/
+    ├── server.py            # MCPServer — HTTP tool server
+    └── client.py            # MCPClient — calls a running MCPServer
+```
+
+---
+
+## Examples
+
+All examples live in `agentic_ai/examples/` and can be run directly:
+
+| File | Concept |
+|---|---|
+| `01_talking_agents.py` | Two agents in a round-robin conversation |
+| `02_personality_and_memory.py` | Agent with persona and short-term memory |
+| `03_tool_agent_weather.py` | Real weather tool through Gemini function-calling |
+| `04_json_agent.py` | Structured JSON output |
+| `05_reasoning_agent.py` | Planning-style reasoning workflow |
+| `06_supervisor.py` | Supervisor delegates to specialist workers |
+| `07_parallel_agents.py` | Fan-out: same task, multiple agents in parallel |
+| `08_debate.py` | Two agents debate; a judge picks a winner |
+| `09_long_term_memory.py` | SQLite-backed memory across sessions |
+| `10_rag_agent.py` | Document ingestion and retrieval-augmented generation |
+| `11_mcp_demo.py` | MCP tool server and agent integration |
+
+---
+
+## Data science agents
+
+The kit also includes applied analytics and modeling agents.
+
+```python
+from agentic_ai.agents import AutoModelAgent
+
+agent = AutoModelAgent(
+    project_context="Marketing audience selection and customer conversion modeling.",
+    model="gemini-1.5-flash",
+)
+
+result = agent.run(
+    df=df,
+    target_col="converted",
+    objective="Predict customer conversion.",
+    interpret=False,
+)
+
+print(result["best_model"])
+print(result["best_score"])
+```
+
+Use `interpret=False` when you want local sklearn training without an additional Gemini interpretation call.
+
+---
+
+## Design philosophy
+
+The framework separates **reasoning** from **execution**.
+
+- Agents can reason, plan, route, critique, and summarize.
+- Utilities can execute deterministic work such as memory lookup, chunking, vector search, dataframe profiling, and model training.
+- Pattern functions provide lightweight orchestration.
+- Specialist agents provide higher-level user-facing workflows.
+
+This makes the library useful for both learning agentic AI patterns and building practical data science or automation workflows.
+
+---
+
+## License
+
+MIT

agentic_ai_kit-0.1.1/README.md

@@ -0,0 +1,172 @@
+# agentic-ai
+
+A progressive Python framework for building **agentic AI systems with Google Gemini**.
+
+`agentic-ai` turns common agentic AI patterns into reusable Python components: talking agents, memory, tool use, structured JSON output, reasoning workflows, supervisor delegation, parallel execution, debate, RAG, MCP tool servers, and applied data science agents.
+
+This project started with a simple question: what happens if two agents talk and one of them is a dog that can bark? From that playful starting point, the patterns evolved into a reusable framework for building composable agentic systems.
+
+---
+
+## Installation
+
+```bash
+pip install agentic-ai
+```
+
+For the latest GitHub version:
+
+```bash
+pip install --upgrade --force-reinstall git+https://github.com/shashank14581/agentic-ai-kit.git
+```
+
+Set your Gemini API key:
+
+```bash
+export GEMINI_API_KEY="your-key-here"
+```
+
+In Google Colab, store `GEMINI_API_KEY` in Colab Secrets and load it into `os.environ`.
+
+---
+
+## Quick start
+
+```python
+from agentic_ai.agents import BaseAgent
+
+agent = BaseAgent(
+    name="Alfred",
+    sys_prompt="You are a witty British butler.",
+    model="gemini-1.5-flash",
+    extract_memory=False,
+)
+
+agent.think("Good morning! What should I do today?", stream=False)
+```
+
+---
+
+## What it supports
+
+| Capability | Component |
+|---|---|
+| Simple conversational agents | `BaseAgent` |
+| Persona and short-term memory | `BaseAgent`, `ShortTermMemory` |
+| LLM-extracted durable facts | `BaseAgent.facts_store` |
+| SQLite-backed long-term memory | `LongTermMemory` |
+| Shared state across agents | `SharedMemory` |
+| Gemini function-calling tools | `ToolAgent`, `ToolRegistry` |
+| Structured JSON output | `JsonAgent` |
+| Reasoning / planning workflows | `ReasoningAgent` |
+| Round-robin conversations | `run_conversation` |
+| Supervisor delegation | `run_supervisor` |
+| Parallel fan-out execution | `run_parallel` |
+| Debate and judge pattern | `run_debate` |
+| Chunking, embeddings, vector search | `chunk_text`, `embed_texts`, `VectorStore` |
+| Retrieval-augmented generation | `RAGAgent` |
+| MCP-style tool server and client | `MCPServer`, `MCPClient` |
+| DataFrame analysis | `AnalystAgent` |
+| Machine learning model training | `MLEAgent` |
+| End-to-end auto modeling workflow | `AutoModelAgent` |
+
+---
+
+## Package layout
+
+```text
+agentic_ai/
+├── agents/
+│   ├── base.py              # BaseAgent — memory, streaming, durable facts
+│   ├── tool_agent.py        # ToolAgent — Gemini function-calling
+│   ├── json_agent.py        # JsonAgent — structured JSON responses
+│   ├── reasoning_agent.py   # ReasoningAgent — planning-style workflows
+│   ├── analyst_agent.py     # AnalystAgent — dataframe profiling and analysis
+│   ├── mle_agent.py         # MLEAgent — train and compare sklearn models
+│   └── auto_model_agent.py  # AutoModelAgent — profile data, train model, summarize results
+├── memory/
+│   ├── short_term.py        # Sliding-window turn memory
+│   ├── long_term.py         # SQLite-backed persistent memory
+│   └── shared.py            # Thread-safe shared state across agents
+├── tools/
+│   ├── registry.py          # @tool decorator and ToolRegistry
+│   └── builtins.py          # get_weather, add_numbers, search_wikipedia
+├── patterns/
+│   ├── orchestrator.py      # run_conversation, run_supervisor
+│   ├── parallel.py          # run_parallel fan-out execution
+│   └── debate.py            # run_debate with debaters and judge
+├── rag/
+│   ├── chunker.py           # chunk_text
+│   ├── embedder.py          # embed_texts using Gemini embeddings
+│   ├── vector_store.py      # In-memory cosine-similarity vector store
+│   └── rag_agent.py         # RAGAgent ingest → retrieve → generate
+└── mcp/
+    ├── server.py            # MCPServer — HTTP tool server
+    └── client.py            # MCPClient — calls a running MCPServer
+```
+
+---
+
+## Examples
+
+All examples live in `agentic_ai/examples/` and can be run directly:
+
+| File | Concept |
+|---|---|
+| `01_talking_agents.py` | Two agents in a round-robin conversation |
+| `02_personality_and_memory.py` | Agent with persona and short-term memory |
+| `03_tool_agent_weather.py` | Real weather tool through Gemini function-calling |
+| `04_json_agent.py` | Structured JSON output |
+| `05_reasoning_agent.py` | Planning-style reasoning workflow |
+| `06_supervisor.py` | Supervisor delegates to specialist workers |
+| `07_parallel_agents.py` | Fan-out: same task, multiple agents in parallel |
+| `08_debate.py` | Two agents debate; a judge picks a winner |
+| `09_long_term_memory.py` | SQLite-backed memory across sessions |
+| `10_rag_agent.py` | Document ingestion and retrieval-augmented generation |
+| `11_mcp_demo.py` | MCP tool server and agent integration |
+
+---
+
+## Data science agents
+
+The kit also includes applied analytics and modeling agents.
+
+```python
+from agentic_ai.agents import AutoModelAgent
+
+agent = AutoModelAgent(
+    project_context="Marketing audience selection and customer conversion modeling.",
+    model="gemini-1.5-flash",
+)
+
+result = agent.run(
+    df=df,
+    target_col="converted",
+    objective="Predict customer conversion.",
+    interpret=False,
+)
+
+print(result["best_model"])
+print(result["best_score"])
+```
+
+Use `interpret=False` when you want local sklearn training without an additional Gemini interpretation call.
+
+---
+
+## Design philosophy
+
+The framework separates **reasoning** from **execution**.
+
+- Agents can reason, plan, route, critique, and summarize.
+- Utilities can execute deterministic work such as memory lookup, chunking, vector search, dataframe profiling, and model training.
+- Pattern functions provide lightweight orchestration.
+- Specialist agents provide higher-level user-facing workflows.
+
+This makes the library useful for both learning agentic AI patterns and building practical data science or automation workflows.
+
+---
+
+## License
+
+MIT

agentic_ai_kit-0.1.1/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_kit-0.1.1/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_kit-0.1.1/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}")