Skip to content

Commit 7b55516

Browse files
jfrench9claude
andauthored
Add taxonomy system with ledger mapping APIs and models (#73)
## Summary Introduces a comprehensive taxonomy and mapping system to the ledger API client, enabling account-to-taxonomy element mapping, reporting structures, and coverage analysis. This feature adds 14 new API endpoints and 15 new data models to support the full lifecycle of taxonomy management within the robosystems client. ## Key Accomplishments ### New Ledger API Endpoints - **Taxonomy Management**: `create_taxonomy`, `list_taxonomies`, `get_reporting_taxonomy` — full CRUD support for taxonomy definitions (e.g., IFRS, GAAP reporting taxonomies) - **Structure Management**: `create_structure`, `list_structures` — create and enumerate reporting structures within taxonomies - **Element Operations**: `list_elements`, `list_unmapped_elements` — browse and filter taxonomy elements with support for unmapped element discovery - **Mapping Associations**: `create_mapping_association`, `delete_mapping_association`, `list_mappings` — link ledger accounts to taxonomy elements with full association lifecycle - **Auto-Mapping**: `auto_map_elements` — automated mapping of accounts to taxonomy elements - **Reporting & Coverage**: `get_mapping_coverage`, `get_mapping_detail`, `get_mapped_trial_balance` — analytics endpoints for mapping completeness and mapped financial reporting ### New Data Models - Request models: `CreateTaxonomyRequest`, `CreateStructureRequest`, `CreateAssociationRequest` with associated enum types (`taxonomy_type`, `structure_type`, `association_type`) - Response models: `TaxonomyResponse`, `StructureResponse`, `ElementResponse`, `ElementAssociationResponse`, `UnmappedElementResponse`, `SuggestedTarget` - List response wrappers: `TaxonomyListResponse`, `StructureListResponse`, `ElementListResponse` - Analytics models: `MappingCoverageResponse`, `MappingDetailResponse` ### Existing Model Updates - `AccountResponse` and `AccountTreeNode` updated with additional fields to support taxonomy associations - `DocumentListItem` minor cleanup (removed unused fields) - `GraphSubscriptionTier`, `GraphTierInfo`, and `ListSubgraphsResponse` updated for graph capabilities and subgraph support - Model `__init__.py` updated with all new model exports ### Minor Modifications - `list_mcp_tools.py` and `create_subgraph.py` updated with documentation/import adjustments ## Breaking Changes - `DocumentListItem` model has fields removed, which may affect consumers relying on those properties - Minor signature or documentation changes in `graph_subscription_tier`, `graph_tier_info`, and `list_subgraphs_response` models could affect existing integrations with graph-related features ## Testing Notes - Verify all 14 new ledger endpoints handle authentication, pagination, and error responses correctly - Test taxonomy → structure → element → mapping association lifecycle end-to-end - Validate `auto_map_elements` produces reasonable suggested targets - Confirm `get_mapped_trial_balance` correctly reflects mapping associations in financial output - Ensure existing ledger, MCP, and subgraph endpoints remain functional after model changes - Check backward compatibility for consumers of `AccountResponse`, `AccountTreeNode`, and `DocumentListItem` ## Infrastructure Considerations - This is a client-side SDK change — no infrastructure deployment required, but consumers should update their client dependency version - The new endpoints assume corresponding backend API availability; coordinate rollout with backend taxonomy service deployment - The volume of new models (15) and endpoints (14) suggests this may benefit from automated API contract validation against the OpenAPI specification --- 🤖 Generated with [Claude Code](https://claude.ai/code) **Branch Info:** - Source: `feature/taxonomy-system` - Target: `main` - Type: feature Co-Authored-By: Claude <noreply@anthropic.com>
2 parents ad60dab + c545b1c commit 7b55516

40 files changed

Lines changed: 4981 additions & 36 deletions
Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
from http import HTTPStatus
2+
from typing import Any
3+
from urllib.parse import quote
4+
5+
import httpx
6+
7+
from ... import errors
8+
from ...client import AuthenticatedClient, Client
9+
from ...models.http_validation_error import HTTPValidationError
10+
from ...types import Response
11+
12+
13+
def _get_kwargs(
14+
graph_id: str,
15+
mapping_id: str,
16+
) -> dict[str, Any]:
17+
_kwargs: dict[str, Any] = {
18+
"method": "post",
19+
"url": "/v1/ledger/{graph_id}/mappings/{mapping_id}/auto-map".format(
20+
graph_id=quote(str(graph_id), safe=""),
21+
mapping_id=quote(str(mapping_id), safe=""),
22+
),
23+
}
24+
25+
return _kwargs
26+
27+
28+
def _parse_response(
29+
*, client: AuthenticatedClient | Client, response: httpx.Response
30+
) -> Any | HTTPValidationError | None:
31+
if response.status_code == 202:
32+
response_202 = response.json()
33+
return response_202
34+
35+
if response.status_code == 422:
36+
response_422 = HTTPValidationError.from_dict(response.json())
37+
38+
return response_422
39+
40+
if client.raise_on_unexpected_status:
41+
raise errors.UnexpectedStatus(response.status_code, response.content)
42+
else:
43+
return None
44+
45+
46+
def _build_response(
47+
*, client: AuthenticatedClient | Client, response: httpx.Response
48+
) -> Response[Any | HTTPValidationError]:
49+
return Response(
50+
status_code=HTTPStatus(response.status_code),
51+
content=response.content,
52+
headers=response.headers,
53+
parsed=_parse_response(client=client, response=response),
54+
)
55+
56+
57+
def sync_detailed(
58+
graph_id: str,
59+
mapping_id: str,
60+
*,
61+
client: AuthenticatedClient,
62+
) -> Response[Any | HTTPValidationError]:
63+
"""Auto-Map Elements via AI
64+
65+
Trigger autonomous CoA → GAAP mapping via background worker.
66+
67+
Uses Bedrock AI to classify and map unmapped Chart of Accounts elements
68+
to US GAAP reporting concepts. Returns a 202 with operation_id for
69+
SSE progress tracking.
70+
71+
Confidence thresholds:
72+
- ≥0.90: auto-approved mapping
73+
- 0.70-0.89: flagged for review
74+
- <0.70: skipped (left unmapped)
75+
76+
Args:
77+
graph_id (str):
78+
mapping_id (str): Mapping structure ID
79+
80+
Raises:
81+
errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
82+
httpx.TimeoutException: If the request takes longer than Client.timeout.
83+
84+
Returns:
85+
Response[Any | HTTPValidationError]
86+
"""
87+
88+
kwargs = _get_kwargs(
89+
graph_id=graph_id,
90+
mapping_id=mapping_id,
91+
)
92+
93+
response = client.get_httpx_client().request(
94+
**kwargs,
95+
)
96+
97+
return _build_response(client=client, response=response)
98+
99+
100+
def sync(
101+
graph_id: str,
102+
mapping_id: str,
103+
*,
104+
client: AuthenticatedClient,
105+
) -> Any | HTTPValidationError | None:
106+
"""Auto-Map Elements via AI
107+
108+
Trigger autonomous CoA → GAAP mapping via background worker.
109+
110+
Uses Bedrock AI to classify and map unmapped Chart of Accounts elements
111+
to US GAAP reporting concepts. Returns a 202 with operation_id for
112+
SSE progress tracking.
113+
114+
Confidence thresholds:
115+
- ≥0.90: auto-approved mapping
116+
- 0.70-0.89: flagged for review
117+
- <0.70: skipped (left unmapped)
118+
119+
Args:
120+
graph_id (str):
121+
mapping_id (str): Mapping structure ID
122+
123+
Raises:
124+
errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
125+
httpx.TimeoutException: If the request takes longer than Client.timeout.
126+
127+
Returns:
128+
Any | HTTPValidationError
129+
"""
130+
131+
return sync_detailed(
132+
graph_id=graph_id,
133+
mapping_id=mapping_id,
134+
client=client,
135+
).parsed
136+
137+
138+
async def asyncio_detailed(
139+
graph_id: str,
140+
mapping_id: str,
141+
*,
142+
client: AuthenticatedClient,
143+
) -> Response[Any | HTTPValidationError]:
144+
"""Auto-Map Elements via AI
145+
146+
Trigger autonomous CoA → GAAP mapping via background worker.
147+
148+
Uses Bedrock AI to classify and map unmapped Chart of Accounts elements
149+
to US GAAP reporting concepts. Returns a 202 with operation_id for
150+
SSE progress tracking.
151+
152+
Confidence thresholds:
153+
- ≥0.90: auto-approved mapping
154+
- 0.70-0.89: flagged for review
155+
- <0.70: skipped (left unmapped)
156+
157+
Args:
158+
graph_id (str):
159+
mapping_id (str): Mapping structure ID
160+
161+
Raises:
162+
errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
163+
httpx.TimeoutException: If the request takes longer than Client.timeout.
164+
165+
Returns:
166+
Response[Any | HTTPValidationError]
167+
"""
168+
169+
kwargs = _get_kwargs(
170+
graph_id=graph_id,
171+
mapping_id=mapping_id,
172+
)
173+
174+
response = await client.get_async_httpx_client().request(**kwargs)
175+
176+
return _build_response(client=client, response=response)
177+
178+
179+
async def asyncio(
180+
graph_id: str,
181+
mapping_id: str,
182+
*,
183+
client: AuthenticatedClient,
184+
) -> Any | HTTPValidationError | None:
185+
"""Auto-Map Elements via AI
186+
187+
Trigger autonomous CoA → GAAP mapping via background worker.
188+
189+
Uses Bedrock AI to classify and map unmapped Chart of Accounts elements
190+
to US GAAP reporting concepts. Returns a 202 with operation_id for
191+
SSE progress tracking.
192+
193+
Confidence thresholds:
194+
- ≥0.90: auto-approved mapping
195+
- 0.70-0.89: flagged for review
196+
- <0.70: skipped (left unmapped)
197+
198+
Args:
199+
graph_id (str):
200+
mapping_id (str): Mapping structure ID
201+
202+
Raises:
203+
errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
204+
httpx.TimeoutException: If the request takes longer than Client.timeout.
205+
206+
Returns:
207+
Any | HTTPValidationError
208+
"""
209+
210+
return (
211+
await asyncio_detailed(
212+
graph_id=graph_id,
213+
mapping_id=mapping_id,
214+
client=client,
215+
)
216+
).parsed

0 commit comments

Comments
 (0)