Initial commit: Agentic Multiwriter

.env.example

@@ -0,0 +1,23 @@
+# Agentic Multiwriter configuration
+
+# LLM provider:
+# - "ollama"  → uses local Ollama (default, recommended to start)
+# - "openai"  → uses OpenAI Chat models (requires OPENAI_API_KEY)
+AMW_LLM_PROVIDER=ollama
+
+# LLM model name:
+# - For Ollama: e.g. "llama3", "llama3.1", "qwen2.5"
+# - For OpenAI: e.g. "gpt-4o-mini", "gpt-4.1"
+AMW_LLM_MODEL=llama3
+
+# Temperature:
+# - 0.0–0.3: more deterministic
+# - 0.4–0.7: more creative
+AMW_TEMPERATURE=0.4
+
+# Max number of search results to pull from DuckDuckGo.
+AMW_MAX_SEARCH_RESULTS=8
+
+# Required only if AMW_LLM_PROVIDER=openai
+# (Leave blank in example file so you don't commit real keys.)
+OPENAI_API_KEY=

.gitignore

@@ -0,0 +1,51 @@
+# Python bytecode / caches
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+.venv*/
+.env*/
+
+# Build / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.mypy_cache/
+.dmypy.json
+
+# IDE / editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS-specific
+.DS_Store
+Thumbs.db
+
+# Logs
+logs/
+*.log
+
+# Environment and secrets
+.env
+.env.local
+.env.*.local
+
+# Uvicorn / FastAPI temp files (just in case)
+*.pid
+
+# Docker
+*.pid

Dockerfile

@@ -0,0 +1,15 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+ENV PYTHONUNBUFFERED=1
+
+COPY pyproject.toml ./
+RUN pip install --upgrade pip && \
+    pip install -e .
+
+COPY src ./src
+
+EXPOSE 8000
+
+CMD ["uvicorn", "agentic_multiwriter.api.server:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -0,0 +1,93 @@
+# Agentic Multiwriter
+
+A multi-agent **research & writing** system built with **LangGraph**, **LangChain**, and local/remote LLMs.
+
+Pipeline:
+
+1. **Researcher** – web search on a topic
+2. **Aggregator** – cleans & deduplicates snippets
+3. **Writer** – drafts content based on research
+4. **Critic** – improves clarity & completeness
+5. **Formatter** – outputs a final, mode-specific format (blog / research_summary / linkedin_post)
+
+Supports:
+
+- Local LLM via **Ollama** (e.g. `llama3`)
+- Optional OpenAI models (if configured)
+- REST API with FastAPI
+- CLI entrypoint
+
+---
+
+## Quickstart
+
+````bash
+# From repo root
+python -m venv .venv
+source .venv/bin/activate
+
+pip install -e .
+
+# Run CLI
+PYTHONPATH=src python -m agentic_multiwriter.cli.main \
+  --topic "Future of AI agents in healthcare" \
+  --mode blog
+
+# Run API
+PYTHONPATH=src uvicorn agentic_multiwriter.api.server:app --reload
+Example request:
+
+bash
+Copy code
+curl -X POST "http://127.0.0.1:8000/generate" \
+  -H "Content-Type: application/json" \
+  -d '{"topic": "Future of AI agents in healthcare", "mode": "blog"}'
+Configuration
+Environment variables:
+
+AMW_LLM_PROVIDER – "ollama" or "openai" (default: "ollama")
+
+AMW_LLM_MODEL – e.g. "llama3" (default) or "gpt-4o-mini"
+
+AMW_TEMPERATURE – float, default 0.4
+
+OPENAI_API_KEY – required if using openai provider
+
+You can also see example configs in examples/sample_config_local.yaml and examples/sample_config_hybrid.yaml.
+
+Development
+Run tests:
+
+bash
+Copy code
+PYTHONPATH=src pytest -q
+License
+MIT (or whatever you prefer).
+
+bash
+Copy code
+
+---
+
+## `docker-compose.yml`
+
+```yaml
+version: "3.9"
+
+services:
+  api:
+    build: .
+    container_name: agentic-multiwriter-api
+    environment:
+      - AMW_LLM_PROVIDER=${AMW_LLM_PROVIDER:-ollama}
+      - AMW_LLM_MODEL=${AMW_LLM_MODEL:-llama3}
+      - AMW_TEMPERATURE=${AMW_TEMPERATURE:-0.4}
+      - OPENAI_API_KEY=${OPENAI_API_KEY:-}
+    ports:
+      - "8000:8000"
+    command: ["uvicorn", "agentic_multiwriter.api.server:app", "--host", "0.0.0.0", "--port", "8000"]
+    working_dir: /app
+    volumes:
+      - ./src:/app/src
+      - ./examples:/app/examples
+````

app.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import json
+import textwrap
+from typing import List
+
+import gradio as gr
+
+from agentic_multiwriter.state import AgentState, ResearchSnippet
+from agentic_multiwriter.agents import (
+    researcher_node,
+    aggregator_node,
+    writer_node,
+    critic_node,
+    formatter_node,
+)
+from agentic_multiwriter.tools import get_logger
+
+logger = get_logger()
+
+
+def _format_sources(snippets: List[ResearchSnippet]) -> str:
+    if not snippets:
+        return "No web sources were retrieved."
+
+    lines = []
+    for s in snippets:
+        title = s["title"] or s["url"]
+        url = s["url"]
+        snippet = s["snippet"]
+        if url:
+            lines.append(f"- [{title}]({url})\n  \n  > {snippet}")
+        else:
+            lines.append(f"- {title}\n  \n  > {snippet}")
+    return "\n\n".join(lines)
+
+
+def generate(topic: str, mode: str, progress=gr.Progress()):
+    """Gradio callback to run the pipeline step-by-step with progress."""
+    topic = topic.strip()
+    if not topic:
+        return (
+            "Please enter a topic.",
+            "",
+            "",
+            "",
+            "",
+        )
+
+    # Initial state
+    state: AgentState = {
+        "topic": topic,
+        "mode": mode,
+        "research_snippets": [],
+        "outline": [],
+        "draft": "",
+        "revised_draft": "",
+        "final_output": "",
+        "meta": {},
+    }
+
+    # 1. Research
+    progress(0.1, "Researching the web...")
+    logger.info("UI: starting researcher_node")
+    state = researcher_node(state)
+
+    # 2. Aggregate
+    progress(0.25, "Aggregating and cleaning snippets...")
+    logger.info("UI: starting aggregator_node")
+    state = aggregator_node(state)
+
+    # 3. Write draft
+    progress(0.5, "Writing first draft...")
+    logger.info("UI: starting writer_node")
+    state = writer_node(state)
+    initial_draft = state.get("draft", "") or ""
+
+    # 4. Critic / edit
+    progress(0.7, "Reviewing and improving draft...")
+    logger.info("UI: starting critic_node")
+    state = critic_node(state)
+    revised_draft = state.get("revised_draft", "") or initial_draft
+
+    # 5. Format final output
+    progress(0.9, f"Formatting final output as {mode}...")
+    logger.info("UI: starting formatter_node")
+    state = formatter_node(state)
+    final_output = state.get("final_output", "") or revised_draft
+
+    # 6. Prepare outline, meta, sources
+    outline = state.get("outline", []) or []
+    meta = state.get("meta", {}) or {}
+    snippets = state.get("research_snippets", []) or []
+
+    outline_text = "\n".join(f"- {item}" for item in outline)
+    meta_text = json.dumps(meta, indent=2)
+    sources_md = _format_sources(snippets)
+
+    progress(1.0, "Done.")
+    return final_output, initial_draft, revised_draft, sources_md, meta_text
+
+
+def build_interface() -> gr.Blocks:
+    with gr.Blocks(title="Agentic Multiwriter") as demo:
+        gr.Markdown(
+            """
+            # 🧠 Agentic Multiwriter
+
+            Multi-agent research & writing system built with **LangGraph**.
+
+            1. Researches your topic on the web  
+            2. Aggregates and cleans snippets  
+            3. Writes a draft  
+            4. Critiques and improves it  
+            5. Formats it as a blog, research summary, or LinkedIn-style post
+            """
+        )
+
+        with gr.Row():
+            topic_input = gr.Textbox(
+                label="Topic",
+                placeholder="e.g. Future of agentic AI",
+                lines=2,
+            )
+        mode_input = gr.Radio(
+            choices=["blog", "research_summary", "linkedin_post"],
+            value="blog",
+            label="Output mode",
+        )
+        run_button = gr.Button("Generate", variant="primary")
+
+        with gr.Tab("Final Output"):
+            final_output_box = gr.Markdown(label="Final Output")
+
+        with gr.Tab("Initial Draft (Writer)"):
+            initial_draft_box = gr.Markdown(label="Initial Draft")
+
+        with gr.Tab("Revised Draft (Critic)"):
+            revised_draft_box = gr.Markdown(label="Revised Draft")
+
+        with gr.Tab("Sources"):
+            sources_box = gr.Markdown(label="Web Sources Used")
+
+        with gr.Tab("Meta"):
+            meta_box = gr.Textbox(
+                label="Meta (timings, counts, etc.)", lines=10)
+
+        run_button.click(
+            fn=generate,
+            inputs=[topic_input, mode_input],
+            outputs=[
+                final_output_box,
+                initial_draft_box,
+                revised_draft_box,
+                sources_box,
+                meta_box,
+            ],
+        )
+
+        gr.Markdown(
+            textwrap.dedent(
+                """
+                ---
+                ⚠️ **Note**: First run may take longer while the model loads or if you are
+                using a local model. For best performance on Hugging Face Spaces, set
+                `AMW_LLM_PROVIDER=openai` and use a small hosted model (e.g. `gpt-4o-mini`).
+                """
+            )
+        )
+
+    return demo
+
+
+if __name__ == "__main__":
+    demo = build_interface()
+    demo.launch(server_name="0.0.0.0", server_port=7860)

examples/example_runs.md

@@ -0,0 +1,31 @@
+# Example Runs
+
+## Blog mode (local, Ollama llama3)
+
+```bash
+PYTHONPATH=src python -m agentic_multiwriter.cli.main \
+  --topic "Future of AI agents in healthcare" \
+  --mode blog
+Outputs (truncated):
+
+Outline with 4–6 headings
+
+Draft text ~800–1200 words
+
+Final formatted blog with title, intro, body, conclusion
+
+Research summary mode
+bash
+Copy code
+PYTHONPATH=src python -m agentic_multiwriter.cli.main \
+  --topic "Randomized controlled trials using AI in radiology" \
+  --mode research_summary
+Outputs:
+
+Bullet-pointed key findings
+
+Short narrative summary
+
+Suggestions for further reading
+
+```

examples/sample_config_hybrid.yaml

@@ -0,0 +1,5 @@
+llm_provider: "openai"
+llm_model: "gpt-4o-mini"
+temperature: 0.3
+max_search_results: 10
+mode: "research_summary"

examples/sample_config_local.yaml

@@ -0,0 +1,5 @@
+llm_provider: "ollama"
+llm_model: "llama3"
+temperature: 0.4
+max_search_results: 8
+mode: "blog"

pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "agentic-multiwriter"
+version = "0.1.0"
+description = "Multi-agent research & writing system using LangGraph, LangChain, and LLMs."
+authors = [{name = "Your Name"}]
+requires-python = ">=3.10"
+
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.30.0",
+    "pydantic>=2.8.0",
+    "langchain>=0.3.0",
+    "langchain-community>=0.3.0",
+    "langchain-ollama>=0.2.0",
+    "langchain-openai>=0.2.0",
+    "langgraph>=0.2.0",
+    "duckduckgo-search>=6.2.10",
+    "python-dotenv>=1.0.1",
+    "httpx>=0.27.0",
+]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"

requirements.txt

@@ -0,0 +1,12 @@
+fastapi>=0.115.0
+uvicorn[standard]>=0.30.0
+pydantic>=2.8.0
+langchain>=0.3.0
+langchain-community>=0.3.0
+langchain-ollama>=0.2.0
+langchain-openai>=0.2.0
+langgraph>=0.2.0
+ddgs>=1.8.0
+python-dotenv>=1.0.1
+httpx>=0.27.0
+gradio>=5.0.0

scripts/run_cli.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -e
+
+export PYTHONPATH=src:${PYTHONPATH}
+
+python -m agentic_multiwriter.cli.main "$@"

scripts/run_local.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -e
+
+export PYTHONPATH=src:${PYTHONPATH}
+
+uvicorn agentic_multiwriter.api.server:app --reload --host 0.0.0.0 --port 8000

src/agentic_multiwriter/__init__.py

@@ -0,0 +1,10 @@
+"""
+Agentic Multiwriter package.
+
+Multi-agent research & writing pipeline using LangGraph and LLMs.
+"""
+
+from .config import Settings
+from .graph.router import run_pipeline
+
+__all__ = ["Settings", "run_pipeline"]

src/agentic_multiwriter/agents/__init__.py

@@ -0,0 +1,13 @@
+from .researcher import researcher_node
+from .aggregator import aggregator_node
+from .writer import writer_node
+from .critic import critic_node
+from .formatter import formatter_node
+
+__all__ = [
+    "researcher_node",
+    "aggregator_node",
+    "writer_node",
+    "critic_node",
+    "formatter_node",
+]

src/agentic_multiwriter/agents/aggregator.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import time
+from typing import List
+
+from ..state import AgentState, ResearchSnippet
+from ..tools import normalize_snippets, get_logger, log_state_summary
+from ..config import settings
+
+logger = get_logger()
+
+
+def _rank_snippets(snippets: List[ResearchSnippet]) -> List[ResearchSnippet]:
+    """
+    Very simple ranking: prefer snippets that mention the topic more often (if present),
+    otherwise keep original order.
+    """
+    return snippets
+
+
+def aggregator_node(state: AgentState) -> AgentState:
+    start = time.time()
+
+    snippets = state.get("research_snippets", []) or []
+    logger.info("Aggregator: normalizing %d snippets...", len(snippets))
+
+    normalized = normalize_snippets(snippets)
+    ranked = _rank_snippets(normalized)
+
+    # Trim to a maximum number for LLM context
+    max_keep = max(3, settings.max_search_results)
+    trimmed = ranked[:max_keep]
+
+    meta = state.get("meta", {}) or {}
+    meta["aggregator_time_sec"] = round(time.time() - start, 3)
+    meta["aggregated_snippets_count"] = len(trimmed)
+
+    new_state: AgentState = {
+        **state,
+        "research_snippets": trimmed,
+        "meta": meta,
+    }
+    log_state_summary(new_state, prefix="Aggregator")
+    return new_state

src/agentic_multiwriter/agents/critic.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import time
+
+from ..state import AgentState
+from ..models import LLMClient, CRITIC_PROMPT_TEMPLATE
+from ..tools import get_logger, log_state_summary
+
+logger = get_logger()
+
+
+def critic_node(state: AgentState) -> AgentState:
+    start = time.time()
+    topic = state.get("topic", "")
+    snippets = state.get("research_snippets", []) or []
+    draft = state.get("draft", "")
+
+    if not draft.strip():
+        raise ValueError("Draft is empty in state for critic_node.")
+
+    joined_snippets = "\n\n".join(
+        f"- {s['snippet']} (source: {s['title']} – {s['url']})" for s in snippets
+    )
+
+    client = LLMClient()
+
+    system_prompt = "You are a thoughtful editor focused on clarity, coherence, and factual grounding."
+    user_prompt = CRITIC_PROMPT_TEMPLATE.format(
+        topic=topic, snippets=joined_snippets, draft=draft
+    )
+
+    logger.info("Critic: improving draft...")
+    revised = client.generate(system_prompt=system_prompt, user_prompt=user_prompt)
+
+    meta = state.get("meta", {}) or {}
+    meta["critic_time_sec"] = round(time.time() - start, 3)
+
+    new_state: AgentState = {
+        **state,
+        "revised_draft": revised,
+        "meta": meta,
+    }
+    log_state_summary(new_state, prefix="Critic")
+    return new_state

src/agentic_multiwriter/agents/formatter.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import time
+
+from ..state import AgentState
+from ..models import LLMClient, FORMATTER_PROMPT_TEMPLATE
+from ..tools import get_logger, log_state_summary
+
+logger = get_logger()
+
+
+def formatter_node(state: AgentState) -> AgentState:
+    start = time.time()
+    topic = state.get("topic", "")
+    mode = state.get("mode", "blog")
+    revised = state.get("revised_draft") or state.get("draft") or ""
+
+    if not revised.strip():
+        raise ValueError("No draft or revised draft available for formatter_node.")
+
+    client = LLMClient()
+
+    system_prompt = "You are an expert formatter who adapts content to the requested mode."
+    user_prompt = FORMATTER_PROMPT_TEMPLATE.format(
+        mode=mode, topic=topic, draft=revised
+    )
+
+    logger.info("Formatter: producing final output in mode '%s'...", mode)
+    final_output = client.generate(system_prompt=system_prompt, user_prompt=user_prompt)
+
+    # Naive outline extraction: use headings lines
+    outline = []
+    for line in final_output.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("#") or stripped.endswith(":"):
+            outline.append(stripped.lstrip("#").strip())
+
+    meta = state.get("meta", {}) or {}
+    meta["formatter_time_sec"] = round(time.time() - start, 3)
+
+    new_state: AgentState = {
+        **state,
+        "final_output": final_output,
+        "outline": outline or state.get("outline", []) or [],
+        "meta": meta,
+    }
+    log_state_summary(new_state, prefix="Formatter")
+    return new_state

src/agentic_multiwriter/agents/researcher.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import time
+
+from ..state import AgentState
+from ..tools import web_search, log_state_summary, get_logger
+
+logger = get_logger()
+
+
+def researcher_node(state: AgentState) -> AgentState:
+    start = time.time()
+    topic = state.get("topic", "")
+    if not topic:
+        raise ValueError("Topic must be provided in state for researcher_node.")
+
+    logger.info("Researcher: searching web for topic '%s'...", topic)
+
+    query = f"key facts and recent information about {topic}"
+    snippets = web_search(query)
+
+    existing = state.get("research_snippets", []) or []
+    merged = existing + snippets
+
+    meta = state.get("meta", {}) or {}
+    meta["researcher_time_sec"] = round(time.time() - start, 3)
+    meta["research_snippets_count"] = len(merged)
+
+    new_state: AgentState = {
+        **state,
+        "research_snippets": merged,
+        "meta": meta,
+    }
+    log_state_summary(new_state, prefix="Researcher")
+    return new_state

src/agentic_multiwriter/agents/writer.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import time
+
+from ..state import AgentState
+from ..models import LLMClient, WRITER_PROMPT_TEMPLATE
+from ..tools import get_logger, log_state_summary
+
+logger = get_logger()
+
+
+def writer_node(state: AgentState) -> AgentState:
+    start = time.time()
+    topic = state.get("topic", "")
+    snippets = state.get("research_snippets", []) or []
+
+    joined_snippets = "\n\n".join(
+        f"- {s['snippet']} (source: {s['title']} – {s['url']})" for s in snippets
+    )
+
+    client = LLMClient()
+
+    system_prompt = "You are a precise and structured writer who follows instructions carefully."
+    user_prompt = WRITER_PROMPT_TEMPLATE.format(topic=topic, snippets=joined_snippets)
+
+    logger.info("Writer: generating first draft...")
+    draft = client.generate(system_prompt=system_prompt, user_prompt=user_prompt)
+
+    meta = state.get("meta", {}) or {}
+    meta["writer_time_sec"] = round(time.time() - start, 3)
+
+    new_state: AgentState = {
+        **state,
+        "draft": draft,
+        "meta": meta,
+    }
+    log_state_summary(new_state, prefix="Writer")
+    return new_state

src/agentic_multiwriter/api/__init__.py

@@ -0,0 +1,3 @@
+from .server import app
+
+__all__ = ["app"]

src/agentic_multiwriter/api/server.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from ..state import GenerateRequest, GenerateResponse
+from ..graph.router import run_pipeline
+from ..tools import get_logger
+
+logger = get_logger()
+
+app = FastAPI(
+    title="Agentic Multiwriter API",
+    version="0.1.0",
+    description="Multi-agent research & writing pipeline using LangGraph and LLMs.",
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.get("/health")
+def health() -> dict:
+    return {"status": "ok"}
+
+
+@app.post("/generate", response_model=GenerateResponse)
+def generate(payload: GenerateRequest) -> GenerateResponse:
+    logger.info("API: /generate called with topic='%s', mode='%s'", payload.topic, payload.mode)
+    state = run_pipeline(topic=payload.topic, mode=payload.mode)
+
+    return GenerateResponse(
+        topic=state.get("topic", payload.topic),
+        mode=state.get("mode", payload.mode),
+        outline=state.get("outline", []) or [],
+        draft=state.get("draft", "") or "",
+        revised_draft=state.get("revised_draft", "") or "",
+        final_output=state.get("final_output", "") or "",
+        meta=state.get("meta", {}) or {},
+    )

src/agentic_multiwriter/cli/__init__.py

@@ -0,0 +1,3 @@
+"""
+CLI entrypoint package for Agentic Multiwriter.
+"""

src/agentic_multiwriter/cli/main.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import argparse
+import textwrap
+
+from ..graph.router import run_pipeline
+from ..tools import get_logger
+
+logger = get_logger()
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Agentic Multiwriter - multi-agent research & writing pipeline."
+    )
+    parser.add_argument(
+        "--topic",
+        required=True,
+        help="Topic to research and write about.",
+    )
+    parser.add_argument(
+        "--mode",
+        default="blog",
+        choices=["blog", "research_summary", "linkedin_post"],
+        help="Output mode (default: blog).",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    topic = args.topic
+    mode = args.mode
+
+    logger.info("CLI: running pipeline for topic='%s', mode='%s'", topic, mode)
+    state = run_pipeline(topic=topic, mode=mode)
+
+    final_output = state.get("final_output", "") or ""
+    meta = state.get("meta", {}) or {}
+
+    print("\n" + "=" * 80)
+    print(f"TOPIC: {topic}")
+    print(f"MODE:  {mode}")
+    print("=" * 80 + "\n")
+    print(textwrap.dedent(final_output).strip())
+    print("\n" + "-" * 80)
+    print("Meta:", meta)
+
+
+if __name__ == "__main__":
+    main()

src/agentic_multiwriter/config.py

@@ -0,0 +1,37 @@
+import os
+from dataclasses import dataclass
+
+
+@dataclass
+class Settings:
+    """Global configuration for the agentic multiwriter system."""
+
+    # ollama | openai | hf_endpoint
+    llm_provider: str = os.getenv("AMW_LLM_PROVIDER", "ollama").lower()
+    llm_model: str = os.getenv("AMW_LLM_MODEL", "llama3")
+    temperature: float = float(os.getenv("AMW_TEMPERATURE", "0.4"))
+    max_search_results: int = int(os.getenv("AMW_MAX_SEARCH_RESULTS", "8"))
+
+    def validate(self) -> None:
+        allowed = {"ollama", "openai", "hf_endpoint"}
+        if self.llm_provider not in allowed:
+            raise ValueError(
+                f"Unsupported LLM provider '{self.llm_provider}'. "
+                f"Use one of: {', '.join(sorted(allowed))}."
+            )
+
+        if self.llm_provider == "openai" and not os.getenv("OPENAI_API_KEY"):
+            raise ValueError(
+                "OPENAI_API_KEY is required when AMW_LLM_PROVIDER is 'openai'."
+            )
+
+        if self.llm_provider == "hf_endpoint" and not os.getenv(
+            "HUGGINGFACEHUB_API_TOKEN"
+        ):
+            raise ValueError(
+                "HUGGINGFACEHUB_API_TOKEN is required when "
+                "AMW_LLM_PROVIDER is 'hf_endpoint'."
+            )
+
+
+settings = Settings()

src/agentic_multiwriter/graph/__init__.py

@@ -0,0 +1,3 @@
+from .workflow import build_workflow_app
+
+__all__ = ["build_workflow_app"]

src/agentic_multiwriter/graph/router.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import Dict, Any
+
+from ..state import AgentState
+from .workflow import build_workflow_app
+
+
+def run_pipeline(topic: str, mode: str = "blog") -> AgentState:
+    """
+    High-level helper to run the full workflow from scratch.
+    """
+    initial_state: AgentState = {
+        "topic": topic,
+        "mode": mode,
+        "research_snippets": [],
+        "outline": [],
+        "draft": "",
+        "revised_draft": "",
+        "final_output": "",
+        "meta": {},
+    }
+
+    app = build_workflow_app()
+    final_state: Dict[str, Any] = app.invoke(initial_state)  # type: ignore[assignment]
+    # LangGraph returns a dict compatible with AgentState
+    return final_state  # type: ignore[return-value]

src/agentic_multiwriter/graph/workflow.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from langgraph.graph import StateGraph, END
+
+from ..state import AgentState
+from ..agents import (
+    researcher_node,
+    aggregator_node,
+    writer_node,
+    critic_node,
+    formatter_node,
+)
+
+
+def build_workflow_app() -> any:
+    """
+    Build and compile the LangGraph workflow for the multi-agent pipeline.
+    Flow: Researcher -> Aggregator -> Writer -> Critic -> Formatter -> END
+    """
+    graph = StateGraph(AgentState)
+
+    graph.add_node("researcher", researcher_node)
+    graph.add_node("aggregator", aggregator_node)
+    graph.add_node("writer", writer_node)
+    graph.add_node("critic", critic_node)
+    graph.add_node("formatter", formatter_node)
+
+    graph.set_entry_point("researcher")
+    graph.add_edge("researcher", "aggregator")
+    graph.add_edge("aggregator", "writer")
+    graph.add_edge("writer", "critic")
+    graph.add_edge("critic", "formatter")
+    graph.add_edge("formatter", END)
+
+    app = graph.compile()
+    return app

src/agentic_multiwriter/models/__init__.py

@@ -0,0 +1,13 @@
+from .llm_client import LLMClient
+from .prompts import (
+    WRITER_PROMPT_TEMPLATE,
+    CRITIC_PROMPT_TEMPLATE,
+    FORMATTER_PROMPT_TEMPLATE,
+)
+
+__all__ = [
+    "LLMClient",
+    "WRITER_PROMPT_TEMPLATE",
+    "CRITIC_PROMPT_TEMPLATE",
+    "FORMATTER_PROMPT_TEMPLATE",
+]

src/agentic_multiwriter/models/llm_client.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from langchain_ollama import ChatOllama
+from langchain_openai import ChatOpenAI
+from langchain_core.messages import SystemMessage, HumanMessage
+from langchain_community.llms import HuggingFaceEndpoint
+
+from ..config import settings
+from ..tools import get_logger
+
+logger = get_logger()
+
+
+class LLMClient:
+    """
+    Wrapper to abstract over multiple LLM providers:
+    - ollama: local Ollama server
+    - openai: OpenAI Chat API
+    - hf_endpoint: Hugging Face Inference Endpoint / hosted model
+    """
+
+    def __init__(
+        self,
+        provider: Optional[str] = None,
+        model: Optional[str] = None,
+        temperature: Optional[float] = None,
+    ) -> None:
+        self.provider = (provider or settings.llm_provider).lower()
+        self.model = model or settings.llm_model
+        self.temperature = temperature if temperature is not None else settings.temperature
+
+        settings.validate()
+        self._init_client()
+        logger.info(
+            "LLMClient initialized with provider='%s', model='%s', temperature=%.2f",
+            self.provider,
+            self.model,
+            self.temperature,
+        )
+
+    def _init_client(self) -> None:
+        if self.provider == "ollama":
+            self._client = ChatOllama(
+                model=self.model, temperature=self.temperature)
+        elif self.provider == "openai":
+            self._client = ChatOpenAI(
+                model=self.model, temperature=self.temperature)
+        elif self.provider == "hf_endpoint":
+            # Uses Hugging Face hosted model via Inference API
+            # Model id should be a HF repo id, e.g. "HuggingFaceH4/zephyr-7b-beta"
+            self._client = HuggingFaceEndpoint(
+                repo_id=self.model,
+                temperature=self.temperature,
+            )
+        else:
+            raise ValueError(f"Unsupported provider: {self.provider}")
+
+    def generate(self, system_prompt: str, user_prompt: str) -> str:
+        if self.provider in {"ollama", "openai"}:
+            messages = [
+                SystemMessage(content=system_prompt),
+                HumanMessage(content=user_prompt),
+            ]
+            response = self._client.invoke(messages)
+            return response.content or ""
+
+        if self.provider == "hf_endpoint":
+            # HuggingFaceEndpoint is a text-completion-style model,
+            # so we concatenate system + user into a single prompt.
+            prompt = f"{system_prompt.strip()}\n\n{user_prompt.strip()}"
+            response = self._client.invoke(prompt)
+            return response or ""
+
+        raise ValueError(
+            f"Unsupported provider at generate(): {self.provider}")

src/agentic_multiwriter/models/prompts.py

@@ -0,0 +1,47 @@
+WRITER_PROMPT_TEMPLATE = """You are a careful, insightful writer.
+Write a structured first draft about the topic below using ONLY the research snippets provided.
+Do not invent facts. If something is unclear from the snippets, either omit it or clearly mark it as uncertainty.
+
+Topic:
+{topic}
+
+Research snippets:
+{snippets}
+
+Write a coherent, well-organized draft in clear, natural language.
+"""
+
+CRITIC_PROMPT_TEMPLATE = """You are an editor reviewing the following draft.
+Your goals:
+- Improve clarity and flow.
+- Remove repetition.
+- Highlight or remove any statements that are not clearly supported by the snippets.
+- Preserve factual accuracy.
+
+Topic:
+{topic}
+
+Research snippets:
+{snippets}
+
+Original draft:
+{draft}
+
+Now return the improved draft.
+"""
+
+FORMATTER_PROMPT_TEMPLATE = """You are formatting the final output based on the requested mode.
+
+Mode: {mode}
+Topic: {topic}
+
+Draft to format:
+{draft}
+
+Rules:
+- For mode "blog": add a title, short intro hook, subheadings, and a concise conclusion.
+- For mode "research_summary": provide bullet points for key findings, then a short narrative summary.
+- For mode "linkedin_post": keep it within ~150–220 words, conversational but professional, and end with a question or call to action.
+
+Return ONLY the formatted text.
+"""

src/agentic_multiwriter/state.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import TypedDict, List, Dict, Any
+from pydantic import BaseModel, Field
+
+
+class ResearchSnippet(TypedDict):
+    title: str
+    url: str
+    snippet: str
+
+
+class AgentState(TypedDict, total=False):
+    topic: str
+    mode: str
+    research_snippets: List[ResearchSnippet]
+    outline: List[str]
+    draft: str
+    revised_draft: str
+    final_output: str
+    meta: Dict[str, Any]
+
+
+class GenerateRequest(BaseModel):
+    topic: str = Field(..., description="Topic to research and write about.")
+    mode: str = Field(
+        "blog",
+        description="Output mode: 'blog', 'research_summary', or 'linkedin_post'.",
+    )
+
+
+class GenerateResponse(BaseModel):
+    topic: str
+    mode: str
+    outline: List[str]
+    draft: str
+    revised_draft: str
+    final_output: str
+    meta: Dict[str, Any] = Field(default_factory=dict)

src/agentic_multiwriter/tools/__init__.py

@@ -0,0 +1,5 @@
+from .web_search import web_search
+from .parsing import normalize_snippets
+from .logging_utils import get_logger, log_state_summary
+
+__all__ = ["web_search", "normalize_snippets", "get_logger", "log_state_summary"]

src/agentic_multiwriter/tools/logging_utils.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict
+
+from ..state import AgentState
+
+_LOGGER_NAME = "agentic_multiwriter"
+
+
+def get_logger() -> logging.Logger:
+    logger = logging.getLogger(_LOGGER_NAME)
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        formatter = logging.Formatter(
+            "[%(asctime)s] %(levelname)s - %(message)s", "%Y-%m-%d %H:%M:%S"
+        )
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+        logger.setLevel(logging.INFO)
+    return logger
+
+
+def log_state_summary(state: AgentState, prefix: str = "") -> None:
+    logger = get_logger()
+    topic = state.get("topic", "")
+    mode = state.get("mode", "")
+    n_snippets = len(state.get("research_snippets", []) or [])
+    logger.info(
+        "%sState summary - topic='%s', mode='%s', research_snippets=%d",
+        f"{prefix} " if prefix else "",
+        topic,
+        mode,
+        n_snippets,
+    )
+    meta: Dict[str, Any] = state.get("meta", {}) or {}
+    if meta:
+        logger.info("%sMeta: %s", prefix, meta)

src/agentic_multiwriter/tools/parsing.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import List, Dict
+
+from ..state import ResearchSnippet
+
+
+def normalize_snippets(snippets: List[ResearchSnippet]) -> List[ResearchSnippet]:
+    """
+    Deduplicate snippets by URL+snippet text and trim length.
+    """
+    seen: set[tuple[str, str]] = set()
+    normalized: List[ResearchSnippet] = []
+
+    for s in snippets:
+        key = (s["url"], s["snippet"])
+        if key in seen:
+            continue
+        seen.add(key)
+
+        snippet_text = s["snippet"].strip()
+        # Hard limit length for prompts
+        if len(snippet_text) > 600:
+            snippet_text = snippet_text[:600] + "..."
+
+        normalized.append(
+            {
+                "title": s["title"].strip(),
+                "url": s["url"].strip(),
+                "snippet": snippet_text,
+            }
+        )
+
+    return normalized

src/agentic_multiwriter/tools/web_search.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import List
+
+# Prefer the new ddgs package, fall back to duckduckgo_search if needed
+try:
+    from ddgs import DDGS  # new package name
+except ImportError:
+    from duckduckgo_search import DDGS  # old package name
+
+from ..state import ResearchSnippet
+from ..config import settings
+
+
+def web_search(query: str, max_results: int | None = None) -> List[ResearchSnippet]:
+    """
+    Perform a web search and return normalized snippets.
+    Uses DuckDuckGo via ddgs (preferred) or duckduckgo_search.
+    """
+    limit = max_results or settings.max_search_results
+    snippets: List[ResearchSnippet] = []
+
+    # region/safesearch can matter for results; 'wt-wt' = worldwide, 'off' = no filtering
+    with DDGS() as ddgs:
+        for result in ddgs.text(
+            query,
+            max_results=limit,
+        ):
+            title = result.get("title") or ""
+            url = result.get("href") or result.get("url") or ""
+            snippet = result.get("body") or result.get("snippet") or ""
+            if not snippet.strip():
+                continue
+            snippets.append(
+                {
+                    "title": title.strip(),
+                    "url": url.strip(),
+                    "snippet": snippet.strip(),
+                }
+            )
+    return snippets

tests/__init__.py

@@ -0,0 +1,3 @@
+"""
+Test package for agentic_multiwriter.
+"""

tests/test_agents.py

@@ -0,0 +1,18 @@
+from agentic_multiwriter.state import AgentState
+from agentic_multiwriter.agents import aggregator_node
+
+
+def test_aggregator_node_handles_empty():
+    state: AgentState = {
+        "topic": "Test",
+        "mode": "blog",
+        "research_snippets": [],
+        "outline": [],
+        "draft": "",
+        "revised_draft": "",
+        "final_output": "",
+        "meta": {},
+    }
+    new_state = aggregator_node(state)
+    assert "research_snippets" in new_state
+    assert isinstance(new_state["research_snippets"], list)

tests/test_state.py

@@ -0,0 +1,16 @@
+from agentic_multiwriter.state import AgentState, ResearchSnippet
+
+
+def test_agent_state_basic():
+    state: AgentState = {
+        "topic": "Test",
+        "mode": "blog",
+        "research_snippets": [],
+        "outline": [],
+        "draft": "",
+        "revised_draft": "",
+        "final_output": "",
+        "meta": {},
+    }
+    assert state["topic"] == "Test"
+    assert state["mode"] == "blog"

tests/test_tools.py

@@ -0,0 +1,10 @@
+from agentic_multiwriter.tools import normalize_snippets
+
+
+def test_normalize_snippets_deduplication():
+    snippets = [
+        {"title": "A", "url": "http://example.com", "snippet": "Same text"},
+        {"title": "B", "url": "http://example.com", "snippet": "Same text"},
+    ]
+    norm = normalize_snippets(snippets)
+    assert len(norm) == 1

tests/test_workflow.py

@@ -0,0 +1,23 @@
+from agentic_multiwriter.graph.workflow import build_workflow_app
+from agentic_multiwriter.state import AgentState
+
+
+def test_build_workflow_app():
+    app = build_workflow_app()
+    assert app is not None
+
+    # Smoke test: invoke with minimal state up to first node.
+    state: AgentState = {
+        "topic": "Test topic",
+        "mode": "blog",
+        "research_snippets": [],
+        "outline": [],
+        "draft": "",
+        "revised_draft": "",
+        "final_output": "",
+        "meta": {},
+    }
+
+    # We won't run the whole graph here because nodes depend on external services.
+    # Just confirm the app can be created and has an 'invoke' method.
+    assert hasattr(app, "invoke")