API Reference

API Reference

Complete Python API documentation for Agentic-Writer.

Table of Contents

• Core Classes
• Configuration
• Agents
• Utilities
• CLI
• Types and Schemas
• Examples

Core Classes

ContentCreationOrchestrator

Location: src/orchestrator.py

Main orchestrator class that coordinates all agents.

Constructor

ContentCreationOrchestrator(config: Config)

Parameters:

• config (Config): Configuration object with API keys and settings

Example:

from src.orchestrator import ContentCreationOrchestrator
from src.utils import Config

config = Config.from_env()
orchestrator = ContentCreationOrchestrator(config)

Methods

create_content()

create_content(
    topic: str,
    style: str = "professional",
    target_audience: str = "general audience",
    platforms: List[str] = ["file"],
    output_dir: str = "output"
) -> Dict[str, Any]

Execute the complete content creation pipeline.

Parameters:

• topic (str): The topic to write about
• style (str): Writing style - "professional", "casual", "technical", or "accessible"
• target_audience (str): Description of target audience
• platforms (List[str]): Publishing platforms - ["file"], ["medium"], or both
• output_dir (str): Directory to save output files

Returns:

{
    "status": "completed" | "failed",
    "research": Dict[str, Any],
    "article": Dict[str, Any],
    "images": Dict[str, Any],
    "publication": Dict[str, Dict[str, Any]],
    "error": Optional[str]
}

Example:

results = orchestrator.create_content(
    topic="Machine Learning Basics",
    style="accessible",
    target_audience="beginners",
    platforms=["file"],
    output_dir="./articles"
)

if results["status"] == "completed":
    print(f"Title: {results['article']['title']}")

get_summary()

get_summary(results: Dict[str, Any]) -> str

Generate human-readable summary of results.

Parameters:

• results (Dict): Results from create_content()

Returns:

• str: Formatted summary string

Example:

summary = orchestrator.get_summary(results)
print(summary)

Configuration

Config

Location: src/utils/config.py

Configuration management using Pydantic.

Class Definition

class Config(BaseModel):
    openai_api_key: str
    medium_access_token: Optional[str] = None
    unsplash_access_key: Optional[str] = None
    openai_model: str = "gpt-4-turbo-preview"
    temperature: float = 0.7
    log_level: str = "INFO"
    max_research_sources: int = 5
    max_retries: int = 3

Class Methods

from_env()

@classmethod
def from_env(cls) -> "Config"

Load configuration from environment variables.

Returns:

• Config: Configuration object

Example:

from src.utils import Config

config = Config.from_env()
print(f"Model: {config.openai_model}")

validate_required()

def validate_required(self) -> None

Validate that required configuration is present.

Raises:

• ValueError: If required configuration is missing

Example:

try:
    config.validate_required()
    print("Configuration valid!")
except ValueError as e:
    print(f"Error: {e}")

Agents

ResearchAgent

Location: src/agents/researcher.py

Conducts web research and synthesizes information.

Constructor

ResearchAgent(llm: ChatOpenAI, max_sources: int = 5)

Parameters:

• llm (ChatOpenAI): Language model instance
• max_sources (int): Maximum number of sources to research

Methods

research()

research(topic: str) -> Dict[str, Any]

Conduct full research pipeline.

Parameters:

• topic (str): Topic to research

Returns:

{
    "topic": str,
    "analysis": str,
    "search_results": List[Dict[str, str]],
    "synthesis": str,
    "sources_count": int
}

Example:

from src.agents import ResearchAgent
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4", temperature=0.7)
researcher = ResearchAgent(llm=llm, max_sources=5)

results = researcher.research("Artificial Intelligence")
print(results["synthesis"])

analyze_topic()

analyze_topic(topic: str) -> str

Analyze topic and identify key areas.

Parameters:

• topic (str): Topic to analyze

Returns:

• str: Topic analysis

search_web()

search_web(topic: str) -> List[Dict[str, str]]

Search the web using DuckDuckGo.

Parameters:

• topic (str): Search query

Returns:

[
    {
        "title": str,
        "body": str,
        "href": str
    }
]

synthesize_research()

synthesize_research(topic: str, results: List[Dict]) -> str

Synthesize research findings.

Parameters:

• topic (str): Original topic
• results (List[Dict]): Search results

Returns:

• str: Research synthesis

WriterAgent

Location: src/agents/writer.py

Generates articles and metadata.

Constructor

WriterAgent(llm: ChatOpenAI)

Parameters:

• llm (ChatOpenAI): Language model instance

Methods

write_article()

write_article(
    research_data: Dict[str, Any],
    style: str = "professional",
    target_audience: str = "general audience"
) -> Dict[str, Any]

Generate complete article with metadata.

Parameters:

• research_data (Dict): Results from ResearchAgent
• style (str): Writing style
• target_audience (str): Target audience description

Returns:

{
    "title": str,
    "content": str,
    "outline": str,
    "meta_description": str,
    "tags": List[str],
    "word_count": int,
    "topic": str
}

Example:

from src.agents import WriterAgent

writer = WriterAgent(llm=llm)
article = writer.write_article(
    research_data=research_results,
    style="casual",
    target_audience="beginners"
)

print(f"Title: {article['title']}")
print(f"Words: {article['word_count']}")

create_outline()

create_outline(research: str, style: str) -> str

Create article outline.

generate_title()

generate_title(content: str) -> str

Generate engaging title.

generate_meta_description()

generate_meta_description(content: str) -> str

Create meta description.

generate_tags()

generate_tags(content: str) -> List[str]

Generate relevant tags.

ImageAgent

Location: src/agents/image_handler.py

Finds and curates relevant images.

Constructor

ImageAgent(llm: ChatOpenAI, unsplash_access_key: Optional[str] = None)

Parameters:

• llm (ChatOpenAI): Language model instance
• unsplash_access_key (Optional[str]): Unsplash API key

Methods

find_images()

find_images(article_content: str, article_title: str) -> Dict[str, Any]

Find relevant images for article.

Parameters:

• article_content (str): Article content
• article_title (str): Article title

Returns:

{
    "images": [
        {
            "url": str,
            "description": str,
            "author": str,
            "author_url": str
        }
    ]
}

Example:

from src.agents import ImageAgent

image_handler = ImageAgent(
    llm=llm,
    unsplash_access_key="your-key"
)

images = image_handler.find_images(
    article_content=article["content"],
    article_title=article["title"]
)

for img in images["images"]:
    print(f"Image: {img['url']}")

generate_image_queries()

generate_image_queries(content: str, title: str) -> List[str]

Generate search queries for images.

search_unsplash()

search_unsplash(query: str) -> List[Dict]

Search Unsplash for images.

PublisherAgent

Location: src/agents/publisher.py

Publishes content to various platforms.

Constructor

PublisherAgent(medium_access_token: Optional[str] = None)

Parameters:

• medium_access_token (Optional[str]): Medium API token

Methods

publish()

publish(
    article: Dict[str, Any],
    images: Dict[str, Any],
    platforms: List[str],
    output_dir: str = "output"
) -> Dict[str, Dict[str, Any]]

Publish to specified platforms.

Parameters:

• article (Dict): Article data from WriterAgent
• images (Dict): Images from ImageAgent
• platforms (List[str]): Target platforms
• output_dir (str): Output directory

Returns:

{
    "file": {
        "success": bool,
        "platform": str,
        "markdown_file": str,
        "metadata_file": str
    },
    "medium": {
        "success": bool,
        "platform": str,
        "url": str,
        "error": Optional[str]
    }
}

Example:

from src.agents import PublisherAgent

publisher = PublisherAgent(
    medium_access_token="your-token"
)

results = publisher.publish(
    article=article,
    images=images,
    platforms=["file", "medium"],
    output_dir="./output"
)

for platform, result in results.items():
    if result["success"]:
        print(f"{platform}: ✓ Success")

publish_to_file()

publish_to_file(
    article: Dict,
    images: Dict,
    output_dir: str
) -> Dict

Save to file system.

publish_to_medium()

publish_to_medium(article: Dict, images: Dict) -> Dict

Publish to Medium.

Utilities

Logger

Location: src/utils/logger.py

setup_logger()

setup_logger(
    name: str = "agentic_writer",
    level: str = "INFO",
    log_file: Optional[str] = None
) -> logging.Logger

Setup configured logger.

Parameters:

• name (str): Logger name
• level (str): Log level (DEBUG, INFO, WARNING, ERROR)
• log_file (Optional[str]): Path to log file

Returns:

• logging.Logger: Configured logger

Example:

from src.utils import setup_logger

logger = setup_logger(
    name="my_app",
    level="DEBUG",
    log_file="app.log"
)

logger.info("Application started")
logger.debug("Debug information")

CLI

Main CLI

Location: src/cli.py

run_cli()

def run_cli() -> None

Main CLI entry point.

Usage:

python main.py create "topic" [options]
python main.py config
python main.py version

Types and Schemas

Research Result Schema

{
    "topic": str,
    "analysis": str,
    "search_results": [
        {
            "title": str,
            "body": str,
            "href": str
        }
    ],
    "synthesis": str,
    "sources_count": int
}

Article Schema

{
    "title": str,
    "content": str,  # Markdown formatted
    "outline": str,
    "meta_description": str,
    "tags": List[str],  # 5-8 tags
    "word_count": int,  # 1200-1500
    "topic": str
}

Images Schema

{
    "images": [
        {
            "url": str,
            "description": str,
            "author": str,
            "author_url": str
        }
    ]
}

Publication Result Schema

{
    "platform_name": {
        "success": bool,
        "platform": str,
        "markdown_file": Optional[str],
        "metadata_file": Optional[str],
        "url": Optional[str],
        "error": Optional[str]
    }
}

Examples

Complete Example

from src.orchestrator import ContentCreationOrchestrator
from src.utils import Config, setup_logger

# Setup
logger = setup_logger(level="INFO")
config = Config.from_env()
config.validate_required()

# Create orchestrator
orchestrator = ContentCreationOrchestrator(config)

# Create content
results = orchestrator.create_content(
    topic="The Future of AI",
    style="professional",
    target_audience="business leaders",
    platforms=["file", "medium"],
    output_dir="./articles"
)

# Handle results
if results["status"] == "completed":
    print("✓ Success!")
    print(orchestrator.get_summary(results))
    
    article = results["article"]
    print(f"\nTitle: {article['title']}")
    print(f"Words: {article['word_count']}")
    print(f"Tags: {', '.join(article['tags'])}")
    
    # Access files
    pub = results["publication"]["file"]
    print(f"\nMarkdown: {pub['markdown_file']}")
    print(f"Metadata: {pub['metadata_file']}")
else:
    print(f"✗ Failed: {results.get('error')}")

Using Individual Agents

from src.agents import ResearchAgent, WriterAgent, ImageAgent, PublisherAgent
from src.utils import Config
from langchain_openai import ChatOpenAI

# Setup
config = Config.from_env()
llm = ChatOpenAI(
    model=config.openai_model,
    temperature=config.temperature,
    api_key=config.openai_api_key
)

# Research
researcher = ResearchAgent(llm, max_sources=5)
research = researcher.research("Machine Learning")

# Write
writer = WriterAgent(llm)
article = writer.write_article(
    research_data=research,
    style="technical",
    target_audience="developers"
)

# Images
image_handler = ImageAgent(llm, config.unsplash_access_key)
images = image_handler.find_images(
    article_content=article["content"],
    article_title=article["title"]
)

# Publish
publisher = PublisherAgent(config.medium_access_token)
results = publisher.publish(
    article=article,
    images=images,
    platforms=["file"],
    output_dir="./output"
)

Custom Configuration

from src.utils import Config

# Create custom config
config = Config(
    openai_api_key="sk-...",
    openai_model="gpt-3.5-turbo",
    temperature=0.5,
    max_research_sources=3,
    max_retries=5,
    log_level="DEBUG"
)

# Use config
orchestrator = ContentCreationOrchestrator(config)

Batch Processing

topics = [
    "AI in Healthcare",
    "Blockchain Technology",
    "Renewable Energy"
]

for topic in topics:
    print(f"Processing: {topic}")
    
    results = orchestrator.create_content(
        topic=topic,
        style="professional",
        target_audience="general audience",
        platforms=["file"],
        output_dir=f"./articles/{topic.replace(' ', '_').lower()}"
    )
    
    if results["status"] == "completed":
        print(f"✓ {topic} completed")
    else:
        print(f"✗ {topic} failed: {results.get('error')}")

Error Handling

try:
    results = orchestrator.create_content(
        topic="Your Topic",
        style="professional",
        target_audience="general audience"
    )
    
    if results["status"] == "completed":
        print("Success!")
    else:
        print(f"Failed: {results.get('error')}")
        
except ValueError as e:
    print(f"Configuration error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

---

More examples? Check out the Usage Guide and examples.py.

Need help? See the FAQ or open an issue.