agents-lab 0.1.0__tar.gz

agents_lab-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: agents-lab
+Version: 0.1.0
+Summary: LangChain LLM agents built on top of tokens-lab.
+Author-email: Mohamed Moslemani <moslemanomohamed@gmail.com>, Youssef Moussallem <youssefaamoussallem@hotmail.com>
+License-Expression: MIT
+Keywords: llm,agents,langchain,langgraph
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: tokens-lab>=0.5.0
+Requires-Dist: langgraph>=0.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"

agents_lab-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agents-lab"
+version = "0.1.0"
+description = "LangChain LLM agents built on top of tokens-lab."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+
+authors = [
+  { name = "Mohamed Moslemani", email = "moslemanomohamed@gmail.com" },
+  { name = "Youssef Moussallem", email = "youssefaamoussallem@hotmail.com" }
+]
+
+keywords = ["llm", "agents", "langchain", "langgraph"]
+
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+  "Operating System :: OS Independent",
+]
+
+dependencies = [
+  "tokens-lab>=0.5.0",
+  "langgraph>=0.2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "pytest-cov>=4.0",
+  "ruff>=0.4.0",
+  "mypy>=1.8",
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["llm_agents*"]
+namespaces = false
+
+[tool.setuptools.package-data]
+"llm_agents" = ["py.typed"]

agents_lab-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agents_lab-0.1.0/src/agents_lab.egg-info/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: agents-lab
+Version: 0.1.0
+Summary: LangChain LLM agents built on top of tokens-lab.
+Author-email: Mohamed Moslemani <moslemanomohamed@gmail.com>, Youssef Moussallem <youssefaamoussallem@hotmail.com>
+License-Expression: MIT
+Keywords: llm,agents,langchain,langgraph
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: tokens-lab>=0.5.0
+Requires-Dist: langgraph>=0.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"

agents_lab-0.1.0/src/agents_lab.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+pyproject.toml
+src/agents_lab.egg-info/PKG-INFO
+src/agents_lab.egg-info/SOURCES.txt
+src/agents_lab.egg-info/dependency_links.txt
+src/agents_lab.egg-info/requires.txt
+src/agents_lab.egg-info/top_level.txt
+src/llm_agents/__init__.py
+src/llm_agents/invoice_parsing_agent.py
+src/llm_agents/name_consolidator.py
+src/llm_agents/name_mapper.py
+src/llm_agents/name_mapper_ml.py
+src/llm_agents/py.typed
+src/llm_agents/resume_slide_identifier.py
+src/llm_agents/resume_structurer.py
+src/llm_agents/resumes_consolidator.py
+src/llm_agents/states.py

agents_lab-0.1.0/src/agents_lab.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agents_lab-0.1.0/src/agents_lab.egg-info/requires.txt

@@ -0,0 +1,8 @@
+tokens-lab>=0.5.0
+langgraph>=0.2.0
+
+[dev]
+pytest>=7.0
+pytest-cov>=4.0
+ruff>=0.4.0
+mypy>=1.8

agents_lab-0.1.0/src/agents_lab.egg-info/top_level.txt

@@ -0,0 +1 @@
+llm_agents

agents_lab-0.1.0/src/llm_agents/__init__.py

@@ -0,0 +1,58 @@
+"""LLM Agents — LangChain/LangGraph agents built on tokens-lab."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+
+def __getattr__(name: str):
+    """Lazy-load public symbols on first access."""
+    _imports: dict[str, tuple[str, str]] = {
+        # agents
+        "InvoiceParsingAgent": (".invoice_parsing_agent", "InvoiceParsingAgent"),
+        "ResumeSlideIdentifier": (".resume_slide_identifier", "ResumeSlideIdentifier"),
+        "ResumeStructurer": (".resume_structurer", "ResumeStructurer"),
+        "ResumesConsolidator": (".resumes_consolidator", "ResumesConsolidator"),
+        "NameMapper": (".name_mapper", "NameMapper"),
+        "NameConsolidator": (".name_consolidator", "NameConsolidator"),
+        "auto_match_names": (".name_mapper_ml", "auto_match_names"),
+        "extract_name": (".name_mapper_ml", "extract_name"),
+        # states
+        "BaseState": (".states", "BaseState"),
+        "InvoiceState": (".states", "InvoiceState"),
+        "NameMatchingState": (".states", "NameMatchingState"),
+        "ResumeState": (".states", "ResumeState"),
+        "CVParserState": (".states", "CVParserState"),
+        "ConsolidateState": (".states", "ConsolidateState"),
+        "DedupState": (".states", "DedupState"),
+    }
+
+    if name in _imports:
+        module_path, attr = _imports[name]
+        import importlib
+        mod = importlib.import_module(module_path, __name__)
+        return getattr(mod, attr)
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "__version__",
+    # agents
+    "InvoiceParsingAgent",
+    "ResumeSlideIdentifier",
+    "ResumeStructurer",
+    "ResumesConsolidator",
+    "NameMapper",
+    "NameConsolidator",
+    "auto_match_names",
+    "extract_name",
+    # states
+    "BaseState",
+    "InvoiceState",
+    "NameMatchingState",
+    "ResumeState",
+    "CVParserState",
+    "ConsolidateState",
+    "DedupState",
+]

agents_lab-0.1.0/src/llm_agents/invoice_parsing_agent.py

@@ -0,0 +1,284 @@
+"""Invoice processing agent using LangGraph.
+
+Handles multi-step processing of invoices from PDFs and text files.
+Goes through: load document → clean text → extract with LLM → parse JSON → validate.
+Retries automatically when errors happen.
+
+Steps:
+    - Load document (text + PDF images)
+    - Extract invoice data using LLM
+    - Parse the output into JSON
+    - Validate the data
+    - Retry if there are errors (up to configured max)
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from typing import Any, Callable
+
+from langgraph.graph import END
+
+from llm_lab.agent import Agent, LLMClient
+from llm_lab.filetextio import load_text, Pdf
+from llm_lab.utils import _clean_llm_json_output
+from llm_lab.preprocessing import normalize_text
+
+from .states import InvoiceState
+
+_pdf_image_lock = threading.Lock()
+_BASE_SYSTEM_RULES = """
+==================================================
+OUTPUT FORMAT (STRICT — ENFORCED BY AGENT)
+==================================================
+- Output ONE JSON object ONLY
+- NO markdown, NO code fences, NO comments, NO explanations
+- Use null for missing or uncertain values
+- Keys MUST match the target field names EXACTLY
+- Extract VALUES ONLY (no labels, no prefixes)
+
+==================================================
+VALUE FORMATTING RULES (ENFORCED BY AGENT)
+==================================================
+- Monetary values: number only (no currency symbols, no words)
+- Preserve original numeric formatting (commas/decimals)
+- If a value is not explicitly printed → null
+""".strip()
+
+class InvoiceParsingAgent(Agent):
+    """Agent for invoice extraction and validation.
+
+    Workflow: load → clean → extract → parse → validate → retry if needed.
+
+    The agent enforces base output format rules (JSON, null handling) automatically.
+    Your system_prompt should contain domain-specific extraction rules only — the
+    base rules are prepended by the agent.
+
+    Args:
+        client: LLMClient instance for LLM calls.
+        devsettings: Retry limits and timeouts.
+        logger: Logger instance.
+        error_handler: Class with _ensure_defaults(state) and _set_error(msg, exc) static methods.
+        validate_fn: Callable(parsed_json, state) -> (is_valid, validated, updates).
+        arabic_instruction: String appended to user prompts for Arabic text handling.
+        system_prompt: Domain-specific extraction rules (output format rules are added automatically).
+    """
+
+    def __init__(
+        self,
+        client: LLMClient,
+        devsettings: Any,
+        logger: Any,
+        error_handler: Any,
+        validate_fn: Callable,
+        arabic_instruction: str,
+        system_prompt: str,
+    ) -> None:
+        super().__init__(InvoiceState)
+
+        self._client = client
+        self.devsettings = devsettings
+        self._logger = logger
+        self._error_handler = error_handler
+        self._validate_fn = validate_fn
+        self._arabic_instruction = arabic_instruction
+        self._system_prompt = f"{_BASE_SYSTEM_RULES}\n\n{system_prompt}"
+        self.setup_graph()
+    
+    def setup_graph(self) -> None:
+        self.add_node("ingest", self.node_ingest)
+        self.add_node("preprocess", self.node_preprocess)
+        self.add_node("extract", self.node_extract)
+        self.add_node("parse_json", self.node_parse_json)
+        self.add_node("validate", self.node_validate)
+        self.add_node("increment_retry", self.node_increment_retry)
+
+        self.set_entry_point("ingest")
+
+        self._guarded("ingest", "preprocess")
+        self._guarded("preprocess", "extract")
+        self._guarded("extract", "parse_json")
+        self._guarded("parse_json", "validate")
+        self._retry_edge("validate", "increment_retry", self.should_retry)
+        self._guarded("increment_retry", "extract")
+
+        self.compile()
+
+        self._logger.info(f"InvoiceAgent initialized with model: {self._client.model_name}")
+
+    def node_ingest(self, state: InvoiceState) -> InvoiceState:
+        updates = self._error_handler._ensure_defaults(state)
+        path = state.get("path")
+        self._logger.info(f"Starting document ingestion: {path}")
+
+        if not path:
+            return {**updates, "stop_agent": True, "error": "Missing document path"}
+
+        raw_text = ""
+        pdf_images = []
+        try:
+            raw_text = load_text(path) or ""
+        except Exception as exc:
+            err_update = self._error_handler._set_error("Could not read text content", exc)
+            updates.update(err_update)
+            raw_text = ""
+
+        try:
+            with _pdf_image_lock:
+                extracted = Pdf.pdf_to_base64_images(path, max_pages=self.devsettings.max_pages)
+            pdf_images = extracted or []
+            if not pdf_images:
+                self._logger.warning(f"No images extracted from PDF: {path}")
+        except Exception as exc:
+            self._logger.error(f"PDF image extraction failed for {path}: {str(exc)}", exc_info=True)
+            err_update = self._error_handler._set_error("Could not process PDF content", exc)
+            updates.update(err_update)
+            pdf_images = []
+
+        has_images_content = any(isinstance(img, str) and img.strip() for img in pdf_images)
+        if not (raw_text.strip() or has_images_content):
+            self._logger.error("No content extracted from document")
+            return {**updates, "stop_agent": True, "error": updates.get("error", state.get("error", ""))}
+
+        self._logger.info(f"Document ingested successfully: {len(raw_text)} chars, {len(pdf_images)} images")
+        return {**updates, "raw_text": raw_text, "pdf_images": pdf_images, "retry_count": 0, "error": "", "last_error": updates.get("error", state.get("error", ""))}
+
+    def node_preprocess(self, state: InvoiceState) -> InvoiceState:
+        raw_text = state.get("raw_text", "")
+
+        try:
+            clean_text = normalize_text(raw_text)
+        except Exception as exc:
+            return {**state, "stop_agent": True, "error": f"Text normalization failed: {str(exc)}"}
+
+        return {"clean_text": clean_text, "error": "", "last_error": state.get("error", "")}
+
+    def node_extract(self, state: InvoiceState) -> InvoiceState:
+        try:
+            user_prompt = state.get("user_prompt", "")
+            feedback = state.get("validation_feedback", "")
+            pdf_images = state.get("pdf_images", [])
+            clean_text = state.get("clean_text", "")
+
+            if feedback:
+                user_prompt = (
+                    f"{user_prompt}{self._arabic_instruction}\n"
+                    f"PREVIOUS EXTRACTION HAD ISSUES:\n{feedback}\n\n"
+                    "Please re-extract and fix the validation issues above while strictly following the Arabic text preservation rules."
+                )
+            else:
+                user_prompt = f"{user_prompt}{self._arabic_instruction}"
+
+            # Build messages with optional image support
+            messages = [{"role": "system", "content": self._system_prompt}]
+
+            if pdf_images:
+                content_items = [
+                    {
+                        "type": "input_text",
+                        "text": (
+                            user_prompt
+                            + ", analyze the invoice images and extracted text below. "
+                            "Use the visual layout across pages, tables, and formatting to accurately identify and extract fields.\n\n"
+                            "Extracted text:\n" + clean_text
+                        ),
+                    }
+                ]
+                for img_b64 in pdf_images:
+                    content_items.append({
+                        "type": "input_image",
+                        "image_url": f"data:image/jpeg;base64,{img_b64}",
+                    })
+                messages.append({"role": "user", "content": content_items})
+            else:
+                messages.append({
+                    "role": "user",
+                    "content": user_prompt + ", find the current invoice text below:\n\n" + clean_text,
+                })
+
+            self._logger.info("Calling Invoice extraction: %s", self._client.model_name)
+            result_content = self._client.generate_response(messages)
+            self._logger.info("Invoice extraction response received: %d chars", len(result_content) if result_content else 0)
+
+            if result_content is None:
+                self._logger.error("LLM extraction returned None")
+                return {"llm_output": "", "error": "Could not extract invoice data."}
+
+            self._logger.info(f"LLM extraction successful: {len(result_content)} chars")
+
+            return {"llm_output": result_content, "error": "", "last_error": state.get("error", "")}
+
+        except Exception as exc:
+            return {"llm_output": "", "error": f"Failed to send LLM request: {str(exc)}", "last_error": state.get("error", "")}
+
+    def node_parse_json(self, state: InvoiceState) -> InvoiceState:
+        llm_output = state.get("llm_output") or ""
+
+        try:
+            cleaned_output = _clean_llm_json_output(llm_output, self._logger)
+            parsed = json.loads(cleaned_output)
+            return {"parsed_json": parsed if isinstance(parsed, dict) else {"_root": parsed}, "error": "", "last_error": state.get("error", "")}
+        except json.JSONDecodeError as e:
+            return {"parsed_json": {}, "error": f"Invalid JSON: {str(e)}", "last_error": state.get("error", "")}
+        except Exception as e:
+            return {"parsed_json": {}, "error": f"Failed to parse JSON: {str(e)}", "last_error": state.get("error", "")}
+
+    def node_validate(self, state: InvoiceState) -> InvoiceState:
+        parsed = state.get("parsed_json", {})
+        try:
+            is_valid, validated, v_updates = self._validate_fn(parsed, state)
+            self._logger.info(f"Validation completed: is_valid={is_valid}")
+        except Exception as exc:
+            self._logger.error(f"Validation failed: {str(exc)}", exc_info=True)
+            return {**self._error_handler._set_error("validate/validate_invoice", exc), "validated_data": {}, "extract": {}}
+
+        validation_info = (validated or {}).get("_validation", {})
+        errors = validation_info.get("errors", []) or []
+        warnings = validation_info.get("warnings", []) or []
+        feedback_parts = []
+        if errors:
+            feedback_parts.append("ERRORS:\n" + "\n".join(f"- {e}" for e in errors))
+        if warnings:
+            feedback_parts.append("WARNINGS:\n" + "\n".join(f"- {w}" for w in warnings))
+
+        feedback = "\n\n".join(feedback_parts) if feedback_parts else ""
+
+        if not is_valid and not errors:
+            feedback = feedback or "Validation marked invalid but no explicit errors were returned."
+
+        feedback_safe = feedback.encode('ascii', errors='replace').decode('ascii')
+        self._logger.info(f"Validation feedback generated ({len(errors)} errors, {len(warnings)} warnings): {feedback_safe}")
+        return {
+            "validated_data": validated or {},
+            "extract": validated or {},
+            "validation_feedback": feedback,
+            "error": (v_updates.get("error") if isinstance(v_updates, dict) else None) or "",
+            "last_error": state.get("error", ""),
+        }
+
+    def should_retry(self, state: InvoiceState) -> str:
+        if state.get("stop_agent"):
+            self._logger.info("Agent stopped by stop_agent flag")
+            return "end"
+
+        retry_count = int(state.get("retry_count", 0) or 0)
+
+        if retry_count >= self.devsettings.max_retries:
+            self._logger.warning(f"Max retries reached ({retry_count}/{self.devsettings.max_retries})")
+            return "end"
+
+        if state.get("error"):
+            self._logger.info(f"Retrying extraction (attempt {retry_count + 1}/{self.devsettings.max_retries})")
+            return "retry"
+
+        validation_info = state.get("validated_data", {}).get("_validation", {})
+        errors = validation_info.get("errors", []) or []
+
+        if errors:
+            return "retry"
+
+        return "end"
+
+    def node_increment_retry(self, state: InvoiceState) -> InvoiceState:
+        return {"retry_count": state.get("retry_count", 0) + 1}