carbonarc 1.0.0__py2.py3-none-any.whl

carbonarc/explorer.py

@@ -0,0 +1,223 @@
+import pandas as pd
+from typing import Optional, Literal, Union, List, Dict, Any
+
+from carbonarc.base.utils import timeseries_response_to_pandas
+from carbonarc.base.client import BaseAPIClient
+from carbonarc.base.exceptions import InvalidConfigurationError
+
+
+class ExplorerAPIClient(BaseAPIClient):
+    """Client for interacting with the Carbon Arc Builder API."""
+
+    def __init__(
+        self,
+        token: str,
+        host: str = "https://platform.carbonarc.co",
+        version: str = "v2"
+    ):
+        """
+        Initialize BuilderAPIClient.
+
+        Args:
+            token: Authentication token for requests.
+            host: Base URL of the Carbon Arc API.
+            version: API version to use.
+        """
+        super().__init__(token=token, host=host, version=version)
+        self.base_framework_url = self._build_base_url("framework")
+
+    @staticmethod
+    def build_framework(
+        entities: List[Dict],
+        insight: int,
+        filters: Dict[str, Any],
+        aggregate: Optional[Literal["sum", "mean"]] = None
+    ) -> dict:
+        """
+        Build a framework payload for the API.
+
+        Args:
+            entities: List of entity dicts (with "carc_id" and "representation").
+            insight: Insight ID.
+            filters: Filters to apply.
+            aggregate: Aggregation method ("sum" or "mean").
+
+        Returns:
+            Framework dictionary.
+        """
+        return {
+            "entities": entities,
+            "insight": {"insight_id": insight},
+            "filters": filters,
+            "aggregate": aggregate
+        }
+
+    @staticmethod
+    def _validate_framework(framework: dict):
+        """
+        Validate a framework dictionary for required structure.
+
+        Args:
+            framework: Framework dictionary.
+
+        Raises:
+            InvalidConfigurationError: If the framework is invalid.
+        """
+        if not isinstance(framework, dict):
+            raise InvalidConfigurationError("Framework must be a dictionary. Use build_framework().")
+        if "entities" not in framework:
+            raise InvalidConfigurationError("Framework must have an 'entities' key.")
+        if not isinstance(framework["entities"], list):
+            raise InvalidConfigurationError("Entities must be a list.")
+        if not all(isinstance(entity, dict) for entity in framework["entities"]):
+            raise InvalidConfigurationError("Each entity must be a dictionary.")
+        for entity in framework["entities"]:
+            if "carc_id" not in entity:
+                raise InvalidConfigurationError("Each entity must have a 'carc_id' key.")
+            if "representation" not in entity:
+                raise InvalidConfigurationError("Each entity must have a 'representation' key.")
+        if not isinstance(framework["insight"], dict):
+            raise InvalidConfigurationError("Insight must be a dictionary.")
+        if "insight_id" not in framework["insight"]:
+            raise InvalidConfigurationError("Insight must have an 'insight_id' key.")
+
+    def collect_framework_filters(self, framework: dict) -> dict:
+        """
+        Retrieve available filters for a framework.
+
+        Args:
+            framework: Framework dictionary.
+
+        Returns:
+            Dictionary of available filters.
+        """
+        self._validate_framework(framework)
+        url = f"{self.base_framework_url}/filters"
+        return self._post(url, json=framework)
+
+    def collect_framework_filter_options(self, framework: dict, filter_key: str) -> dict:
+        """
+        Retrieve options for a specific filter in a framework.
+
+        Args:
+            framework: Framework dictionary.
+            filter_key: Filter key to retrieve options for.
+
+        Returns:
+            Dictionary of filter options.
+        """
+        self._validate_framework(framework)
+        url = f"{self.base_framework_url}/filters/{filter_key}/options"
+        return self._post(url, json=framework)
+
+    
+    def collect_framework_information(self, framework: dict) -> dict:
+        """
+        Retrieve metadata for a framework.
+
+        Args:
+            framework: Framework dictionary.
+
+        Returns:
+            Dictionary of framework metadata.
+        """
+        self._validate_framework(framework)
+        url = f"{self.base_framework_url}/information"
+        return self._post(url, json=framework)
+
+    def buy_frameworks(self, order: List[dict]) -> dict:
+        """
+        Purchase one or more frameworks.
+
+        Args:
+            order: List of framework dictionaries to purchase.
+
+        Returns:
+            Dictionary with purchase information.
+        """
+        for framework in order:
+            self._validate_framework(framework)
+        url = f"{self.base_framework_url}/buy"
+        return self._post(url, json=order)
+
+    def get_framework_data(
+        self,
+        framework_id: str,
+        page: int = 1,
+        page_size: int = 100,
+        data_type: Optional[Literal["dataframe", "timeseries"]] = None,
+    ) -> Union[pd.DataFrame, dict]:
+        """
+        Retrieve data for a specific framework.
+
+        Args:
+            framework_id: Framework ID.
+            page: Page number (default 1).
+            page_size: Number of items per page (default 100).
+            data_type: Data type to retrieve ("dataframe" or "timeseries").
+
+        Returns:
+            Data as a DataFrame, dictionary, or timeseries, depending on data_type.
+        """
+        endpoint = f"{framework_id}/data"
+        url = f"{self.base_framework_url}/{endpoint}?page={page}&size={page_size}"
+        if data_type:
+            url += f"&type={data_type}"
+        if data_type == "dataframe":
+            return pd.DataFrame(self._get(url).get("data", {}))
+        elif data_type == "timeseries":
+            return timeseries_response_to_pandas(response=self._get(url))
+        else:
+            return self._get(url)
+
+    def stream_framework_data(
+        self,
+        framework_id: str,
+        page_size: int = 100,
+        data_type: Optional[Literal["dataframe", "timeseries"]] = None,
+    ):
+        """
+        Iterate over all data for a framework, yielding each page.
+
+        Args:
+            framework_id: Framework ID.
+            page_size: Number of items per page (default 100).
+            data_type: Data type to yield ("dataframe" or "timeseries").
+
+        Yields:
+            Data for each page as a DataFrame, timeseries, or dictionary.
+        """
+        page = 1
+        while True:
+            response = self.get_framework_data(
+                framework_id=framework_id,
+                page=page,
+                page_size=page_size,
+            )
+            if not response:
+                break
+            total_pages = response.get("pages", 0)
+            if page > total_pages:
+                break
+            if data_type == "dataframe":
+                yield pd.DataFrame(response.get("data", {}))
+            elif data_type == "timeseries":
+                yield timeseries_response_to_pandas(response=response)
+            else:
+                yield response
+            page += 1
+    
+    def get_framework_metadata(self, framework_id: str) -> dict:
+        """
+        Retrieve metadata for a specific framework.
+
+        Args:
+            framework_id: Framework ID.
+
+        Returns:
+            Dictionary of framework metadata.
+        """
+        endpoint = f"{framework_id}/metadata"
+        url = f"{self.base_framework_url}/{endpoint}"
+        return self._get(url)
+    

carbonarc/hub.py

@@ -0,0 +1,45 @@
+from carbonarc.base.client import BaseAPIClient
+
+class HubAPIClient(BaseAPIClient):
+    """
+    A client for interacting with the Carbon Arc Hub API.
+    """
+
+    def __init__(
+        self, 
+        token: str,
+        host: str = "https://platform.carbonarc.co",
+        version: str = "v2"
+        ):
+        """
+        Initialize HubAPIClient with an authentication token and user agent.
+        
+        Args:
+            token: The authentication token to be used for requests.
+            host: The base URL of the Carbon Arc API.
+            version: The API version to use.
+        """
+        super().__init__(token=token, host=host, version=version)
+        
+        self.base_hub_url = self._build_base_url("hub")
+    
+    def get_webcontent_feeds(self) -> dict:
+        """
+        Retrieve all webcontent feeds.
+        """
+        url = f"{self.base_hub_url}/webcontent"
+        return self._get(url)
+    
+    def get_subscribed_feeds(self) -> dict:
+        """
+        Retrieve all subscribed webcontent feeds.
+        """
+        url = f"{self.base_hub_url}/webcontent/subscribed"
+        return self._get(url)
+    
+    def get_webcontent_data(self, webcontent_name: str, page: int = 1, size: int = 100) -> dict:
+        """
+        Retrieve a webcontent feed by name.
+        """
+        url = f"{self.base_hub_url}/webcontent/{webcontent_name}?page={page}&size={size}"
+        return self._get(url)

carbonarc/ontology.py

@@ -0,0 +1,238 @@
+from typing import Optional, List, Literal, Dict, Any, Union
+
+from carbonarc.base.client import BaseAPIClient
+
+class OntologyAPIClient(BaseAPIClient):
+    """
+    A client for interacting with the Carbon Arc Ontology API.
+    """
+
+    def __init__(
+        self, 
+        token: str,
+        host: str = "https://platform.carbonarc.co",
+        version: str = "v2"
+        ):
+        """
+        Initialize OntologyAPIClient with an authentication token and user agent.
+        
+        Args:
+            token: The authentication token to be used for requests.
+            host: The base URL of the Carbon Arc API.
+            version: The API version to use.
+        """
+        super().__init__(token=token, host=host, version=version)
+        
+        self.base_ontology_url = self._build_base_url("ontology")
+    
+    def get_entity_map(self) -> dict:
+        """
+        Retrieve the entity map.
+        """
+        url = f"{self.base_ontology_url}/entity-map"
+        return self._get(url)
+    
+    def get_insight_map(self) -> dict:
+        """
+        Retrieve the insight map.
+        """
+        url = f"{self.base_ontology_url}/insight-map"
+        return self._get(url)
+
+    def get_entities(
+        self,
+        representation: Optional[List[str]] = None,
+        domain: Optional[Union[str, List[str]]] = None,
+        entity: Optional[List[Literal["brand", "company", "people", "location"]]] = None,
+        subject_ids: Optional[List[int]] = None,
+        topic_ids: Optional[List[int]] = None,
+        insight_types: Optional[List[Literal["metric", "event", "kpi", "marketshare", "cohort"]]] = None,
+        insight_id: Optional[int] = None,
+        version: Optional[str] = "latest",
+        page: int = 1,
+        size: int = 100,
+        sort_by: str = "label",
+        order: str = "asc"
+    ) -> Dict[str, Any]:
+        """
+        Retrieve entities with filtering and pagination.
+
+        Args:
+            entity_representation: List of entity representations to filter by.
+            entity_domain: Entity domain(s) to filter by.
+            entity: List of entity types to filter by.
+            subject_ids: List of subject IDs to filter by.
+            topic_ids: List of topic IDs to filter by.
+            insight_types: List of insight types to filter by.
+            insight_id: Insight ID to filter by.
+            page: Page number (default 1).
+            size: Number of results per page (default 100).
+            sort_by: Field to sort by.
+            order: Sort direction ("asc" or "desc").
+
+        Returns:
+            Dictionary containing paginated entities.
+        """
+        params = {
+            "page": page,
+            "size": size,
+            "sort_by": sort_by,
+            "order": order
+        }
+        if subject_ids:
+            params["subject_ids"] = subject_ids
+        if topic_ids:
+            params["topic_ids"] = topic_ids
+        if insight_types:
+            params["insight_types"] = insight_types
+        if insight_id:
+            params["insight_id"] = insight_id
+        if representation:
+            params["entity_representation"] = representation
+        if domain:
+            params["entity_domain"] = domain
+        if entity:
+            params["entity"] = entity
+        if version:
+            params["version"] = version
+        url = f"{self.base_ontology_url}/entities"
+        return self._get(url, params=params)
+
+    def get_entity_information(self, entity_id: int, representation: str) -> dict:
+        """
+        Retrieve information for a specific entity.
+
+        Args:
+            entity_id: Entity ID.
+
+        Returns:
+            Dictionary with entity information.
+        """
+        params = {"entity_representation": representation}
+        url = f"{self.base_ontology_url}/entities/{entity_id}"
+        return self._get(url, params=params)
+
+    def get_insights(
+        self,
+        subject_ids: Optional[List[int]] = None,
+        topic_ids: Optional[List[int]] = None,
+        insight_types: Optional[List[Literal["metric", "event", "kpi", "marketshare", "cohort"]]] = None,
+        entity_id: Optional[int] = None,
+        entity_representation: Optional[str] = None,
+        entity_domain: Optional[Union[str, List[str]]] = None,
+        entity: Optional[Literal["brand", "company", "people", "location"]] = None,
+        page: int = 1,
+        size: int = 100,
+        sort_by: str = "insight_label",
+        order: str = "asc"
+    ) -> Dict[str, Any]:
+        """
+        Retrieve insights with filtering and pagination.
+
+        Args:
+            subject_ids: List of subject IDs to filter by.
+            topic_ids: List of topic IDs to filter by.
+            insight_types: List of insight types to filter by.
+            entity_id: Entity ID to filter by.
+            entity_representation: Entity representation to filter by.
+            entity_domain: Entity domain(s) to filter by.
+            entity: Entity type to filter by.
+            page: Page number (default 1).
+            size: Number of results per page (default 100).
+            sort_by: Field to sort by.
+            order: Sort direction ("asc" or "desc").
+
+        Returns:
+            Dictionary containing paginated insights.
+        """
+        params = {
+            "page": page,
+            "size": size,
+            "sort_by": sort_by,
+            "order": order
+        }
+        if subject_ids:
+            params["subject_ids"] = subject_ids
+        if topic_ids:
+            params["topic_ids"] = topic_ids
+        if insight_types:
+            params["insight_types"] = insight_types
+        if entity_id:
+            params["entity_id"] = entity_id
+        if entity_representation:
+            params["entity_representation"] = entity_representation
+        if entity_domain:
+            params["entity_domain"] = entity_domain
+        if entity:
+            params["entity"] = entity
+        url = f"{self.base_ontology_url}/insights"
+        return self._get(url, params=params)
+
+    def get_insight_information(self, insight_id: int) -> dict:
+        """
+        Retrieve information for a specific insight.
+
+        Args:
+            insight_id: Insight ID.
+
+        Returns:
+            Dictionary with insight information.
+        """
+        url = f"{self.base_ontology_url}/insights/{insight_id}"
+        return self._get(url)
+
+    def get_insights_for_entity(self, entity_id: int) -> dict:
+        """
+        Retrieve insights for a specific entity.
+        """
+        url = f"{self.base_ontology_url}/entity/{entity_id}/insights"
+        return self._get(url)
+    
+    def get_entities_for_insight(self, insight_id: int) -> dict:
+        """
+        Retrieve entities for a specific insight.
+        """
+        url = f"{self.base_ontology_url}/insight/{insight_id}/entities"
+        return self._get(url)
+    
+    def get_subjects(self) -> dict:
+        """
+        Retrieve all subjects.
+        """
+        url = f"{self.base_ontology_url}/subjects"
+        return self._get(url)
+    
+    def get_topics(self) -> dict:
+        """
+        Retrieve all topics.
+        """
+        url = f"{self.base_ontology_url}/topics"
+        return self._get(url)
+    
+    def get_insights_for_subject(self, subject_id: int) -> dict:
+        """
+        Retrieve insights for a specific subject.
+        """
+        url = f"{self.base_ontology_url}/subject/{subject_id}/insights"
+        return self._get(url)
+    
+    def get_insights_for_topic(self, topic_id: int) -> dict:
+        """
+        Retrieve insights for a specific topic.
+        """
+        url = f"{self.base_ontology_url}/topic/{topic_id}/insights"
+        return self._get(url)
+        
+    def get_ontology_version(self) -> dict:
+        """
+        Retrieve the current ontology version.
+        """
+        url = f"{self.base_ontology_url}/ontology-versions"
+        return self._get(url)
+    
+    def get_ontology_tree(self) -> dict:
+        """
+        Retrieve the ontology tree.
+        """
+        url = f"{self.base_ontology_url}/ontology-tree"
+        return self._get(url)

carbonarc/platform.py

@@ -0,0 +1,62 @@
+from carbonarc.base.client import BaseAPIClient
+
+class PlatformAPIClient(BaseAPIClient):
+    """
+    A client for interacting with the Carbon Arc Platform API.
+    """
+
+    def __init__(
+        self, 
+        token: str,
+        host: str = "https://platform.carbonarc.co",
+        version: str = "v2"
+        ):
+        """
+        Initialize PlatformAPIClient.
+
+        Args:
+            token: Authentication token for requests.
+            host: Base URL of the Carbon Arc API.
+            version: API version to use.
+        """
+        super().__init__(token=token, host=host, version=version)
+        
+        self.base_platform_url = self._build_base_url("clients")
+
+    def get_balance(self) -> dict:
+        """
+        Retrieve balance for the current user.
+        """
+        url = f"{self.base_platform_url}/me/balance"
+        return self._get(url)
+    
+    def get_usage(self) -> dict:
+        """
+        Retrieve usage for the current user.
+        """
+        url = f"{self.base_platform_url}/me/usage"
+        return self._get(url)
+    
+    def get_order_history(self) -> dict:
+        """
+        Retrieve order history.
+
+        Returns:
+            Dictionary of order history.
+        """
+        url = f"{self.base_platform_url}/me/orders"
+        return self._get(url)
+    
+    def get_order_details(self, order_id: str) -> dict:
+        """
+        Retrieve details for a specific order.
+        
+        Args:
+            order_id: ID of the order to retrieve details for.
+
+        Returns:
+            Dictionary of order details.
+        """
+        url = f"{self.base_platform_url}/orders/{order_id}"
+        return self._get(url)
+    

carbonarc-1.0.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Carbon Arc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

carbonarc-1.0.0.dist-info/METADATA

@@ -0,0 +1,56 @@
+Metadata-Version: 2.3
+Name: carbonarc
+Version: 1.0.0
+Summary: Carbon Arc - Python Package
+License: MIT
+Author: Carbon Arc
+Author-email: support@carbonarc.co
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 2
+Classifier: Programming Language :: Python :: 2.7
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.4
+Classifier: Programming Language :: Python :: 3.5
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: Click (>=8.1.7,<9.0.0)
+Requires-Dist: beautifulsoup4 (>=4.12.2,<5.0.0)
+Requires-Dist: pandas (>=2.2.3,<3.0.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Project-URL: Repository, https://github.com/Carbon-Arc/carbonarc.git
+Description-Content-Type: text/markdown
+
+# Carbon Arc - Python Package
+
+Client for [Carbon Arc](https://carbonarc.co/), an Insights Exchange Platform.
+
+## Usage
+
+**Installation**
+
+```bash
+pip install carbonarc
+```
+
+**Quick Start**
+
+Initialize the API client with authentication.
+
+```python
+from carbonarc import CarbonArcClient
+
+client = CarbonArcClient(token="<token>") # retrieve token from account
+```
+
+## Resources
+
+- [Tutorials](https://github.com/Carbon-Arc/carbonarc-tutorials)
+- [Docs](https://docs.carbonarc.co/)
+- [App](https://app.carbonarc.co/)
+- [API](https://api.carbonarc.co/)

carbonarc-1.0.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+carbonarc/__init__.py,sha256=tX_wgnLkNtQbXQLYLf_W4xVmsi4tYY4bSww5FI29LgQ,311
+carbonarc/base/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+carbonarc/base/auth.py,sha256=LEgjCulVKe6MdkL-MemFTxl8lfA5AKHJOuNRDc00sj4,604
+carbonarc/base/client.py,sha256=IeNeFTT83V6b-mPQ-7gQgbtinKG86rdnZ6_XeM_lKmQ,1335
+carbonarc/base/exceptions.py,sha256=9FKbMjTl8h_8x06hMGuV9mmFcfgu_QeNMmouQJmbgi4,807
+carbonarc/base/manager.py,sha256=nnNL44brXUa2LzQM_GGqIu04f1xD5AGKB4rWi9pUh60,3063
+carbonarc/base/utils.py,sha256=IcEqKmusK-0fslopgNMrsoIuqG-zxhgBh8lKZ7DTkXc,1244
+carbonarc/client.py,sha256=w5KdGfuQunIHJw2asfiymh0pS1Ry7WdhiTI5skSAz6g,1174
+carbonarc/data.py,sha256=GicgDfX5vr8KgIZij6uBsV7pmfD1pJZREnkqR7UhQxY,19853
+carbonarc/explorer.py,sha256=wO53AaWnzutucetFkQ4o412ykf1nkXX4bSeYheKhemQ,7525
+carbonarc/hub.py,sha256=HoMyNssHcCQ8ht2DqYvQqZVJYjS1WkvYAV8o3VfmdHQ,1418
+carbonarc/ontology.py,sha256=mkio2bymIQGctyRRTl0vKJnAJW1XmspodgyfE-0NvI0,8060
+carbonarc/platform.py,sha256=y5gnZho3jnqQABYtJxXMyd_sBueCi1PaKOjB4l-MgS4,1669
+carbonarc_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+carbonarc_cli/cli.py,sha256=SZzKn2x7fu-FHGvxFq6aH_Jbjky2cIji7WYMyfTV-vg,1361
+carbonarc-1.0.0.dist-info/LICENSE,sha256=7AvXaWWJUZ9ppCoGEF9ncSKaBYtb5GKppfXFUoV2HxA,1067
+carbonarc-1.0.0.dist-info/METADATA,sha256=HewHOdn7Nn-CMWOV1RkKHh5oVRGwAAgEKcHOuCINwkE,1686
+carbonarc-1.0.0.dist-info/WHEEL,sha256=5druYqcII7zHXzX7qmN0TH895Jg3yuTtfjMgJIVBrKE,92
+carbonarc-1.0.0.dist-info/entry_points.txt,sha256=_TBcw2Akk2E55i8V3DVRvLJ4dvUgVSVaqJlN3SBWIuk,51
+carbonarc-1.0.0.dist-info/RECORD,,

carbonarc-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.1.3
+Root-Is-Purelib: true
+Tag: py2.py3-none-any

carbonarc-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+carbonarc=carbonarc_cli.cli:cli
+