AI-Powered Generation

class GeminiClient:
    def __init__(
        self,
        api_key: str,
        model: str = DEFAULT_MODEL,
        system_prompt: str = SYSTEM_PROMPT,
        client: Any | None = None,
    ) -> None:
        if not api_key or not api_key.strip():
            raise ValueError("GEMINI_API_KEY is required.")
        
        self.model = model
        self.system_prompt = system_prompt
        self.client = client or self._build_client(api_key.strip())

SYSTEM_PROMPT = (
    "Actua como un Technical Writer Senior experto en documentacion de software. "
    "Tu tarea es analizar los metadatos de codigo (clases, funciones, docstrings) que te proporcionare.\n"
    "1. Genera una descripcion tecnica de alto nivel pero facil de entender.\n"
    "2. Crea ejemplos de uso (Usage Examples) basados en las firmas de las funciones.\n"
    "3. Manten un tono profesional, conciso y utiliza formato Markdown limpio.\n"
    "4. Si el codigo carece de docstrings, infiere la utilidad basandote en el nombre de las variables y la logica.\n"
    "5. Responde unicamente con el contenido del Markdown, sin introducciones ni despedidas."
)

def _build_content(self, project_metadata: dict[str, Any], user_prompt: str | None = None) -> str:
    metadata_json = json.dumps(project_metadata, ensure_ascii=False, indent=2)
    sections = [
        "Project metadata (JSON):",
        "```json",
        metadata_json,
        "```",
    ]
    
    if user_prompt and user_prompt.strip():
        sections.extend(["", f"Additional instruction: {user_prompt.strip()}"])
    
    return "\n".join(sections)

def generate_markdown(self, project_metadata: dict[str, Any], user_prompt: str | None = None) -> str:
    content = self._build_content(project_metadata, user_prompt=user_prompt)
    
    try:
        response = self.client.models.generate_content(
            model=self.model,
            contents=content,
            config={"system_instruction": self.system_prompt},
        )
    except Exception as exc:
        raise RuntimeError(f"Gemini API call failed: {exc}") from exc
    
    return self._extract_text(response)

@staticmethod
def _extract_text(response: Any) -> str:
    # Try direct text attribute
    direct_text = getattr(response, "text", None)
    if isinstance(direct_text, str) and direct_text.strip():
        return direct_text.strip()
    
    # Fallback: iterate through candidates
    for candidate in getattr(response, "candidates", []) or []:
        content = getattr(candidate, "content", None)
        parts = getattr(content, "parts", None) if content is not None else None
        if not parts:
            continue
        
        text_parts = [getattr(part, "text", "") for part in parts if getattr(part, "text", None)]
        joined = "".join(text_parts).strip()
        if joined:
            return joined
    
    raise RuntimeError("Gemini response did not include text content.")

except Exception as exc:
    raise RuntimeError(f"Gemini API call failed: {exc}") from exc

raise RuntimeError("Gemini response did not include text content.")

@staticmethod
def _build_client(api_key: str) -> Any:
    if genai is None:
        raise RuntimeError("google-genai is not installed. Install dependencies first.")
    return genai.Client(api_key=api_key)

try:
    from google import genai
except ImportError:
    genai = None  # type: ignore[assignment]

def render_readme(ai_content: str, project_name: str, summary: dict[str, Any] | None = None) -> str:
    engine = TemplateEngine()
    return engine.render(
        DEFAULT_TEMPLATE,
        {
            "project_name": project_name,
            "ai_content": ai_content.strip(),
            "summary": summary or {},
        },
    )

# 1. Initialize client
client = GeminiClient(api_key="your-key")

# 2. Prepare metadata (from previous phases)
metadata = prepare_for_ai(parsed_files)

# 3. Generate documentation
ai_markdown = client.generate_markdown(
    project_metadata=metadata,
    user_prompt="Focus on the public API"
)

# 4. Render final output
final_docs = render_readme(
    ai_content=ai_markdown,
    project_name="MyProject",
    summary=metadata["summary"]
)

client = GeminiClient(
    api_key="your-key",
    model="gemini-4.5-pro"  # More powerful model
)

custom_prompt = """
You are a documentation expert. Generate API reference documentation
with a focus on code examples and best practices. Use TypeScript-style
type annotations when possible.
"""

client = GeminiClient(
    api_key="your-key",
    system_prompt=custom_prompt
)

ai_markdown = client.generate_markdown(
    project_metadata=metadata,
    user_prompt="Include detailed examples for the GeminiClient class"
)