prashflow 1.0.0__py3-none-any.whl

prashflow/__init__.py

@@ -0,0 +1,25 @@
+from .__version__ import __version__
+from .rag import RAG
+from .chat import Chat
+from .inmemory import InMemoryDB, InMemoryVectorStore
+from .agent import Agent
+from .agentchat import AgentChat
+from .multiagent import MultiAgent
+from .tools import tool, ToolManager
+from .config import load_config
+from .errors import PrashFlowError
+
+__all__ = [
+    "RAG",
+    "Chat",
+    "InMemoryDB",
+    "InMemoryVectorStore",
+    "Agent",
+    "AgentChat",
+    "MultiAgent",
+    "tool",
+    "ToolManager",
+    "load_config",
+    "PrashFlowError",
+    "__version__",
+]

prashflow/__version__.py

@@ -0,0 +1 @@
+__version__ = "1.4.0"

prashflow/agent.py

@@ -0,0 +1,112 @@
+from langchain_core.messages import HumanMessage
+from .llm import create_llm
+from .tools import calculator_tool, web_search_tool
+from .mcp import MCPManager
+from .errors import ConfigurationError, AgentError
+from .display import success
+from .session import SessionStore
+
+class Agent:
+    def __init__(
+        self,
+        llm=None,
+        tools=None,
+        mcp_servers=None,
+        system_prompt="You are a helpful AI assistant.",
+        temperature=0,
+        max_retries=1,
+        session_id="default",
+        memory=None,
+        **legacy,
+    ):
+        if llm is None:
+            llm = legacy.get("model", "ollama:qwen3:8b")
+        self.model = create_llm(llm)
+        self.system_prompt = system_prompt
+        self.max_retries = max_retries
+        self.session_id = session_id
+        self.sessions = memory if isinstance(memory, SessionStore) else SessionStore(memory)
+        self.tools = self._build_tools(tools or [])
+        self.mcp = MCPManager(mcp_servers or [])
+        self.mcp.validate()
+        self._build_graph()
+        success("Agent initialized.")
+
+    def _build_graph(self):
+        try:
+            from langgraph.prebuilt import create_react_agent
+            try:
+                self.graph = create_react_agent(
+                    self.model, self.tools, prompt=self.system_prompt
+                )
+            except TypeError:
+                self.graph = create_react_agent(self.model, self.tools)
+        except Exception as exc:
+            raise AgentError("Could not initialize LangGraph agent.") from exc
+
+    def _build_tools(self, items):
+        result = []
+        for item in items:
+            if isinstance(item, str):
+                if item == "calculator":
+                    result.append(calculator_tool())
+                elif item == "web_search":
+                    result.append(web_search_tool())
+                else:
+                    raise ConfigurationError(f"Unknown built-in tool '{item}'.")
+            elif callable(item):
+                result.append(item)
+            else:
+                raise ConfigurationError("Tool must be a string or callable.")
+        return result
+
+    def add_tool(self, custom_tool):
+        if not callable(custom_tool):
+            raise ConfigurationError("Custom tool must be callable.")
+        self.tools.append(custom_tool)
+        self._build_graph()
+        return self
+
+    async def discover_mcp_tools(self):
+        return await self.mcp.discover_tools()
+
+    def run(self, query):
+        if not query.strip():
+            raise ConfigurationError("Agent query cannot be empty.")
+        history = self.sessions.history(self.session_id)
+        messages = history + [{"role": "user", "content": query}]
+        last = None
+        for _ in range(self.max_retries + 1):
+            try:
+                result = self.graph.invoke({"messages": messages})
+                outputs = result.get("messages", [])
+                if not outputs:
+                    raise AgentError("Agent returned no messages.")
+                answer = getattr(outputs[-1], "content", "") or ""
+                self.sessions.append(self.session_id, "user", query)
+                self.sessions.append(self.session_id, "assistant", answer)
+                return answer
+            except Exception as exc:
+                last = exc
+        raise AgentError(f"Agent failed after {self.max_retries + 1} attempt(s).") from last
+
+    def stream(self, query):
+        if not query.strip():
+            raise ConfigurationError("Agent query cannot be empty.")
+        history = self.sessions.history(self.session_id)
+        messages = history + [{"role": "user", "content": query}]
+        parts = []
+        try:
+            for item in self.graph.stream({"messages": messages}, stream_mode="messages"):
+                msg = item[0] if isinstance(item, tuple) else item
+                text = getattr(msg, "content", "") or ""
+                if text:
+                    parts.append(text)
+                    yield text
+            self.sessions.append(self.session_id, "user", query)
+            self.sessions.append(self.session_id, "assistant", "".join(parts))
+        except Exception as exc:
+            raise AgentError(f"Agent streaming failed: {exc}") from exc
+
+    def clear_session(self):
+        self.sessions.clear(self.session_id)

prashflow/agentchat.py

@@ -0,0 +1,5 @@
+from .agent import Agent
+
+class AgentChat(Agent):
+    """Friendly alias for agentic conversational use."""
+    pass

prashflow/chat.py

@@ -0,0 +1,38 @@
+from .llm import create_llm
+from .session import SessionStore
+from .errors import ConfigurationError
+
+class Chat:
+    """Provider-agnostic chat with session memory and streaming."""
+    def __init__(self, llm=None, memory=None, session_id="default", max_messages=30, **legacy):
+        llm = llm or legacy.get("model") or "ollama:qwen3:8b"
+        self.llm = create_llm(llm)
+        self.sessions = memory if isinstance(memory, SessionStore) else SessionStore(memory, max_messages=max_messages)
+        self.session_id = session_id
+
+    def _messages(self, prompt):
+        return self.sessions.history(self.session_id) + [{"role": "user", "content": prompt}]
+
+    def chat(self, prompt):
+        if not prompt or not prompt.strip():
+            raise ConfigurationError("Chat prompt cannot be empty.")
+        response = self.llm.invoke(self._messages(prompt))
+        content = response.content or ""
+        self.sessions.append(self.session_id, "user", prompt)
+        self.sessions.append(self.session_id, "assistant", content)
+        return content
+
+    def stream(self, prompt):
+        if not prompt or not prompt.strip():
+            raise ConfigurationError("Chat prompt cannot be empty.")
+        parts = []
+        for chunk in self.llm.stream(self._messages(prompt)):
+            text = getattr(chunk, "content", "") or ""
+            if text:
+                parts.append(text)
+                yield text
+        self.sessions.append(self.session_id, "user", prompt)
+        self.sessions.append(self.session_id, "assistant", "".join(parts))
+
+    def clear(self):
+        self.sessions.clear(self.session_id)

prashflow/cli.py

@@ -0,0 +1,43 @@
+import sys
+import typer
+from .display import info, success, error
+from .rag import RAG
+
+app = typer.Typer(help="PrashFlow CLI")
+
+@app.command()
+def doctor():
+    import shutil, urllib.request
+    info(f"Python: {sys.version.split()[0]}")
+    if shutil.which("ollama"):
+        success("Ollama executable found.")
+    else:
+        error("Ollama not found", "Ollama is not on PATH.", "Install Ollama.")
+        raise typer.Exit(1)
+    try:
+        with urllib.request.urlopen("http://localhost:11434/api/tags", timeout=3) as r:
+            if r.status == 200:
+                success("Ollama server is reachable.")
+    except Exception:
+        error("Ollama unavailable", "Cannot reach localhost:11434.", "Run: ollama serve")
+        raise typer.Exit(1)
+
+@app.command()
+def ingest(source: str, db: str = "./chroma_db"):
+    try:
+        RAG(vector_db={"provider": "chroma", "path": db}).ingest(source)
+    except Exception as exc:
+        error("Ingestion failed", str(exc))
+        raise typer.Exit(1)
+
+@app.command()
+def ask(question: str, db: str = "./chroma_db", search_type: str = "hybrid"):
+    try:
+        rag = RAG(
+            vector_db={"provider": "chroma", "path": db},
+            retrieval={"type": search_type, "top_k": 5, "candidate_k": 20},
+        )
+        print(rag.ask(question))
+    except Exception as exc:
+        error("Question failed", str(exc))
+        raise typer.Exit(1)

prashflow/config.py

@@ -0,0 +1,26 @@
+import os
+from pathlib import Path
+import yaml
+from .errors import ConfigurationError
+
+def expand_env(value):
+    if isinstance(value, dict):
+        return {k: expand_env(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [expand_env(v) for v in value]
+    if isinstance(value, str):
+        if value.startswith("${") and value.endswith("}"):
+            name = value[2:-1]
+            return os.getenv(name, "")
+        return value
+    return value
+
+def load_config(path: str):
+    p = Path(path)
+    if not p.exists():
+        raise ConfigurationError(f"Configuration file not found: {path}")
+    try:
+        with p.open("r", encoding="utf-8") as f:
+            return expand_env(yaml.safe_load(f) or {})
+    except Exception as exc:
+        raise ConfigurationError(f"Invalid YAML configuration: {path}") from exc

prashflow/display.py

@@ -0,0 +1,14 @@
+from rich.console import Console
+from rich.panel import Panel
+
+console = Console()
+
+def info(msg): console.print(f"[cyan]ℹ[/cyan] {msg}")
+def success(msg): console.print(f"[green]✓[/green] {msg}")
+def warning(msg): console.print(f"[yellow]⚠[/yellow] {msg}")
+
+def error(title, msg, fix=None):
+    body = msg
+    if fix:
+        body += f"\n\n[bold]Fix:[/bold]\n{fix}"
+    console.print(Panel(body, title=f"❌ {title}", border_style="red"))

prashflow/errors.py

@@ -0,0 +1,15 @@
+class PrashFlowError(Exception):
+    """Base exception for the framework."""
+
+class ConfigurationError(PrashFlowError): pass
+class LLMError(PrashFlowError): pass
+class LLMConnectionError(LLMError): pass
+class EmbeddingError(PrashFlowError): pass
+class VectorDBError(PrashFlowError): pass
+class DocumentLoadError(PrashFlowError): pass
+class RetrievalError(PrashFlowError): pass
+class RerankerError(PrashFlowError): pass
+class DataSourceError(PrashFlowError): pass
+class ToolExecutionError(PrashFlowError): pass
+class AgentError(PrashFlowError): pass
+class MCPError(PrashFlowError): pass

prashflow/inmemory.py

@@ -0,0 +1,87 @@
+import math
+from collections import defaultdict
+from .errors import ConfigurationError
+
+class InMemoryDB:
+    """Simple process-local key/value database for chat state, sessions and metadata."""
+    def __init__(self):
+        self.data = defaultdict(dict)
+    def set(self, namespace, key, value):
+        self.data[namespace][key] = value
+    def get(self, namespace, key, default=None):
+        return self.data.get(namespace, {}).get(key, default)
+    def delete(self, namespace, key):
+        self.data.get(namespace, {}).pop(key, None)
+    def list(self, namespace):
+        return dict(self.data.get(namespace, {}))
+    def clear(self):
+        self.data.clear()
+
+class InMemoryVectorStore:
+    """Ephemeral vector store; useful for tests, demos and short-lived agents."""
+    def __init__(self, embeddings, **kwargs):
+        self.embeddings = embeddings
+        self.documents = []
+        self.vectors = []
+
+    def add_documents(self, documents):
+        if not documents:
+            return []
+        vectors = self.embeddings.embed_documents([d.page_content for d in documents])
+        self.documents.extend(documents)
+        self.vectors.extend(vectors)
+        return [d.metadata.get("chunk_id", str(i)) for i, d in enumerate(documents)]
+
+    def _cosine(self, a, b):
+        dot = sum(x*y for x, y in zip(a, b))
+        na = math.sqrt(sum(x*x for x in a))
+        nb = math.sqrt(sum(x*x for x in b))
+        return dot / (na * nb) if na and nb else 0.0
+
+    def _filtered(self, filter):
+        if not filter:
+            return list(range(len(self.documents)))
+        return [
+            i for i, d in enumerate(self.documents)
+            if all(d.metadata.get(k) == v for k, v in filter.items())
+        ]
+
+    def similarity_search(self, query, k=4, filter=None):
+        q = self.embeddings.embed_query(query)
+        ids = self._filtered(filter)
+        ranked = sorted(ids, key=lambda i: self._cosine(q, self.vectors[i]), reverse=True)
+        return [self.documents[i] for i in ranked[:k]]
+
+    def similarity_search_with_score(self, query, k=4, filter=None):
+        q = self.embeddings.embed_query(query)
+        ids = self._filtered(filter)
+        ranked = sorted(
+            ((i, self._cosine(q, self.vectors[i])) for i in ids),
+            key=lambda x: x[1], reverse=True
+        )
+        return [(self.documents[i], score) for i, score in ranked[:k]]
+
+    def max_marginal_relevance_search(self, query, k=4, fetch_k=20, lambda_mult=.5, filter=None):
+        q = self.embeddings.embed_query(query)
+        ids = self._filtered(filter)
+        candidates = sorted(ids, key=lambda i: self._cosine(q, self.vectors[i]), reverse=True)[:fetch_k]
+        selected = []
+        while candidates and len(selected) < k:
+            if not selected:
+                best = candidates[0]
+            else:
+                def mmr(i):
+                    relevance = self._cosine(q, self.vectors[i])
+                    diversity = max(
+                        self._cosine(self.vectors[i], self.vectors[j])
+                        for j in selected
+                    )
+                    return lambda_mult * relevance - (1-lambda_mult) * diversity
+                best = max(candidates, key=mmr)
+            selected.append(best)
+            candidates.remove(best)
+        return [self.documents[i] for i in selected]
+
+    def delete_collection(self):
+        self.documents.clear()
+        self.vectors.clear()

prashflow/llm.py

@@ -0,0 +1,206 @@
+from typing import Any, Iterator
+from .errors import ConfigurationError, LLMConnectionError
+
+def _message_dict(message):
+    role = getattr(message, "type", "human")
+    role = {"human": "user", "ai": "assistant", "system": "system", "tool": "tool"}.get(role, role)
+    content = message.content
+    return {"role": role, "content": content}
+
+class LiteLLMChatModel:
+    """
+    Small LangChain-compatible ChatModel adapter over LiteLLM.
+    LiteLLM provides one OpenAI-style interface across many providers,
+    including OpenAI, Azure, Anthropic, Gemini, OpenRouter, Ollama and
+    OpenAI-compatible endpoints.
+    """
+    def __init__(self, model, api_key=None, api_base=None, temperature=0, **kwargs):
+        self.model_name = model
+        self.api_key = api_key
+        self.api_base = api_base
+        self.temperature = temperature
+        self.kwargs = kwargs
+
+    @property
+    def _llm_type(self):
+        return "litellm"
+
+    def _call(self, messages, stream=False, **kwargs):
+        try:
+            import litellm
+        except ImportError as exc:
+            raise ConfigurationError(
+                "LiteLLM is not installed. Run: pip install 'prashflow[litellm]'"
+            ) from exc
+        params = dict(self.kwargs)
+        params.update(kwargs)
+        params.update({
+            "model": self.model_name,
+            "messages": [_message_dict(m) for m in messages],
+            "temperature": self.temperature,
+            "stream": stream,
+        })
+        if self.api_key:
+            params["api_key"] = self.api_key
+        if self.api_base:
+            params["api_base"] = self.api_base
+        return litellm.completion(**params)
+
+    def invoke(self, messages, **kwargs):
+        from langchain_core.messages import AIMessage
+        if isinstance(messages, str):
+            messages = [{"role": "user", "content": messages}]
+        try:
+            if messages and isinstance(messages[0], dict):
+                class M:
+                    def __init__(self, d): self.type, self.content = d.get("role"), d.get("content")
+                messages = [M(m) for m in messages]
+            response = self._call(messages, **kwargs)
+            content = response.choices[0].message.content or ""
+            return AIMessage(content=content)
+        except Exception as exc:
+            raise LLMConnectionError(
+                f"LiteLLM call failed for model '{self.model_name}': {exc}"
+            ) from exc
+
+    def stream(self, messages, **kwargs) -> Iterator[Any]:
+        from langchain_core.messages import AIMessageChunk
+        try:
+            if isinstance(messages, str):
+                class M:
+                    type = "human"
+                    content = messages
+                messages = [M()]
+            if messages and isinstance(messages[0], dict):
+                class M:
+                    def __init__(self, d): self.type, self.content = d.get("role"), d.get("content")
+                messages = [M(m) for m in messages]
+            response = self._call(messages, stream=True, **kwargs)
+            for chunk in response:
+                content = ""
+                try:
+                    content = chunk.choices[0].delta.content or ""
+                except Exception:
+                    pass
+                if content:
+                    yield AIMessageChunk(content=content)
+        except Exception as exc:
+            raise LLMConnectionError(
+                f"LiteLLM streaming failed for model '{self.model_name}': {exc}"
+            ) from exc
+
+def create_llm(config):
+    if isinstance(config, str):
+        if ":" in config:
+            provider, model = config.split(":", 1)
+        else:
+            provider, model = "ollama", config
+        config = {"provider": provider, "model": model}
+    config = dict(config or {})
+    provider = config.get("provider", "ollama").lower()
+    model = config.get("model")
+    if not model:
+        raise ConfigurationError("LLM model is required.")
+
+    if provider == "litellm":
+        return LiteLLMChatModel(
+            model=model,
+            api_key=config.get("api_key"),
+            api_base=config.get("base_url") or config.get("api_base"),
+            temperature=config.get("temperature", 0),
+            **config.get("extra", {}),
+        )
+
+    if provider == "ollama":
+        try:
+            from langchain_ollama import ChatOllama
+            return ChatOllama(
+                model=model,
+                base_url=config.get("base_url", "http://localhost:11434"),
+                temperature=config.get("temperature", 0),
+            )
+        except Exception as exc:
+            raise LLMConnectionError(
+                f"Could not initialize Ollama model '{model}'."
+            ) from exc
+
+    if provider in {"openai", "openai-compatible"}:
+        try:
+            from langchain_openai import ChatOpenAI
+        except ImportError as exc:
+            raise ConfigurationError(
+                "Install OpenAI support: pip install 'prashflow[openai]'"
+            ) from exc
+        kwargs = {
+            "model": model,
+            "temperature": config.get("temperature", 0),
+        }
+        if config.get("base_url"):
+            kwargs["base_url"] = config["base_url"]
+        if config.get("api_key"):
+            kwargs["api_key"] = config["api_key"]
+        return ChatOpenAI(**kwargs)
+
+    raise ConfigurationError(
+        f"Unsupported LLM provider '{provider}'. "
+        "Supported: ollama, openai, openai-compatible, litellm."
+    )
+
+def create_embeddings(config):
+    if isinstance(config, str):
+        provider, model = config.split(":", 1)
+        config = {"provider": provider, "model": model}
+    config = dict(config or {})
+    provider = config.get("provider", "ollama").lower()
+    model = config.get("model")
+    if not model:
+        raise ConfigurationError("Embedding model is required.")
+
+    if provider == "litellm":
+        try:
+            import litellm
+        except ImportError as exc:
+            raise ConfigurationError(
+                "Install LiteLLM support: pip install 'prashflow[litellm]'"
+            ) from exc
+
+        class LiteLLMEmbeddings:
+            def embed_documents(self, texts):
+                result = litellm.embedding(
+                    model=model,
+                    input=texts,
+                    api_key=config.get("api_key"),
+                    api_base=config.get("base_url") or config.get("api_base"),
+                )
+                return [x["embedding"] for x in result["data"]]
+            def embed_query(self, text):
+                return self.embed_documents([text])[0]
+        return LiteLLMEmbeddings()
+
+    if provider == "ollama":
+        try:
+            from langchain_ollama import OllamaEmbeddings
+            return OllamaEmbeddings(
+                model=model,
+                base_url=config.get("base_url", "http://localhost:11434"),
+            )
+        except Exception as exc:
+            raise LLMConnectionError(
+                f"Could not initialize Ollama embeddings '{model}'."
+            ) from exc
+
+    if provider in {"openai", "openai-compatible"}:
+        try:
+            from langchain_openai import OpenAIEmbeddings
+        except ImportError as exc:
+            raise ConfigurationError(
+                "Install OpenAI support: pip install 'prashflow[openai]'"
+            ) from exc
+        kwargs = {"model": model}
+        if config.get("api_key"):
+            kwargs["api_key"] = config["api_key"]
+        if config.get("base_url"):
+            kwargs["base_url"] = config["base_url"]
+        return OpenAIEmbeddings(**kwargs)
+
+    raise ConfigurationError(f"Unsupported embedding provider '{provider}'.")

prashflow/loaders.py

@@ -0,0 +1,40 @@
+from pathlib import Path
+from langchain_community.document_loaders import (
+    PyPDFLoader, TextLoader, CSVLoader, Docx2txtLoader, WebBaseLoader
+)
+from .errors import DocumentLoadError
+
+SUPPORTED = {".pdf", ".txt", ".md", ".csv", ".docx"}
+
+def load_file(path: Path):
+    try:
+        suffix = path.suffix.lower()
+        if suffix == ".pdf": return PyPDFLoader(str(path)).load()
+        if suffix in {".txt", ".md"}: return TextLoader(str(path), encoding="utf-8").load()
+        if suffix == ".csv": return CSVLoader(str(path)).load()
+        if suffix == ".docx": return Docx2txtLoader(str(path)).load()
+    except Exception as exc:
+        raise DocumentLoadError(f"Failed to load {path}: {exc}") from exc
+    raise DocumentLoadError(f"Unsupported file type: {suffix}")
+
+def load_source(source: str):
+    p = Path(source)
+    if p.exists():
+        if p.is_file():
+            return load_file(p)
+        docs = []
+        for f in p.rglob("*"):
+            if f.is_file() and f.suffix.lower() in SUPPORTED:
+                try:
+                    docs.extend(load_file(f))
+                except Exception:
+                    pass
+        if not docs:
+            raise DocumentLoadError(f"No supported documents found in {source}")
+        return docs
+    if source.startswith(("http://", "https://")):
+        try:
+            return WebBaseLoader(source).load()
+        except Exception as exc:
+            raise DocumentLoadError(f"Could not load URL {source}") from exc
+    raise DocumentLoadError(f"Source not found: {source}")

prashflow/mcp.py

@@ -0,0 +1,55 @@
+from .errors import MCPError, ConfigurationError
+
+class MCPManager:
+    """
+    MCP integration boundary.
+
+    The exact Python MCP SDK transport APIs have changed across SDK releases.
+    This adapter keeps server configuration in one place and exposes an
+    explicit async method for tool discovery. The synchronous Agent API can
+    consume pre-created LangChain tools, while applications using a specific
+    MCP SDK release can extend this adapter without changing Agent.
+    """
+    def __init__(self, servers=None):
+        self.servers = servers or []
+
+    def validate(self):
+        for server in self.servers:
+            if not server.get("name"):
+                raise ConfigurationError("Every MCP server needs a name.")
+            transport = server.get("transport", "stdio")
+            if transport == "stdio":
+                if not server.get("command"):
+                    raise ConfigurationError(
+                        f"MCP stdio server '{server['name']}' requires command."
+                    )
+            elif transport in {"streamable_http", "sse"}:
+                if not server.get("url"):
+                    raise ConfigurationError(
+                        f"MCP HTTP server '{server['name']}' requires url."
+                    )
+            else:
+                raise ConfigurationError(
+                    f"Unsupported MCP transport '{transport}'."
+                )
+        return True
+
+    async def discover_tools(self):
+        """
+        Return MCP tools when the installed MCP SDK/server adapter supports them.
+
+        This method deliberately fails clearly instead of pretending to have
+        connected to a server. Extend this method for your pinned MCP SDK.
+        """
+        self.validate()
+        try:
+            import mcp  # noqa: F401
+        except ImportError as exc:
+            raise MCPError(
+                "MCP support is not installed. Run: pip install 'prashflow[mcp]'"
+            ) from exc
+        raise MCPError(
+            "MCP server discovery requires an SDK transport adapter. "
+            "The server configuration was validated, but no transport session "
+            "was opened by this reference implementation."
+        )