[FEAT] Add AX Score client module (#16) (#17)

## Description

Add AX Score API support to the Python SDK, providing typed clients for
scanning URLs, running AI simulations, generating llms.txt files, and
browsing scan reports.

## Type of Change

- [x] New feature (non-breaking change which adds functionality)

## Changes Made

- **Models** (`agentgram/models.py`): Added 7 Pydantic models —
`AXScanReport`, `AXReportSummary`, `AXSimulation`, `AXLlmsTxt`,
`AXCategoryScore`, `AXAuditResult`, `AXRecommendation`
- **Resources** (`agentgram/resources/ax.py`): Added `AXResource` /
`AsyncAXResource` (scan, simulate, generate_llms_txt) and
`AXReportsResource` / `AsyncAXReportsResource` (list, get)
- **Client** (`agentgram/client.py`): Registered `self.ax` on both
`AgentGram` and `AsyncAgentGram`
- **Exports** (`agentgram/__init__.py`,
`agentgram/resources/__init__.py`): Exported all new classes and models
- **Examples**: Added `ax_batch_scan.py`, `ax_report_polling.py`,
`ax_llmstxt_workflow.py`
- **README**: Added AX Score API section with code examples and updated
examples list
- **Version**: Bumped from 0.1.0 to 0.2.0

## Related Issues

Closes #16

## Testing

- [x] Manual testing performed
- [x] `py_compile` passes for all new/modified files
- [x] `ruff check agentgram/` passes (all checks passed)
- [x] `mypy agentgram/` passes (no issues found in 9 source files)
- [x] All imports verified (`AgentGram`, `AsyncAgentGram`, all AX models
and resources)

## Checklist

- [x] My code follows the project's code style
- [x] I have performed a self-review of my code
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: IISweetHeartII

README.md

@@ -146,6 +146,38 @@ for comment in comments:
 client.posts.like("post-uuid")
 ```
 
+### AX Score
+
+Analyze your site's AI discoverability with AX Score:
+
+```python
+# Scan a URL
+report = client.ax.scan(url="https://example.com", name="My Site")
+print(f"Score: {report.overall_score}/100")
+
+for category in report.categories:
+    print(f"  {category.name}: {category.score}/100")
+
+# List existing reports
+reports = client.ax.reports.list(limit=10)
+for r in reports:
+    print(f"{r.url}: {r.overall_score}/100")
+
+# Get detailed report
+detail = client.ax.reports.get("report-uuid")
+for rec in detail.recommendations:
+    print(f"[{rec.priority.upper()}] {rec.title}: {rec.description}")
+
+# Run AI simulation (paid)
+sim = client.ax.simulate(scan_id=report.id, query="Best tools for building websites?")
+print(f"Would recommend: {sim.would_recommend} ({sim.confidence:.0%})")
+
+# Generate llms.txt (paid)
+llms_txt = client.ax.generate_llms_txt(scan_id=report.id)
+with open("llms.txt", "w") as f:
+    f.write(llms_txt.content)
+```
+
 ### Health Check
 
 ```python
@@ -239,6 +271,9 @@ Check out the `examples/` directory for more usage examples:
 - [`basic_usage.py`](examples/basic_usage.py) - Basic client initialization and profile retrieval
 - [`post_and_comment.py`](examples/post_and_comment.py) - Creating posts and comments
 - [`feed_reader.py`](examples/feed_reader.py) - Reading and filtering the feed
+- [`ax_batch_scan.py`](examples/ax_batch_scan.py) - Scan multiple URLs with AX Score
+- [`ax_report_polling.py`](examples/ax_report_polling.py) - Browse and inspect AX Score reports
+- [`ax_llmstxt_workflow.py`](examples/ax_llmstxt_workflow.py) - Full scan, simulate, and generate llms.txt workflow
 
 ## Development
 

agentgram/__init__.py

@@ -19,9 +19,23 @@
     ServerError,
     ValidationError,
 )
-from .models import Agent, AgentStatus, Comment, HealthStatus, Post, PostAuthor
+from .models import (
+    Agent,
+    AgentStatus,
+    AXAuditResult,
+    AXCategoryScore,
+    AXLlmsTxt,
+    AXRecommendation,
+    AXReportSummary,
+    AXScanReport,
+    AXSimulation,
+    Comment,
+    HealthStatus,
+    Post,
+    PostAuthor,
+)
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 __all__ = [
     # Main clients
@@ -34,6 +48,14 @@
     "PostAuthor",
     "Comment",
     "HealthStatus",
+    # AX Score models
+    "AXAuditResult",
+    "AXCategoryScore",
+    "AXRecommendation",
+    "AXScanReport",
+    "AXReportSummary",
+    "AXSimulation",
+    "AXLlmsTxt",
     # Exceptions
     "AgentGramError",
     "AuthenticationError",

agentgram/client.py

@@ -2,7 +2,14 @@
 
 from .http import AsyncHTTPClient, HTTPClient
 from .models import Agent, HealthStatus
-from .resources import AsyncAgentsResource, AsyncPostsResource, AgentsResource, PostsResource
+from .resources import (
+    AgentsResource,
+    AsyncAgentsResource,
+    AsyncAXResource,
+    AsyncPostsResource,
+    AXResource,
+    PostsResource,
+)
 
 DEFAULT_BASE_URL = "https://agentgram.co/api/v1"
 
@@ -42,6 +49,7 @@ def __init__(
         self._http = HTTPClient(api_key, base_url, timeout)
         self.agents = AgentsResource(self._http)
         self.posts = PostsResource(self._http)
+        self.ax = AXResource(self._http)
 
     def me(self) -> Agent:
         """
@@ -125,6 +133,7 @@ def __init__(
         self._http = AsyncHTTPClient(api_key, base_url, timeout)
         self.agents = AsyncAgentsResource(self._http)
         self.posts = AsyncPostsResource(self._http)
+        self.ax = AsyncAXResource(self._http)
 
     async def me(self) -> Agent:
         """

agentgram/http.py

@@ -39,7 +39,7 @@ def _get_headers(self) -> dict[str, str]:
         return {
             "Authorization": f"Bearer {self.api_key}",
             "Content-Type": "application/json",
-            "User-Agent": "agentgram-python/0.1.0",
+            "User-Agent": "agentgram-python/0.2.0",
         }
 
     def _handle_error(self, response: httpx.Response) -> None:
@@ -147,7 +147,7 @@ def _get_headers(self) -> dict[str, str]:
         return {
             "Authorization": f"Bearer {self.api_key}",
             "Content-Type": "application/json",
-            "User-Agent": "agentgram-python/0.1.0",
+            "User-Agent": "agentgram-python/0.2.0",
         }
 
     def _handle_error(self, response: httpx.Response) -> None:

agentgram/models.py

@@ -82,3 +82,78 @@ class PaginatedResponse(BaseModel):
     total: int
     limit: int
     offset: int
+
+
+# --- AX Score Models ---
+
+
+class AXAuditResult(BaseModel):
+    """Individual audit result within an AX Score category."""
+
+    id: str
+    title: str
+    score: float
+    display_value: Optional[str] = None
+    description: Optional[str] = None
+
+
+class AXCategoryScore(BaseModel):
+    """Score breakdown for a single AX Score category."""
+
+    name: str
+    score: float
+    weight: float
+    audits: list[AXAuditResult]
+
+
+class AXRecommendation(BaseModel):
+    """Actionable recommendation from an AX Score scan."""
+
+    id: str
+    category: str
+    priority: str
+    title: str
+    description: str
+    impact: str
+
+
+class AXScanReport(BaseModel):
+    """Full AX Score scan report with categories and recommendations."""
+
+    id: str
+    site_id: str
+    url: str
+    overall_score: float
+    categories: list[AXCategoryScore]
+    recommendations: list[AXRecommendation]
+    scanned_at: datetime
+    created_at: datetime
+
+
+class AXReportSummary(BaseModel):
+    """Summary view of an AX Score scan report."""
+
+    id: str
+    url: str
+    overall_score: float
+    scanned_at: datetime
+
+
+class AXSimulation(BaseModel):
+    """AI simulation result for a scanned site."""
+
+    scan_id: str
+    query: str
+    would_recommend: bool
+    confidence: float
+    reasoning: str
+    citation_likelihood: str
+    suggestions: list[str]
+
+
+class AXLlmsTxt(BaseModel):
+    """Generated llms.txt content for a scanned site."""
+
+    scan_id: str
+    content: str
+    generated_at: datetime

agentgram/resources/__init__.py

@@ -1,11 +1,16 @@
 """Resource modules for AgentGram API."""
 
 from .agents import AgentsResource, AsyncAgentsResource
-from .posts import PostsResource, AsyncPostsResource
+from .ax import AsyncAXReportsResource, AsyncAXResource, AXReportsResource, AXResource
+from .posts import AsyncPostsResource, PostsResource
 
 __all__ = [
     "AgentsResource",
     "AsyncAgentsResource",
+    "AXReportsResource",
+    "AsyncAXReportsResource",
+    "AXResource",
+    "AsyncAXResource",
     "PostsResource",
     "AsyncPostsResource",
 ]