Add toolsforgitnotionslack folder as a folder for my code which can be run nativelly and as a fastapi endpoint

toolsforgitnotionslack/agent/cache.py

@@ -0,0 +1,21 @@
+import time
+from typing import Optional
+
+class Cache:
+    def __init__(self, ttl_seconds: int = 300):
+        self._store: dict[str, tuple[str, float]] = {}
+        self._ttl = ttl_seconds
+
+    def get(self, key: str) -> Optional[str]:
+        entry = self._store.get(key)
+        if entry and (time.monotonic() - entry[1]) < self._ttl:
+            return entry[0]
+        if entry:
+            del self._store[key]
+        return None
+
+    def set(self, key: str, value: str) -> None:
+        self._store[key] = (value, time.monotonic())
+
+    def clear(self) -> None:
+        self._store.clear()

toolsforgitnotionslack/agent/planner.py

@@ -0,0 +1,36 @@
+def build_system_prompt(default_repo: str = "") -> str:
+    repo_hint = f"\n  Default GitHub repo: {default_repo}" if default_repo else ""
+    return f"""You are an enterprise knowledge assistant with live access to GitHub, Slack, and Notion.{repo_hint}
+
+## Retrieval discipline
+
+### GitHub
+1. DISCOVER first: use github_list_repos or github_list_files before reading anything.
+2. SEARCH before reading: use github_search_code or github_list_markdown_files to locate docs.
+3. READ only documentation files (.md, README, docs/, wiki/, adr/).
+   Never read .py .ts .json .yaml .lock unless user explicitly asks for code.
+4. Summarise large files — do not quote them verbatim.
+5. Cite every answer as: [owner/repo · path/file.md]
+
+### Slack
+1. Use slack_list_channels to confirm channel IDs before history calls.
+2. Use slack_search for topic lookups. Use slack_channel_history for recent messages.
+3. Use slack_get_thread when a message has replies worth reconstructing.
+4. Cite as: [#channel | YYYY-MM-DD]
+
+### Notion
+1. Use notion_search first. Only call notion_read_page after you have a page_id.
+2. Use notion_list_databases → notion_query_database for structured data.
+3. Cite as: [Notion · Page Title]
+
+## Cross-source reasoning
+- Run parallel tool calls when questions span multiple sources.
+- Reuse cached results — do not re-call with identical arguments.
+- Summarise before deep-diving.
+- If info is not found after a reasonable search, say so. Never fabricate paths, names, or channels.
+
+## Response format
+- Lead with a direct answer.
+- Cite every factual claim from a tool result.
+- Offer follow-up suggestions when the question is broad.
+"""

toolsforgitnotionslack/chatbot.py

@@ -0,0 +1,204 @@
+"""
+FastAPI endpoint for the Enterprise Knowledge Assistant.
+
+pip install fastapi uvicorn
+
+Run:
+    uvicorn app:app --reload --port 8000
+
+Endpoints:
+    POST /chat        — single-turn or multi-turn conversation
+    DELETE /chat      — clear session history and cache
+    GET  /health      — service status
+"""
+
+from dotenv import load_dotenv
+load_dotenv()
+
+import asyncio, json, os, time, uuid
+from contextlib import asynccontextmanager
+from typing import Optional
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+
+from openai import AsyncOpenAI
+from tools.github_tools import GITHUB_TOOLS, GITHUB_TOOL_FNS
+from tools.slack_tools  import SLACK_TOOLS,  SLACK_TOOL_FNS
+from tools.notion_tools import NOTION_TOOLS,  NOTION_TOOL_FNS
+from agent.cache        import Cache
+from agent.planner      import build_system_prompt
+
+# ── Config ─────────────────────────────────────────────────────────────────────
+
+MODEL       = "gpt-4o-mini"
+GITHUB_REPO = os.environ.get("GITHUB_REPO", "")
+client      = AsyncOpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
+
+ALL_TOOLS = GITHUB_TOOLS + SLACK_TOOLS + NOTION_TOOLS
+ALL_FNS   = {**GITHUB_TOOL_FNS, **SLACK_TOOL_FNS, **NOTION_TOOL_FNS}
+
+tool_cache = Cache(ttl_seconds=300)
+
+# session_id → list of message dicts
+sessions: dict[str, list[dict]] = {}
+
+# ── Lifespan ───────────────────────────────────────────────────────────────────
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    missing = [v for v in ["OPENAI_API_KEY"] if not os.environ.get(v)]
+    if missing:
+        print(f"⚠️  Missing env vars: {', '.join(missing)}")
+    print(f"  GitHub {'✓' if os.environ.get('GITHUB_TOKEN') else '✗'}  "
+          f"Slack {'✓' if os.environ.get('SLACK_BOT_TOKEN') else '✗'}  "
+          f"Notion {'✓' if os.environ.get('NOTION_API_TOKEN') else '✗'}")
+    yield
+
+# ── App ────────────────────────────────────────────────────────────────────────
+
+app = FastAPI(
+    title="Enterprise Knowledge Assistant",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ── Schemas ────────────────────────────────────────────────────────────────────
+
+class ChatRequest(BaseModel):
+    message: str
+    session_id: Optional[str] = None   # omit to start a new session
+
+class ToolCall(BaseModel):
+    name: str
+    args: dict
+    result: str
+    cached: bool
+
+class ChatResponse(BaseModel):
+    answer: str
+    session_id: str
+    elapsed_seconds: float
+    tool_calls: list[ToolCall]
+
+class ClearResponse(BaseModel):
+    cleared: bool
+    session_id: str
+
+class HealthResponse(BaseModel):
+    status: str
+    model: str
+    github: bool
+    slack: bool
+    notion: bool
+    active_sessions: int
+
+# ── Agent ──────────────────────────────────────────────────────────────────────
+
+async def dispatch(name: str, args: dict) -> tuple[str, bool]:
+    """Returns (result, was_cached)."""
+    key    = f"{name}:{json.dumps(args, sort_keys=True)}"
+    cached = tool_cache.get(key)
+    if cached:
+        return cached, True
+    fn     = ALL_FNS.get(name)
+    result = await fn(**args) if fn else f"Unknown tool: {name}"
+    tool_cache.set(key, result)
+    return result, False
+
+
+async def run_agent(history: list[dict]) -> tuple[str, list[ToolCall]]:
+    system   = build_system_prompt(GITHUB_REPO)
+    messages = [{"role": "system", "content": system}] + history
+    tool_log: list[ToolCall] = []
+
+    for _ in range(14):
+        response = await client.chat.completions.create(
+            model=MODEL,
+            messages=messages,
+            tools=ALL_TOOLS,
+            tool_choice="auto",
+        )
+        msg        = response.choices[0].message
+        tool_calls = msg.tool_calls or []
+
+        if not tool_calls:
+            return msg.content or "", tool_log
+
+        messages.append(msg)
+
+        names_and_args = [
+            (tc.function.name, json.loads(tc.function.arguments))
+            for tc in tool_calls
+        ]
+
+        results = await asyncio.gather(*[
+            dispatch(name, args) for name, args in names_and_args
+        ])
+
+        for tc, (name, args), (result, was_cached) in zip(tool_calls, names_and_args, results):
+            tool_log.append(ToolCall(name=name, args=args,
+                                     result=result[:500], cached=was_cached))
+            messages.append({
+                "role":         "tool",
+                "tool_call_id": tc.id,
+                "content":      result,
+            })
+
+    return "⚠️ Reached reasoning limit. Try a more specific question.", tool_log
+
+# ── Routes ─────────────────────────────────────────────────────────────────────
+
+@app.post("/chat", response_model=ChatResponse)
+async def chat(req: ChatRequest):
+    session_id = req.session_id or str(uuid.uuid4())
+    history    = sessions.setdefault(session_id, [])
+
+    history.append({"role": "user", "content": req.message})
+
+    t0 = time.monotonic()
+    try:
+        answer, tool_log = await run_agent(history)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+    history.append({"role": "assistant", "content": answer})
+
+    # cap session size
+    if len(history) > 60:
+        sessions[session_id] = history[-60:]
+
+    return ChatResponse(
+        answer=answer,
+        session_id=session_id,
+        elapsed_seconds=round(time.monotonic() - t0, 2),
+        tool_calls=tool_log,
+    )
+
+
+@app.delete("/chat", response_model=ClearResponse)
+async def clear_session(session_id: str):
+    existed = session_id in sessions
+    sessions.pop(session_id, None)
+    tool_cache.clear()
+    return ClearResponse(cleared=existed, session_id=session_id)
+
+
+@app.get("/health", response_model=HealthResponse)
+async def health():
+    return HealthResponse(
+        status="ok",
+        model=MODEL,
+        github=bool(os.environ.get("GITHUB_TOKEN")),
+        slack=bool(os.environ.get("SLACK_BOT_TOKEN")),
+        notion=bool(os.environ.get("NOTION_API_TOKEN")),
+        active_sessions=len(sessions),
+    )

toolsforgitnotionslack/main.py

@@ -0,0 +1,121 @@
+"""
+Enterprise Knowledge Assistant
+GPT-4o-mini orchestrated, MCP-style tool calling across GitHub, Slack, Notion.
+
+pip install openai httpx python-dotenv
+
+.env:
+  OPENAI_API_KEY=
+  GITHUB_TOKEN=       # free PAT with repo read scope
+  GITHUB_REPO=        # default "owner/repo" (optional)
+  SLACK_BOT_TOKEN=    # free workspace bot token
+  NOTION_API_TOKEN=   # free integration token
+"""
+
+from dotenv import load_dotenv
+load_dotenv()
+
+import asyncio, json, os, time
+from openai import AsyncOpenAI
+from tools.github_tools import GITHUB_TOOLS, GITHUB_TOOL_FNS
+from tools.slack_tools  import SLACK_TOOLS,  SLACK_TOOL_FNS
+from tools.notion_tools import NOTION_TOOLS,  NOTION_TOOL_FNS
+from agent.cache        import Cache
+from agent.planner      import build_system_prompt
+
+MODEL       = "gpt-4o-mini"
+GITHUB_REPO = os.environ.get("GITHUB_REPO", "")
+client      = AsyncOpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
+# ALL_TOOLS = GITHUB_TOOLS+ NOTION_TOOLS
+# ALL_FNS = {**GITHUB_TOOL_FNS,**NOTION_TOOL_FNS}
+ALL_TOOLS   = GITHUB_TOOLS + SLACK_TOOLS + NOTION_TOOLS
+ALL_FNS     = {**GITHUB_TOOL_FNS, **SLACK_TOOL_FNS, **NOTION_TOOL_FNS}
+cache       = Cache(ttl_seconds=300)
+
+
+async def dispatch(name: str, args: dict) -> str:
+    key    = f"{name}:{json.dumps(args, sort_keys=True)}"
+    cached = cache.get(key)
+    if cached:
+        return f"[cached] {cached}"
+    fn     = ALL_FNS.get(name)
+    result = await fn(**args) if fn else f"Unknown tool: {name}"
+    cache.set(key, result)
+    return result
+
+
+async def run_agent(history: list[dict]) -> str:
+    system = build_system_prompt(GITHUB_REPO)
+    messages = [{"role": "system", "content": system}] + history
+
+    for _ in range(14):
+        response = await client.chat.completions.create(
+            model=MODEL,
+            messages=messages,
+            tools=ALL_TOOLS,
+            tool_choice="auto",
+        )
+        msg        = response.choices[0].message
+        tool_calls = msg.tool_calls or []
+
+        if not tool_calls:
+            return msg.content or ""
+
+        messages.append(msg)
+
+        results = await asyncio.gather(*[
+            dispatch(tc.function.name, json.loads(tc.function.arguments))
+            for tc in tool_calls
+        ])
+
+        for tc, result in zip(tool_calls, results):
+            tag = " [cached]" if result.startswith("[cached]") else ""
+            print(f"  🔧 {tc.function.name}{tag} → {result[:90].replace(chr(10),' ')}…")
+            messages.append({
+                "role":         "tool",
+                "tool_call_id": tc.id,
+                "content":      result,
+            })
+
+    return "⚠️ Reached reasoning limit. Try a more specific question."
+
+
+async def chat_loop():
+    history: list[dict] = []
+    print(f"\n{'═'*60}\n  Enterprise Knowledge Assistant  |  {MODEL}")
+    print(f"  GitHub {'✓' if os.environ.get('GITHUB_TOKEN') else '✗'}  "
+          f"Slack {'✓' if os.environ.get('SLACK_BOT_TOKEN') else '✗'}  "
+          f"Notion {'✓' if os.environ.get('NOTION_API_TOKEN') else '✗'}")
+    if GITHUB_REPO:
+        print(f"  Default repo: {GITHUB_REPO}")
+    print(f"{'═'*60}\nCommands: /clear  /quit\n")
+
+    while True:
+        try:
+            user = input("You: ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\n👋 Bye!"); break
+        if not user: continue
+        if user.lower() in ("/quit", "/exit"):
+            print("👋 Bye!"); break
+        if user.lower() == "/clear":
+            history = []; cache.clear()
+            print("🗑️  Cleared.\n"); continue
+
+        history.append({"role": "user", "content": user})
+        t0 = time.monotonic()
+        try:
+            answer = await run_agent(history)
+        except Exception as e:
+            answer = f"❌ {e}"
+
+        history.append({"role": "assistant", "content": answer})
+        print(f"\nAssistant ({time.monotonic()-t0:.1f}s):\n{answer}\n{'─'*60}")
+        if len(history) > 60:
+            history = history[-60:]
+
+
+if __name__ == "__main__":
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("⚠️  Missing OPENAI_API_KEY")
+    asyncio.run(chat_loop())

toolsforgitnotionslack/tools/github_tools.py

@@ -0,0 +1,256 @@
+"""
+GitHub tools — discovery-first, markdown-only reads, paginated, rate-limit aware.
+"""
+import os
+import httpx
+
+GH           = "https://api.github.com"
+GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN", "")
+GITHUB_REPO  = os.environ.get("GITHUB_REPO", "")
+
+
+def _headers() -> dict:
+    return {
+        "Authorization":        f"Bearer {GITHUB_TOKEN}",
+        "Accept":               "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+
+
+def _target(repo: str) -> str:
+    return repo or GITHUB_REPO
+
+
+def _rate_warn(resp: httpx.Response) -> str | None:
+    if resp.headers.get("x-ratelimit-remaining", "1") == "0":
+        reset = resp.headers.get("x-ratelimit-reset", "soon")
+        return f"⚠️ GitHub rate limit reached. Resets at epoch {reset}."
+    return None
+
+
+# ── Tools ──────────────────────────────────────────────────────────────────────
+
+async def github_list_repos(org_or_user: str = "", repo_type: str = "all",
+                             page: int = 1) -> str:
+    params = {"type": repo_type, "per_page": 50, "page": page}
+    async with httpx.AsyncClient(timeout=15) as h:
+        if org_or_user:
+            r = await h.get(f"{GH}/orgs/{org_or_user}/repos",
+                            headers=_headers(), params=params)
+            if r.status_code == 404:
+                r = await h.get(f"{GH}/users/{org_or_user}/repos",
+                                headers=_headers(), params=params)
+        else:
+            r = await h.get(f"{GH}/user/repos", headers=_headers(), params=params)
+    if w := _rate_warn(r): return w
+    if r.status_code != 200: return f"GitHub error {r.status_code}: {r.text[:300]}"
+    repos = r.json()
+    if not repos: return "No repositories found."
+    lines = [
+        f"• {repo['full_name']}  {'🔒' if repo['private'] else '🌐'}  "
+        f"⭐{repo['stargazers_count']}  {(repo.get('description') or '')[:80]}"
+        for repo in repos
+    ]
+    if len(repos) == 50:
+        lines.append(f"[Page {page} — call with page={page+1} for more]")
+    return "\n".join(lines)
+
+
+async def github_repo_summary(repo: str = "") -> str:
+    t = _target(repo)
+    if not t: return "Provide repo as 'owner/repo' or set GITHUB_REPO."
+    async with httpx.AsyncClient(timeout=15) as h:
+        r = await h.get(f"{GH}/repos/{t}", headers=_headers())
+    if w := _rate_warn(r): return w
+    if r.status_code == 404: return f"Repo not found: {t}"
+    if r.status_code != 200: return f"GitHub error {r.status_code}"
+    d = r.json()
+    topics = ", ".join(d.get("topics", [])) or "none"
+    return (
+        f"Repo: {d['full_name']}\n"
+        f"Description: {d.get('description') or 'n/a'}\n"
+        f"Language: {d.get('language') or 'n/a'}\n"
+        f"Topics: {topics}\n"
+        f"Default branch: {d.get('default_branch')}\n"
+        f"Stars: {d['stargazers_count']}  Open issues: {d['open_issues_count']}\n"
+        f"URL: {d['html_url']}"
+    )
+
+
+async def github_list_files(repo: str = "", path: str = "", branch: str = "") -> str:
+    t = _target(repo)
+    if not t: return "Provide repo as 'owner/repo' or set GITHUB_REPO."
+    params = {"ref": branch} if branch else {}
+    async with httpx.AsyncClient(timeout=15) as h:
+        r = await h.get(f"{GH}/repos/{t}/contents/{path}",
+                        headers=_headers(), params=params)
+    if w := _rate_warn(r): return w
+    if r.status_code == 404: return f"Path '{path}' not found in {t}."
+    if r.status_code != 200: return f"GitHub error {r.status_code}"
+    items = r.json()
+    if isinstance(items, dict):
+        return f"'{path}' is a file. Use github_read_file to read it."
+    lines = []
+    for item in sorted(items, key=lambda x: (x["type"] != "dir", x["name"])):
+        icon = "📁" if item["type"] == "dir" else "📄"
+        size = f"  {item.get('size',0):,}b" if item["type"] == "file" else ""
+        lines.append(f"{icon} {item['path']}{size}")
+    return "\n".join(lines) or "Empty directory."
+
+
+async def github_read_file(path: str, repo: str = "", branch: str = "") -> str:
+    t = _target(repo)
+    if not t: return "Provide repo as 'owner/repo' or set GITHUB_REPO."
+    lower = path.lower()
+    allowed_exts  = (".md", ".mdx", ".txt", ".rst", ".adoc")
+    allowed_names = ("readme", "changelog", "contributing", "license", "notice")
+    allowed_dirs  = ("docs/", "doc/", "wiki/", "adr/", "architecture/", "rfcs/")
+    is_doc = (
+        any(lower.endswith(e) for e in allowed_exts)
+        or any(os.path.basename(lower) == n for n in allowed_names)
+        or any(lower.startswith(d) for d in allowed_dirs)
+    )
+    if not is_doc:
+        return (
+            f"⚠️ '{path}' looks like a source/config file. "
+            "This tool is for documentation only (.md, README, docs/ etc). "
+            "Re-call with the same args only if the user explicitly asked for this file."
+        )
+    params = {"ref": branch} if branch else {}
+    async with httpx.AsyncClient(timeout=15) as h:
+        r = await h.get(
+            f"{GH}/repos/{t}/contents/{path}",
+            headers={**_headers(), "Accept": "application/vnd.github.raw+json"},
+            params=params,
+        )
+    if w := _rate_warn(r): return w
+    if r.status_code == 404: return f"File not found: {path} in {t}"
+    if r.status_code != 200: return f"GitHub error {r.status_code}"
+    content = r.text
+    total   = len(content)
+    if total > 8000:
+        content = content[:8000] + f"\n\n…[truncated — {total:,} chars total]"
+    return f"[{t} · {path}]\n\n{content}"
+
+
+async def github_search_code(query: str, repo: str = "", language: str = "",
+                              path_filter: str = "") -> str:
+    t = _target(repo)
+    q = query
+    if t:           q += f" repo:{t}"
+    if language:    q += f" language:{language}"
+    if path_filter: q += f" path:{path_filter}"
+    async with httpx.AsyncClient(timeout=15) as h:
+        r = await h.get(f"{GH}/search/code", headers=_headers(),
+                        params={"q": q, "per_page": 10})
+    if w := _rate_warn(r): return w
+    if r.status_code == 422: return "Search query too short or invalid."
+    if r.status_code == 403: return "GitHub search rate limit hit. Wait 60s then retry."
+    if r.status_code != 200: return f"GitHub error {r.status_code}: {r.text[:200]}"
+    items = r.json().get("items", [])
+    if not items: return "No matching files found."
+    return "\n".join(
+        f"• {i['repository']['full_name']}/{i['path']}\n  {i['html_url']}"
+        for i in items
+    )
+
+
+async def github_list_markdown_files(repo: str = "", folder: str = "") -> str:
+    t = _target(repo)
+    if not t: return "Provide repo as 'owner/repo' or set GITHUB_REPO."
+    q = f"extension:md repo:{t}"
+    if folder: q += f" path:{folder}"
+    async with httpx.AsyncClient(timeout=15) as h:
+        r = await h.get(f"{GH}/search/code", headers=_headers(),
+                        params={"q": q, "per_page": 30})
+    if w := _rate_warn(r): return w
+    if r.status_code != 200: return f"GitHub error {r.status_code}"
+    items = r.json().get("items", [])
+    if not items: return "No markdown files found."
+    return f"[{t}] {len(items)} markdown file(s):\n" + "\n".join(f"• {i['path']}" for i in items)
+
+
+# ── Registry ───────────────────────────────────────────────────────────────────
+
+GITHUB_TOOL_FNS = {
+    "github_list_repos":          github_list_repos,
+    "github_repo_summary":        github_repo_summary,
+    "github_list_files":          github_list_files,
+    "github_read_file":           github_read_file,
+    "github_search_code":         github_search_code,
+    "github_list_markdown_files": github_list_markdown_files,
+}
+
+GITHUB_TOOLS = [
+    {"type": "function", "function": {
+        "name": "github_list_repos",
+        "description": (
+            "List GitHub repositories for a user or org. "
+            "Call this FIRST when you don't know which repos exist. "
+            "Supports pagination. Do NOT call if you already have the repo name."
+        ),
+        "parameters": {"type": "object", "properties": {
+            "org_or_user": {"type": "string", "description": "GitHub username or org. Empty = authenticated user."},
+            "repo_type":   {"type": "string", "enum": ["all","public","private","forks","sources"]},
+            "page":        {"type": "integer", "description": "Page number, default 1"},
+        }},
+    }},
+    {"type": "function", "function": {
+        "name": "github_repo_summary",
+        "description": (
+            "Get lightweight repo metadata: description, language, topics, stars, open issues. "
+            "Call this INSTEAD of reading README when you just need a quick overview. "
+            "Much cheaper than github_read_file."
+        ),
+        "parameters": {"type": "object", "properties": {
+            "repo": {"type": "string", "description": "owner/repo"},
+        }},
+    }},
+    {"type": "function", "function": {
+        "name": "github_list_files",
+        "description": (
+            "List files and directories in a repo path. "
+            "Use this to explore repo structure BEFORE reading any file. "
+            "Do NOT use to read file content — use github_read_file for that."
+        ),
+        "parameters": {"type": "object", "properties": {
+            "repo":   {"type": "string"}, "path": {"type": "string"},
+            "branch": {"type": "string"},
+        }},
+    }},
+    {"type": "function", "function": {
+        "name": "github_read_file",
+        "description": (
+            "Read a file from GitHub. ONLY for documentation files: "
+            ".md .mdx .txt .rst, README, CHANGELOG, files in docs/ wiki/ adr/ architecture/. "
+            "Do NOT use for .py .ts .json .yaml .lock source files unless user explicitly asks."
+        ),
+        "parameters": {"type": "object", "required": ["path"], "properties": {
+            "path":   {"type": "string"}, "repo": {"type": "string"},
+            "branch": {"type": "string"},
+        }},
+    }},
+    {"type": "function", "function": {
+        "name": "github_search_code",
+        "description": (
+            "Search for text or code within GitHub repos. "
+            "Use to LOCATE relevant files before reading them. "
+            "Set language='markdown' and path_filter='docs/' to target documentation."
+        ),
+        "parameters": {"type": "object", "required": ["query"], "properties": {
+            "query":       {"type": "string"}, "repo":        {"type": "string"},
+            "language":    {"type": "string"}, "path_filter": {"type": "string"},
+        }},
+    }},
+    {"type": "function", "function": {
+        "name": "github_list_markdown_files",
+        "description": (
+            "List ALL markdown (.md) files in a repo, optionally scoped to a folder. "
+            "Use for documentation discovery before github_read_file. "
+            "Returns file paths only, not content."
+        ),
+        "parameters": {"type": "object", "properties": {
+            "repo":   {"type": "string"}, "folder": {"type": "string"},
+        }},
+    }},
+]

toolsforgitnotionslack/tools/notion_tools.py

@@ -0,0 +1,203 @@
+"""
+Notion tools — search, read pages, list and query databases.
+"""
+import os
+import httpx
+from dotenv import load_dotenv
+load_dotenv()
+NOTION_TOKEN = os.environ.get("NOTION_API_TOKEN", "")
+
+NOTION_HEADERS = {
+    "Authorization":  f"Bearer {NOTION_TOKEN}",
+    "Notion-Version": "2022-06-28",
+    "Content-Type":   "application/json",
+}
+
+
+def _extract_rich_text(rt: list) -> str:
+    return "".join(t.get("plain_text", "") for t in rt)
+
+
+async def notion_search(query: str, filter_type: str = "") -> str:
+    body: dict = {"query": query, "page_size": 10}
+    if filter_type in ("page", "database"):
+        body["filter"] = {"value": filter_type, "property": "object"}
+    async with httpx.AsyncClient(timeout=15) as h:
+        r = await h.post("https://api.notion.com/v1/search",
+                         headers=NOTION_HEADERS, json=body)
+    if r.status_code != 200: return f"Notion error {r.status_code}: {r.text[:300]}"
+    results = r.json().get("results", [])
+    if not results: return "No Notion pages or databases found."
+    out = []
+    for item in results:
+        obj   = item.get("object", "")
+        iid   = item.get("id", "")
+        url   = item.get("url", "")
+        title = "Untitled"
+        if obj == "page":
+            for prop in item.get("properties", {}).values():
+                if prop.get("type") == "title":
+                    title = _extract_rich_text(prop.get("title", [])) or "Untitled"
+                    break
+        elif obj == "database":
+            title = _extract_rich_text(item.get("title", [])) or "Untitled DB"
+        out.append(f"• [{obj}] {title}\n  id: {iid}\n  {url}")
+    return "\n\n".join(out)
+
+
+async def notion_read_page(page_id: str, max_blocks: int = 80) -> str:
+    async with httpx.AsyncClient(timeout=15) as h:
+        r = await h.get(
+            f"https://api.notion.com/v1/blocks/{page_id}/children",
+            headers=NOTION_HEADERS,
+            params={"page_size": max_blocks},
+        )
+    if r.status_code != 200: return f"Notion error {r.status_code}: {r.text[:300]}"
+    blocks = r.json().get("results", [])
+    PREFIXES = {
+        "heading_1":           "# ",
+        "heading_2":           "## ",
+        "heading_3":           "### ",
+        "bulleted_list_item":  "• ",
+        "numbered_list_item":  "1. ",
+        "to_do":               "☐ ",
+        "toggle":              "▶ ",
+        "quote":               "> ",
+        "callout":             "💡 ",
+        "code":                "```\n",
+    }
+    lines = []
+    for block in blocks:
+        btype = block.get("type", "")
+        data  = block.get(btype, {})
+        rt    = data.get("rich_text", [])
+        text  = _extract_rich_text(rt)
+        if not text and btype not in ("divider", "image"):
+            continue
+        if btype == "divider":
+            lines.append("---")
+        elif btype == "image":
+            url = data.get("external", {}).get("url") or data.get("file", {}).get("url", "")
+            lines.append(f"[image: {url}]")
+        else:
+            prefix = PREFIXES.get(btype, "")
+            suffix = "\n```" if btype == "code" else ""
+            lines.append(f"{prefix}{text}{suffix}")
+    return "\n".join(lines) or "Page is empty or has unsupported block types."
+
+
+async def notion_list_databases(query: str = "") -> str:
+    body: dict = {"filter": {"value": "database", "property": "object"}, "page_size": 20}
+    if query: body["query"] = query
+    async with httpx.AsyncClient(timeout=15) as h:
+        r = await h.post("https://api.notion.com/v1/search",
+                         headers=NOTION_HEADERS, json=body)
+    if r.status_code != 200: return f"Notion error {r.status_code}: {r.text[:300]}"
+    results = r.json().get("results", [])
+    if not results: return "No databases found."
+    return "\n".join(
+        f"• {_extract_rich_text(db.get('title', [])) or 'Untitled'}  id:{db['id']}"
+        for db in results
+    )
+
+
+async def notion_query_database(database_id: str, filter_property: str = "",
+                                 filter_value: str = "", page_size: int = 20) -> str:
+    body: dict = {"page_size": min(page_size, 50)}
+    if filter_property and filter_value:
+        body["filter"] = {
+            "property":  filter_property,
+            "rich_text": {"contains": filter_value},
+        }
+    async with httpx.AsyncClient(timeout=15) as h:
+        r = await h.post(
+            f"https://api.notion.com/v1/databases/{database_id}/query",
+            headers=NOTION_HEADERS, json=body,
+        )
+    if r.status_code != 200: return f"Notion error {r.status_code}: {r.text[:300]}"
+    results = r.json().get("results", [])
+    if not results: return "No results found."
+    rows = []
+    for page in results:
+        row = {}
+        for name, prop in page.get("properties", {}).items():
+            ptype = prop.get("type")
+            if ptype == "title":
+                row[name] = _extract_rich_text(prop.get("title", []))
+            elif ptype == "rich_text":
+                row[name] = _extract_rich_text(prop.get("rich_text", []))
+            elif ptype == "select":
+                row[name] = (prop.get("select") or {}).get("name", "")
+            elif ptype == "multi_select":
+                row[name] = ", ".join(s["name"] for s in prop.get("multi_select", []))
+            elif ptype == "number":
+                row[name] = prop.get("number", "")
+            elif ptype == "checkbox":
+                row[name] = "✓" if prop.get("checkbox") else "✗"
+            elif ptype == "date":
+                row[name] = (prop.get("date") or {}).get("start", "")
+            elif ptype == "people":
+                row[name] = ", ".join(p.get("name", "") for p in prop.get("people", []))
+        rows.append("  ".join(f"{k}: {v}" for k, v in row.items() if v))
+    return "\n".join(rows)
+
+
+# ── Registry ───────────────────────────────────────────────────────────────────
+
+NOTION_TOOL_FNS = {
+    "notion_search":          notion_search,
+    "notion_read_page":       notion_read_page,
+    "notion_list_databases":  notion_list_databases,
+    "notion_query_database":  notion_query_database,
+}
+
+NOTION_TOOLS = [
+    {"type": "function", "function": {
+        "name": "notion_search",
+        "description": (
+            "Search Notion for pages and databases by keyword. "
+            "Always call this FIRST to get page IDs before calling notion_read_page. "
+            "filter_type: 'page', 'database', or '' (both)."
+        ),
+        "parameters": {"type": "object", "required": ["query"], "properties": {
+            "query":       {"type": "string"},
+            "filter_type": {"type": "string", "enum": ["page", "database", ""]},
+        }},
+    }},
+    {"type": "function", "function": {
+        "name": "notion_read_page",
+        "description": (
+            "Read the full content of a Notion page by its ID. "
+            "Only call this AFTER getting a page_id from notion_search. "
+            "Preserves heading hierarchy, bullets, to-dos, callouts, code blocks."
+        ),
+        "parameters": {"type": "object", "required": ["page_id"], "properties": {
+            "page_id":    {"type": "string"},
+            "max_blocks": {"type": "integer", "description": "Max blocks to read, default 80"},
+        }},
+    }},
+    {"type": "function", "function": {
+        "name": "notion_list_databases",
+        "description": (
+            "List accessible Notion databases, optionally filtered by name. "
+            "Use this before notion_query_database to find the correct database_id."
+        ),
+        "parameters": {"type": "object", "properties": {
+            "query": {"type": "string", "description": "Filter by database name"},
+        }},
+    }},
+    {"type": "function", "function": {
+        "name": "notion_query_database",
+        "description": (
+            "Query rows from a Notion database. Supports text property filtering. "
+            "Use notion_list_databases first to get the database_id. "
+            "Extracts title, text, select, multi_select, number, checkbox, date, people fields."
+        ),
+        "parameters": {"type": "object", "required": ["database_id"], "properties": {
+            "database_id":      {"type": "string"},
+            "filter_property":  {"type": "string", "description": "Property name to filter on e.g. 'Status'"},
+            "filter_value":     {"type": "string", "description": "Value to match e.g. 'Done'"},
+            "page_size":        {"type": "integer", "description": "Rows to return, default 20"},
+        }},
+    }},
+]

toolsforgitnotionslack/tools/slack_tools.py

@@ -0,0 +1,162 @@
+"""
+Slack tools — search, history, threads, channel metadata.
+"""
+import os
+import httpx
+
+SLACK_TOKEN = os.environ.get("SLACK_BOT_TOKEN", "")
+
+
+def _headers() -> dict:
+    return {"Authorization": f"Bearer {SLACK_TOKEN}"}
+
+
+async def slack_list_channels(filter_name: str = "") -> str:
+    async with httpx.AsyncClient(timeout=15) as h:
+        r = await h.get(
+            "https://slack.com/api/conversations.list",
+            headers=_headers(),
+            params={"types": "public_channel,private_channel",
+                    "limit": 200, "exclude_archived": True},
+        )
+    d = r.json()
+    if not d.get("ok"): return f"Slack error: {d.get('error')}"
+    channels = d.get("channels", [])
+    if filter_name:
+        channels = [c for c in channels if filter_name.lower() in c["name"].lower()]
+    if not channels: return "No channels found."
+    return "\n".join(
+        f"• #{c['name']}  id:{c['id']}  members:{c.get('num_members',0)}"
+        + (f"  [{c['purpose']['value'][:60]}]" if c.get("purpose", {}).get("value") else "")
+        for c in channels
+    )
+
+
+async def slack_search(query: str, channel: str = "",
+                        oldest_date: str = "", latest_date: str = "",
+                        count: int = 10) -> str:
+    q = query
+    if channel:     q = f"in:#{channel.lstrip('#')} {q}"
+    if oldest_date: q += f" after:{oldest_date}"
+    if latest_date: q += f" before:{latest_date}"
+    async with httpx.AsyncClient(timeout=15) as h:
+        r = await h.get(
+            "https://slack.com/api/search.messages",
+            headers=_headers(),
+            params={"query": q, "count": min(count, 20), "highlight": False},
+        )
+    d = r.json()
+    if not d.get("ok"): return f"Slack error: {d.get('error')}"
+    matches = d.get("messages", {}).get("matches", [])
+    if not matches: return "No messages found."
+    parts = []
+    for m in matches:
+        ch   = m.get("channel", {}).get("name", "?")
+        user = m.get("username", "?")
+        ts   = m.get("ts", "")
+        text = m.get("text", "")[:400]
+        link = m.get("permalink", "")
+        parts.append(f"[#{ch} | {user} | {ts}]\n{text}\n{link}")
+    return "\n\n---\n\n".join(parts)
+
+
+async def slack_channel_history(channel_id: str, limit: int = 20,
+                                 oldest: str = "", latest: str = "") -> str:
+    params: dict = {"channel": channel_id, "limit": min(limit, 50)}
+    if oldest: params["oldest"] = oldest
+    if latest: params["latest"] = latest
+    async with httpx.AsyncClient(timeout=15) as h:
+        r = await h.get("https://slack.com/api/conversations.history",
+                        headers=_headers(), params=params)
+    d = r.json()
+    if not d.get("ok"): return f"Slack error: {d.get('error')}"
+    messages = d.get("messages", [])
+    if not messages: return "No messages in range."
+    lines = []
+    for m in reversed(messages):
+        reply_hint = f"  [🧵 {m['reply_count']} replies]" if m.get("reply_count") else ""
+        lines.append(f"[{m.get('ts','')}] {m.get('text','')[:300]}{reply_hint}")
+    return "\n".join(lines)
+
+
+async def slack_get_thread(channel_id: str, thread_ts: str, limit: int = 30) -> str:
+    async with httpx.AsyncClient(timeout=15) as h:
+        r = await h.get(
+            "https://slack.com/api/conversations.replies",
+            headers=_headers(),
+            params={"channel": channel_id, "ts": thread_ts, "limit": min(limit, 50)},
+        )
+    d = r.json()
+    if not d.get("ok"): return f"Slack error: {d.get('error')}"
+    messages = d.get("messages", [])
+    if not messages: return "Thread not found or empty."
+    return "\n".join(
+        f"[{m.get('ts','')}] {m.get('username', m.get('user','?'))}: {m.get('text','')[:400]}"
+        for m in messages
+    )
+
+
+# ── Registry ───────────────────────────────────────────────────────────────────
+
+SLACK_TOOL_FNS = {
+    "slack_list_channels":   slack_list_channels,
+    "slack_search":          slack_search,
+    "slack_channel_history": slack_channel_history,
+    "slack_get_thread":      slack_get_thread,
+}
+
+SLACK_TOOLS = [
+    {"type": "function", "function": {
+        "name": "slack_list_channels",
+        "description": (
+            "List public/private Slack channels with their IDs. "
+            "Call this FIRST to discover channel IDs before using slack_channel_history. "
+            "Do NOT use to search messages — use slack_search for that."
+        ),
+        "parameters": {"type": "object", "properties": {
+            "filter_name": {"type": "string", "description": "Filter channels by name substring"},
+        }},
+    }},
+    {"type": "function", "function": {
+        "name": "slack_search",
+        "description": (
+            "Search Slack messages across channels by topic or keyword. "
+            "Supports time filtering with oldest_date/latest_date (YYYY-MM-DD). "
+            "Use this for topic lookups. Use slack_channel_history for recent chronological messages."
+        ),
+        "parameters": {"type": "object", "required": ["query"], "properties": {
+            "query":       {"type": "string"},
+            "channel":     {"type": "string", "description": "Limit to #channel-name"},
+            "oldest_date": {"type": "string", "description": "YYYY-MM-DD"},
+            "latest_date": {"type": "string", "description": "YYYY-MM-DD"},
+            "count":       {"type": "integer", "description": "Max results, default 10"},
+        }},
+    }},
+    {"type": "function", "function": {
+        "name": "slack_channel_history",
+        "description": (
+            "Fetch recent messages from a Slack channel by channel ID. "
+            "Use slack_list_channels first to get the channel ID. "
+            "oldest/latest are Unix timestamps for date range filtering."
+        ),
+        "parameters": {"type": "object", "required": ["channel_id"], "properties": {
+            "channel_id": {"type": "string"},
+            "limit":      {"type": "integer", "description": "Max messages, default 20"},
+            "oldest":     {"type": "string", "description": "Unix timestamp"},
+            "latest":     {"type": "string", "description": "Unix timestamp"},
+        }},
+    }},
+    {"type": "function", "function": {
+        "name": "slack_get_thread",
+        "description": (
+            "Reconstruct a full Slack thread given a channel_id and thread_ts (timestamp). "
+            "Use this when slack_channel_history shows a message has replies. "
+            "Returns all replies in chronological order."
+        ),
+        "parameters": {"type": "object", "required": ["channel_id", "thread_ts"], "properties": {
+            "channel_id": {"type": "string"},
+            "thread_ts":  {"type": "string", "description": "Timestamp of the parent message"},
+            "limit":      {"type": "integer", "description": "Max replies, default 30"},
+        }},
+    }},
+]