agent-shared-core 0.1.0__tar.gz

agent_shared_core-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: agent-shared-core
+Version: 0.1.0
+Summary: Shared Compass core and marketing domain logic for agents
+Requires-Python: >=3.11
+Requires-Dist: google-cloud-firestore
+Requires-Dist: google-cloud-storage
+Requires-Dist: google-auth
+Requires-Dist: trafilatura

agent_shared_core-0.1.0/__init__.py

@@ -0,0 +1,3 @@
+# agent_shared_core: shared Python library for the Compass Agent Framework.
+# Not an ADK agent (no root_agent). Provides core infra and domain logic.
+

agent_shared_core-0.1.0/agent_shared_core.egg-info/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: agent-shared-core
+Version: 0.1.0
+Summary: Shared Compass core and marketing domain logic for agents
+Requires-Python: >=3.11
+Requires-Dist: google-cloud-firestore
+Requires-Dist: google-cloud-storage
+Requires-Dist: google-auth
+Requires-Dist: trafilatura

agent_shared_core-0.1.0/agent_shared_core.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+__init__.py
+pyproject.toml
+./__init__.py
+agent_shared_core.egg-info/PKG-INFO
+agent_shared_core.egg-info/SOURCES.txt
+agent_shared_core.egg-info/dependency_links.txt
+agent_shared_core.egg-info/requires.txt
+agent_shared_core.egg-info/top_level.txt
+core/__init__.py
+core/auth.py
+core/checkpoints.py
+core/config.py
+core/content.py
+core/firestore.py
+core/image_gen.py
+core/prompts.py
+core/wallet.py
+mktg/__init__.py
+mktg/brands.py
+mktg/compositions.py
+mktg/platform_specs.py
+mktg/themes.py

agent_shared_core-0.1.0/agent_shared_core.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agent_shared_core-0.1.0/agent_shared_core.egg-info/requires.txt

@@ -0,0 +1,4 @@
+google-cloud-firestore
+google-cloud-storage
+google-auth
+trafilatura

agent_shared_core-0.1.0/agent_shared_core.egg-info/top_level.txt

@@ -0,0 +1 @@
+agent_shared_core

agent_shared_core-0.1.0/core/__init__.py

@@ -0,0 +1,2 @@
+# agent_shared_core.core: universal infrastructure (firestore, auth, wallet, config, prompts)
+

agent_shared_core-0.1.0/core/auth.py

@@ -0,0 +1,79 @@
+"""Role resolution via Google Directory API with TTL cache.
+
+Usage:
+    from agent_shared_core.core.auth import resolve_role
+    role = resolve_role("user@company.com", "mktg")  # returns "admin" or "exec"
+"""
+
+import logging
+import os
+import time
+from typing import Dict, Tuple
+
+logger = logging.getLogger(__name__)
+
+# Cache: key = (email, dept), value = (role, timestamp)
+_role_cache: Dict[Tuple[str, str], Tuple[str, float]] = {}
+
+# Cache TTL in seconds (5 minutes)
+_CACHE_TTL = 300
+
+# Read domain from environment. Set per customer deployment.
+# Default to company.com for the dev sandbox (concretio-compass-sb).
+_GROUP_DOMAIN = os.environ.get("COMPASS_GROUP_DOMAIN", "company.com")
+
+
+def _check_group_membership(email: str, group_email: str) -> bool:
+    """Check if email is a member of the given Google Group.
+
+    Uses the Google Admin SDK Directory API.
+    """
+    from googleapiclient.discovery import build
+    import google.auth
+
+    credentials, _ = google.auth.default(
+        scopes=["https://www.googleapis.com/auth/admin.directory.group.member.readonly"]
+    )
+    service = build("admin", "directory_v1", credentials=credentials)
+
+    try:
+        result = service.members().hasMember(
+            groupKey=group_email, memberKey=email
+        ).execute()
+        return result.get("isMember", False)
+    except Exception:
+        return False
+
+
+def resolve_role(email: str, dept: str) -> str:
+    """Resolve user role based on Google Group membership.
+
+    Returns "admin" if the user is in {dept}-admins@company.com,
+    otherwise returns "exec". On API failure, defaults to "exec" (safe default).
+
+    Results are cached for 5 minutes per (email, dept) pair.
+    """
+    cache_key = (email, dept)
+
+    # Check cache
+    if cache_key in _role_cache:
+        cached_role, cached_time = _role_cache[cache_key]
+        if time.time() - cached_time < _CACHE_TTL:
+            return cached_role
+
+    # Query Directory API
+    try:
+        admin_group = f"{dept}-admins@{_GROUP_DOMAIN}"
+        is_admin = _check_group_membership(email, admin_group)
+        role = "admin" if is_admin else "exec"
+    except Exception:
+        logger.warning(
+            "Directory API failure for %s in dept %s, defaulting to exec",
+            email, dept,
+        )
+        role = "exec"
+
+    # Cache the result
+    _role_cache[cache_key] = (role, time.time())
+    return role
+

agent_shared_core-0.1.0/core/checkpoints.py

@@ -0,0 +1,58 @@
+"""Workflow checkpoints via ADK session state (no external deps).
+
+Agents use checkpoints to persist intermediate progress within a session.
+Data is stored in tool_context.state["checkpoint"] as a flat dict.
+
+Usage:
+    from agent_shared_core.core.checkpoints import save_checkpoint, read_checkpoint
+
+    # Save progress after a step completes
+    save_checkpoint(tool_context, {"step": "theme_selected", "theme_id": "abc123"})
+
+    # Read current checkpoint (returns None if no checkpoint exists)
+    cp = read_checkpoint(tool_context)
+    if cp:
+        print(cp["step"])  # "theme_selected"
+
+    # Subsequent saves merge into the existing checkpoint
+    save_checkpoint(tool_context, {"step": "preview_generated", "image_url": "https://..."})
+    # checkpoint now has: step, theme_id, image_url, last_updated
+"""
+
+import logging
+from datetime import datetime, timezone
+
+logger = logging.getLogger(__name__)
+
+
+def save_checkpoint(tool_context, data: dict) -> None:
+    """Merge data into the session checkpoint and set last_updated.
+
+    Reads the existing checkpoint from tool_context.state, merges new
+    keys (overwriting on conflict), stamps the current UTC time, and
+    writes back.
+
+    Args:
+        tool_context: ADK ToolContext with a .state dict.
+        data: key-value pairs to merge into the checkpoint.
+    """
+    checkpoint = tool_context.state.get("checkpoint", {})
+    checkpoint.update(data)
+    checkpoint["last_updated"] = datetime.now(timezone.utc).isoformat()
+    tool_context.state["checkpoint"] = checkpoint
+
+    step = data.get("step", "unknown")
+    logger.info("Checkpoint saved: step=%s", step)
+
+
+def read_checkpoint(tool_context) -> dict | None:
+    """Read the current checkpoint from session state.
+
+    Args:
+        tool_context: ADK ToolContext with a .state dict.
+
+    Returns:
+        The checkpoint dict, or None if no checkpoint exists.
+    """
+    return tool_context.state.get("checkpoint") or None
+

agent_shared_core-0.1.0/core/config.py

@@ -0,0 +1,37 @@
+"""Runtime configuration from Firestore /config/{agent_name}.
+
+Usage:
+    from agent_shared_core.core.config import get_config
+
+    config = get_config("mktg_banner_generator")
+    preview_count = config.get("preview_count", 3)
+    model_id = config.get("model_id", "imagen-4-fast")
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def get_config(agent_name: str) -> dict:
+    """Read agent configuration from Firestore /config/{agent_name}.
+
+    Returns the document as a dict. Returns empty dict if the document
+    does not exist or on Firestore failure. Callers use the
+    .get(key, default) pattern to handle missing keys.
+    """
+    from agent_shared_core.core.firestore import get_client
+
+    try:
+        doc = get_client().collection("config").document(agent_name).get()
+        if doc.exists:
+            return doc.to_dict()
+        return {}
+    except Exception:
+        logger.warning(
+            "Failed to read config for %s, returning empty dict",
+            agent_name,
+            exc_info=True,
+        )
+        return {}
+

agent_shared_core-0.1.0/core/content.py

@@ -0,0 +1,215 @@
+"""Content extraction and context analysis for agent workflows.
+
+Usage:
+    from agent_shared_core.core.content import fetch_content, extract_content_context
+
+    # Fetch from URL
+    result = fetch_content("https://example.com/article")
+    # => {"source": "https://...", "content": "...", "content_type": "url", "success": True}
+
+    # Pass raw text
+    result = fetch_content("Some plain text content here.")
+    # => {"source": "Some plain...", "content": "Some plain...", "content_type": "text", "success": True}
+
+    # Pass markdown
+    result = fetch_content("# Heading\n\n**Bold** text with [links](url)")
+    # => {"source": "# Heading...", "content": "Heading\nBold text with links", "content_type": "markdown", "success": True}
+
+    # Extract structured context via Gemini Flash
+    context = extract_content_context("Article text here...")
+    # => {"title": "...", "vertical": "...", "key_themes": [...], ...}
+"""
+
+import json
+import logging
+import os
+import re
+
+import trafilatura
+
+logger = logging.getLogger(__name__)
+
+_MAX_CONTENT_LENGTH = 15_000
+
+_EXTRACTION_PROMPT = """Extract structured information from the following content.
+Return ONLY valid JSON with these keys:
+- title (string): the main title or topic
+- vertical (string): the industry or domain vertical
+- key_themes (list of strings): 3-5 main themes
+- mood (string): overall tone or mood
+- visual_cues (list of strings): 2-4 visual elements suggested by the content
+- color_hints (list of strings): 2-4 colors associated with the content's mood or vertical
+- summary (string): 2-3 sentence summary
+
+Content:
+{content}
+"""
+
+
+def fetch_content(source: str) -> dict:
+    """Fetch and normalize content from a URL, raw text, or markdown.
+
+    URLs are fetched via trafilatura. Markdown is stripped of formatting.
+    All content is truncated to 15,000 chars.
+
+    Args:
+        source: a URL (http/https), markdown string, or plain text.
+
+    Returns:
+        Dict with keys: source, content, content_type, success, and error (on failure).
+    """
+    if source.startswith("http://") or source.startswith("https://"):
+        return _fetch_url(source)
+
+    if _looks_like_markdown(source):
+        text = _strip_markdown(source)[:_MAX_CONTENT_LENGTH]
+        return {"source": source, "content": text, "content_type": "markdown", "success": True}
+
+    text = source[:_MAX_CONTENT_LENGTH]
+    return {"source": source, "content": text, "content_type": "text", "success": True}
+
+
+def extract_content_context(text: str) -> dict:
+    """Extract structured context from text using Gemini 2.0 Flash.
+
+    Calls the model with a structured extraction prompt and parses the
+    JSON response. Logs cost via agent_shared_core.core.wallet.log_cost().
+
+    Args:
+        text: the content to analyze.
+
+    Returns:
+        Dict with title, vertical, key_themes, mood, visual_cues, color_hints, summary.
+        On failure, returns {"error": "..."}.
+    """
+    from google import genai
+
+    project = os.environ.get("GOOGLE_CLOUD_PROJECT", "concretio-compass-sb")
+    location = os.environ.get("GOOGLE_CLOUD_LOCATION", "us-central1")
+
+    try:
+        client = genai.Client(
+            vertexai=True,
+            project=project,
+            location=location,
+        )
+
+        prompt = _EXTRACTION_PROMPT.format(content=text[:_MAX_CONTENT_LENGTH])
+        response = client.models.generate_content(
+            model="gemini-2.0-flash",
+            contents=prompt,
+        )
+
+        raw = response.text.strip()
+        # Strip markdown code fences if the model wraps its output
+        if raw.startswith("```"):
+            raw = re.sub(r"^```(?:json)?\s*", "", raw)
+            raw = re.sub(r"\s*```$", "", raw)
+
+        result = json.loads(raw)
+
+        # Log cost estimate
+        from agent_shared_core.core.wallet import log_cost
+        log_cost(
+            agent="content_extraction",
+            user_email="system",
+            model="gemini-2.0-flash",
+            cost=0.001,
+            phase="extract_context",
+        )
+
+        logger.info("Content context extracted: title=%s", result.get("title", "unknown"))
+        return result
+
+    except json.JSONDecodeError as exc:
+        logger.error("Failed to parse Gemini response as JSON: %s", exc)
+        return {"error": f"JSON parse error: {exc}"}
+    except Exception as exc:
+        logger.error("Content context extraction failed: %s", exc, exc_info=True)
+        return {"error": str(exc)}
+
+
+# --- Internal helpers ---
+
+
+def _fetch_url(url: str) -> dict:
+    """Download and extract article text from a URL via trafilatura."""
+    try:
+        downloaded = trafilatura.fetch_url(url)
+        if downloaded is None:
+            return {
+                "source": url,
+                "content": "",
+                "content_type": "url",
+                "success": False,
+                "error": f"Could not fetch URL: {url}",
+            }
+
+        text = trafilatura.extract(downloaded)
+        if text is None:
+            return {
+                "source": url,
+                "content": "",
+                "content_type": "url",
+                "success": False,
+                "error": f"Could not extract content from: {url}",
+            }
+
+        truncated = text[:_MAX_CONTENT_LENGTH]
+        return {
+            "source": url,
+            "content": truncated,
+            "content_type": "url",
+            "success": True,
+        }
+    except Exception as exc:
+        logger.error("URL fetch failed for %s: %s", url, exc)
+        return {
+            "source": url,
+            "content": "",
+            "content_type": "url",
+            "success": False,
+            "error": f"Extraction failed: {exc}",
+        }
+
+
+def _looks_like_markdown(text: str) -> bool:
+    """Detect if text contains common markdown patterns."""
+    md_patterns = [
+        r"^#{1,6}\s",       # headings
+        r"\*\*.+\*\*",      # bold
+        r"\[.+\]\(.+\)",    # links
+        r"^[-*]\s",          # unordered lists
+        r"^\d+\.\s",        # ordered lists
+        r"^>\s",             # blockquotes
+        r"```",              # code blocks
+    ]
+    for pattern in md_patterns:
+        if re.search(pattern, text, re.MULTILINE):
+            return True
+    return False
+
+
+def _strip_markdown(text: str) -> str:
+    """Remove common markdown formatting, returning plain text."""
+    # Remove code blocks
+    text = re.sub(r"```[\s\S]*?```", "", text)
+    # Remove inline code
+    text = re.sub(r"`([^`]+)`", r"\1", text)
+    # Remove images
+    text = re.sub(r"!\[([^\]]*)\]\([^)]+\)", r"\1", text)
+    # Remove links, keep text
+    text = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", text)
+    # Remove headings markers
+    text = re.sub(r"^#{1,6}\s+", "", text, flags=re.MULTILINE)
+    # Remove bold/italic markers
+    text = re.sub(r"\*{1,3}([^*]+)\*{1,3}", r"\1", text)
+    text = re.sub(r"_{1,3}([^_]+)_{1,3}", r"\1", text)
+    # Remove blockquote markers
+    text = re.sub(r"^>\s?", "", text, flags=re.MULTILINE)
+    # Remove horizontal rules
+    text = re.sub(r"^[-*_]{3,}\s*$", "", text, flags=re.MULTILINE)
+    # Collapse multiple blank lines
+    text = re.sub(r"\n{3,}", "\n\n", text)
+    return text.strip()
+

agent_shared_core-0.1.0/core/firestore.py

@@ -0,0 +1,31 @@
+"""Singleton Firestore client for the Compass Agent Framework.
+
+Usage:
+    from agent_shared_core.core.firestore import get_client
+    db = get_client()
+    doc = db.collection("brands").document("abc").get()
+"""
+
+import logging
+import os
+
+from google.cloud import firestore
+
+logger = logging.getLogger(__name__)
+
+_client = None
+
+
+def get_client() -> firestore.Client:
+    """Return a lazy-initialized singleton Firestore client.
+
+    Uses GOOGLE_CLOUD_PROJECT from the environment, defaulting to
+    concretio-compass-sb (the sandbox project).
+    """
+    global _client
+    if _client is None:
+        project = os.environ.get("GOOGLE_CLOUD_PROJECT", "concretio-compass-sb")
+        _client = firestore.Client(project=project)
+        logger.info("Firestore client initialized for project: %s", project)
+    return _client
+

agent_shared_core-0.1.0/core/image_gen.py

@@ -0,0 +1,183 @@
+"""Image generation and upscaling via Vertex AI (Imagen 4 + Gemini 3 Pro).
+
+Usage:
+    from agent_shared_core.core.image_gen import generate_images, upscale_image
+
+    # Generate preview images
+    results = generate_images("a glass panel banner...", resolution="LinkedIn post", count=3)
+    # => [{"image_bytes": b"...", "aspect_ratio": "16:9"}, ...]
+
+    # Upscale from bytes
+    upscaled = upscale_image(source_bytes, target_size="2K")
+    # => b"..." (upscaled image bytes)
+
+GCS upload is optional and separate. For local dev, tools return base64
+and save as ADK artifacts. For production, a Cloud Run wrapper can handle
+GCS upload via this same module.
+"""
+
+import base64
+import logging
+import os
+
+from google import genai
+from google.genai import types
+
+logger = logging.getLogger(__name__)
+
+# --- Model IDs ---
+
+GENERATE_MODEL_ID = "imagen-4.0-fast-generate-001"
+UPSCALE_MODEL_ID = "gemini-3.0-pro-image-generate-001"
+
+# --- Resolution table ---
+
+RESOLUTION_TABLE: dict[str, tuple[int, int]] = {
+    "LinkedIn post": (1200, 628),
+    "LinkedIn banner": (1584, 396),
+    "Twitter/X header": (1500, 500),
+    "Twitter/X post": (1200, 675),
+    "Facebook cover": (851, 315),
+    "Facebook post": (1200, 630),
+    "Instagram square": (1080, 1080),
+    "Instagram story": (1080, 1920),
+    "YouTube thumbnail": (1280, 720),
+    "YouTube banner": (2560, 1440),
+    "Blog universal": (1200, 628),
+    "Blog OG social": (1200, 630),
+    "WordPress featured image": (1200, 628),
+    "Medium header": (1400, 788),
+    "Presentation slide 16:9": (1920, 1080),
+    "Presentation slide 4:3": (1440, 1080),
+}
+
+DEFAULT_RESOLUTION = (1200, 628)
+
+# --- Aspect ratio mapping for Imagen 4 ---
+
+SUPPORTED_ASPECT_RATIOS = ["1:1", "9:16", "16:9", "3:4", "4:3"]
+
+_ASPECT_RATIO_VALUES = {
+    "1:1": 1.0,
+    "9:16": 9 / 16,
+    "16:9": 16 / 9,
+    "3:4": 3 / 4,
+    "4:3": 4 / 3,
+}
+
+# --- Upscale target dimensions ---
+
+UPSCALE_TARGETS = {
+    "2K": (2048, 2048),
+    "4K": (4096, 4096),
+}
+
+
+def _get_client() -> genai.Client:
+    """Create a google-genai client configured for Vertex AI."""
+    project = os.environ.get("GOOGLE_CLOUD_PROJECT", "concretio-compass-sb")
+    location = os.environ.get("GOOGLE_CLOUD_LOCATION", "us-central1")
+    return genai.Client(vertexai=True, project=project, location=location)
+
+
+def _closest_aspect_ratio(width: int, height: int) -> str:
+    """Map width/height to the nearest supported Imagen 4 aspect ratio."""
+    target = width / height
+    return min(
+        SUPPORTED_ASPECT_RATIOS,
+        key=lambda r: abs(_ASPECT_RATIO_VALUES[r] - target),
+    )
+
+
+def generate_images(
+    prompt: str,
+    resolution: str = "LinkedIn post",
+    count: int = 1,
+) -> list[dict]:
+    """Generate images using Imagen 4 Fast via Vertex AI.
+
+    Args:
+        prompt: The image generation prompt.
+        resolution: Platform resolution key (e.g. "LinkedIn post").
+        count: Number of images to generate (1-4).
+
+    Returns:
+        List of dicts, each with "image_bytes" (raw bytes) and "image_b64"
+        (base64-encoded string for ADK artifact display).
+
+    Raises:
+        Exception on API errors (safety rejection, quota, etc.).
+    """
+    width, height = RESOLUTION_TABLE.get(resolution, DEFAULT_RESOLUTION)
+    aspect_ratio = _closest_aspect_ratio(width, height)
+
+    client = _get_client()
+    response = client.models.generate_images(
+        model=GENERATE_MODEL_ID,
+        prompt=prompt,
+        config=types.GenerateImagesConfig(
+            number_of_images=count,
+            aspect_ratio=aspect_ratio,
+            output_mime_type="image/jpeg",
+            safety_filter_level="BLOCK_MEDIUM_AND_ABOVE",
+            person_generation="ALLOW_ADULT",
+        ),
+    )
+
+    results = []
+    for generated_image in response.generated_images:
+        img_bytes = generated_image.image.image_bytes
+        results.append({
+            "image_bytes": img_bytes,
+            "image_b64": base64.b64encode(img_bytes).decode("utf-8"),
+        })
+
+    logger.info(
+        "Generated %d images with %s, resolution=%s, aspect_ratio=%s",
+        len(results), GENERATE_MODEL_ID, resolution, aspect_ratio,
+    )
+    return results
+
+
+def upscale_image(
+    source_bytes: bytes,
+    target_size: str = "2K",
+) -> bytes:
+    """Upscale an image using Gemini 3 Pro Image via Vertex AI.
+
+    Args:
+        source_bytes: Raw bytes of the source image.
+        target_size: Target resolution, "2K" or "4K".
+
+    Returns:
+        Upscaled image bytes (JPEG).
+
+    Raises:
+        ValueError if the response contains no image.
+        Exception on API errors.
+    """
+    target_width, target_height = UPSCALE_TARGETS.get(target_size, UPSCALE_TARGETS["2K"])
+
+    client = _get_client()
+    source_image = types.Part.from_bytes(data=source_bytes, mime_type="image/jpeg")
+
+    response = client.models.generate_content(
+        model=UPSCALE_MODEL_ID,
+        contents=[
+            source_image,
+            f"Upscale this image to {target_width}x{target_height} resolution. "
+            "Preserve all details, colors, and composition exactly. "
+            "Enhance clarity and sharpness without altering the content.",
+        ],
+        config=types.GenerateContentConfig(
+            response_modalities=["IMAGE", "TEXT"],
+        ),
+    )
+
+    for part in response.candidates[0].content.parts:
+        if part.inline_data and part.inline_data.mime_type.startswith("image/"):
+            logger.info("Upscaled image to %s using %s", target_size, UPSCALE_MODEL_ID)
+            return part.inline_data.data
+
+    raise ValueError("Upscale response did not contain an image")
+