# Carver Feeds SDK
[](https://pypi.org/project/carver-feeds-sdk/)
[](https://opensource.org/licenses/MIT)
A Python SDK for the Carver Feeds API, enabling seamless access to regulatory feed data with querying, filtering, and data analysis capabilities.
## 🎯 Features
- **Comprehensive API Client**: Full support for public Carver Feeds API endpoints with authentication, retry logic, and error handling
- **DataFrame Integration**: Convert API responses to pandas DataFrames for easy data analysis
- **Advanced Query Engine**: Fluent API with method chaining for building complex queries
- **Optimized Performance**: Smart endpoint selection and caching for efficient data access
- **Type Safety**: Full type hints throughout the codebase for better IDE support
- **Production Ready**: Comprehensive error handling, logging, and extensive documentation
## 🏢 About The SDK
This SDK provides programmatic access to [Carver Feeds API](https://app.carveragents.ai/api-docs/), a real-time regulatory intelligence platform. The SDK helps compliance, risk, and legal teams monitor global regulatory developments, track sanctions and mandates, and receive actionable alerts—transforming regulatory monitoring from reactive dashboard checking into proactive intelligence delivery.
## 👥 Who Is This For?
**Compliance teams, risk analysts, and developers** building monitoring tools, compliance dashboards, or automated alert systems for regulatory risk management.
## 💡 Use Cases
- **Regulatory Intelligence**: Track regulatory changes across multiple jurisdictions in real-time
- **Risk Assessment**: Analyze regulatory trends and emerging requirements affecting your business
- **Automated Alerting**: Build systems that notify stakeholders when relevant regulations are published
- **Research & Analysis**: Query historical regulatory data for trend analysis and reporting
## 📦 Installation
```bash
pip install carver-feeds-sdk
```
## 🚀 Quick Start
### 1. Configuration
Create a `.env` file in your project directory:
```bash
CARVER_API_KEY=your_api_key_here
CARVER_BASE_URL=https://app.carveragents.ai # optional
```
### 2. Basic Usage
```python
from dotenv import load_dotenv
from carver_feeds import get_client
load_dotenv()
# Initialize client from environment variables
client = get_client()
# Fetch topics
topics = client.list_topics()
print(f"Found {len(topics)} topics")
# Fetch feeds
feeds = client.list_feeds()
print(f"Found {len(feeds)} feeds")
```
### 3. Using DataFrames
```python
from dotenv import load_dotenv
from carver_feeds import create_data_manager
load_dotenv()
# Create data manager
dm = create_data_manager()
# Get topics as DataFrame
topics_df = dm.get_topics_df()
print(topics_df[['id', 'name', 'is_active']].head())
# Get entries for a specific feed
entries_df = dm.get_entries_df(feed_id="feed-123")
print(f"Found {len(entries_df)} entries")
```
### 4. Advanced Querying
```python
from dotenv import load_dotenv
from carver_feeds import create_query_engine
from datetime import datetime
load_dotenv()
# Create query engine
qe = create_query_engine()
# Build complex query with method chaining
results = qe \
.filter_by_topic(topic_name="Banking") \
.filter_by_date(start_date=datetime(2024, 1, 1)) \
.search_entries("regulation") \
.to_dataframe()
print(f"Found {len(results)} matching entries")
# Export results
qe.to_csv("results.csv")
qe.to_json("results.json")
```
## 🏗️ Core Components
### API Client (`CarverFeedsAPIClient`)
Low-level API client with comprehensive error handling:
- X-API-Key authentication
- Automatic pagination (handles ~10,000+ entries)
- Exponential backoff retry logic for rate limits
- Support for all API endpoints
### Data Manager (`FeedsDataManager`)
Converts API responses to pandas DataFrames:
- JSON to DataFrame conversion with schema validation
- Hierarchical data views (topic → feed → entry)
- Smart endpoint selection for performance
- Handles topics, feeds, entries
### Query Engine (`EntryQueryEngine`)
High-level query interface with fluent API:
- Method chaining for complex queries
- Filter by topic, feed, date range, and status
- Keyword search with AND/OR logic across multiple fields
- Multiple export formats (DataFrame, CSV, JSON, dict)
- Lazy loading with automatic endpoint optimization
## 📊 Data Model
The SDK works with three main entities in a hierarchical structure:
```
Topic (regulatory bodies like SEC, SEBI, RBI, etc.)
↓ 1:N
Feed (RSS feeds for each topic)
↓ 1:N
Entry (individual articles/entries)
```
**Key Fields**:
- **Topic**: `id`, `name`, `description`, `is_active`, timestamps
- **Feed**: `id`, `name`, `url`, `topic_id`, `topic_name`, `is_active`, timestamps
- **Entry**: `id`, `title`, `link`, `content_markdown`, `description`, `published_at`, `feed_id`, `is_active`, timestamps
## ⚡ Advanced Features
### Keyword Search
```python
# Single keyword (case-insensitive by default)
qe.search_entries("regulation").to_dataframe()
# Multiple keywords with OR logic (matches ANY)
qe.search_entries(["regulation", "compliance", "enforcement"], match_all=False)
# Multiple keywords with AND logic (matches ALL)
qe.search_entries(["banking", "regulation"], match_all=True)
# Case-sensitive search
qe.search_entries("SEC", case_sensitive=True)
# Search specific fields
qe.search_entries("fintech", search_fields=['entry_title', 'entry_description'])
```
**Available Search Fields**:
- `entry_content_markdown` (default, full article content)
- `entry_title` (headline)
- `entry_description` (brief summary)
- `entry_link` (URL)
### Hierarchical Views
Build denormalized DataFrames combining topic, feed, and entry data:
```python
from carver_feeds import create_data_manager
dm = create_data_manager()
# Topic + Feed hierarchy (fast, no entries)
hierarchy = dm.get_hierarchical_view(include_entries=False)
# Full hierarchy for a specific feed
full = dm.get_hierarchical_view(include_entries=True, feed_id="feed-456")
# Full hierarchy for a topic (all feeds + entries)
topic_data = dm.get_hierarchical_view(include_entries=True, topic_id="topic-123")
```
## 📚 Documentation
- **[API Reference](https://github.com/carveragents/carver-feeds-sdk/blob/master/docs/api-reference.md)**: Detailed API endpoint and module reference
- **[Usage Examples](https://github.com/carveragents/carver-feeds-sdk/blob/master/docs/examples.md)**: A collection of comprehensive examples covering common workflows
## 📋 Requirements
- Python 3.10 or higher
- pandas >= 2.0.0
- requests >= 2.31.0
- See [pyproject.toml](pyproject.toml) for complete dependency list
## 🔧 Development
### Install for Development
```bash
# Clone repository
git clone https://github.com/carveragents/carver-feeds-sdk.git
cd carver-feeds-sdk
# Create virtual environment
python3.10 -m venv .venv
source .venv/bin/activate
# Install with dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run type checking
mypy src/carver_feeds
# Format code
black src/carver_feeds
ruff check src/carver_feeds
```
### 🚢 Publishing to PyPI
```bash
# Install packaging tools
python -m pip install --upgrade build twine
# Clean old artifacts
rm -rf dist build *.egg-info
# Build source and wheel distributions
python -m build
# Upload to PyPI (use PYPI_API_TOKEN or .pypirc for credentials)
python -m twine upload dist/*
```
### Version Management
We use [`bumpversion`](https://github.com/c4urself/bumpversion) to keep every version reference in sync.
```bash
# Install once (included in dev extras)
python -m pip install bumpversion
# Bump patch/minor/major as needed
bumpversion patch # or minor / major
# Inspect the changes, update CHANGELOG.md, then build + upload
git status
```
The `.bumpversion.cfg` file updates `pyproject.toml`, `src/carver_feeds/__version__.py`, and the SDK version strings in the docs in one command. After bumping, add a new changelog entry with the chosen version before publishing.
### Project Structure
```
carver-feeds-sdk/
├── src/carver_feeds/ # Main package source
│ ├── __init__.py # Public package exports
│ ├── __version__.py # Version metadata
│ ├── carver_api.py # API client
│ ├── data_manager.py # DataFrame construction helpers
│ ├── query_engine.py # Query interface
│ └── py.typed # PEP 561 marker for type checking
├── tests/ # Test suite
├── docs/ # Documentation
├── examples/ # Example scripts
├── CHANGELOG.md # Release notes
├── MANIFEST.in # Source distribution manifest
└── pyproject.toml # Package configuration
```
## 📈 Performance Optimization
### 1. Filter Before Loading
The query engine automatically uses optimized endpoints when you filter before loading data:
```python
# Optimal: Query engine uses get_topic_entries() endpoint
qe = create_query_engine()
results = qe.filter_by_topic(topic_name="Banking").to_dataframe()
# Optimal: Query engine uses get_feed_entries() endpoint
results = qe.filter_by_feed(feed_name="SEC News").to_dataframe()
# Less optimal: Loads all ~10,000 entries, then filters
results = qe.to_dataframe() # Loads everything first
filtered = results[results['topic_name'].str.contains("Banking")]
```
### 2. Chain Filters Efficiently
Apply filters in order of specificity (narrowest first):
```python
# Good: Narrow by topic first, then apply other filters
results = qe \
.filter_by_topic(topic_name="Banking") \
.filter_by_date(start_date=datetime(2024, 1, 1)) \
.search_entries("regulation") \
.to_dataframe()
```
### 3. Reuse Query Engine
Data is cached after the first load:
```python
qe = create_query_engine()
# First query: loads data from API (~30-60 seconds for all entries)
results1 = qe.filter_by_topic(topic_name="Banking").to_dataframe()
# Subsequent queries: use cached data (instant)
results2 = qe.chain().filter_by_topic(topic_name="Healthcare").to_dataframe()
```
### 4. Use Data Manager for Simple Queries
For simple filtering without complex logic, use the Data Manager directly:
```python
# Faster for simple use cases
dm = create_data_manager()
entries = dm.get_entries_df(feed_id='feed-456') # Direct endpoint call
```
## ⚠️ Error Handling
The SDK provides specific exception types for different error scenarios:
```python
from carver_feeds import get_client, CarverAPIError, AuthenticationError, RateLimitError
try:
client = get_client()
topics = client.list_topics()
except AuthenticationError:
print("Invalid API key. Check your .env file.")
except RateLimitError:
print("Rate limit exceeded. Please wait before retrying.")
except CarverAPIError as e:
print(f"API error: {e}")
```
## ✅ Best Practices
1. **Use factory functions** for automatic environment configuration:
```python
from carver_feeds import get_client, create_data_manager, create_query_engine
client = get_client() # Automatically loads from .env
dm = create_data_manager()
qe = create_query_engine()
```
2. **Choose the right component** for your use case:
- **API Client**: Raw API responses, specific control over requests
- **Data Manager**: Simple DataFrame operations without complex filtering
- **Query Engine**: Complex queries with multiple filters and chaining
3. **Handle errors gracefully**:
```python
from carver_feeds import create_query_engine, CarverAPIError
try:
qe = create_query_engine()
results = qe.filter_by_topic(topic_name="Banking").to_dataframe()
if len(results) == 0:
print("No results found. Try broadening search criteria.")
except CarverAPIError as e:
print(f"API error: {e}")
```
4. **Export large result sets** to CSV for external processing:
```python
# For large datasets, export rather than keeping in memory
results = qe.filter_by_topic(topic_name="Banking")
results.to_csv("banking_entries.csv") # Saves ~50-100 MB to disk
```
## 🤝 Contributing
We welcome contributions! Please follow these guidelines:
1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run the test suite and type checking
5. Submit a pull request
## 💬 Support
For issues, questions, or feature requests:
- **API Reference**: [docs/api-reference.md](https://github.com/carveragents/carver-feeds-sdk/blob/master/docs/api-reference.md)
- **Examples**: [docs/examples.md](https://github.com/carveragents/carver-feeds-sdk/blob/master/docs/examples.md)
- **Issues**: [GitHub Issues](https://github.com/carveragents/carver-feeds-sdk/issues)
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 📝 Changelog
See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.
---
**Note**: This SDK requires a valid Carver API key. Visit [Carver Agents](https://carveragents.ai) to obtain your API key.
Raw data
{
"_id": null,
"home_page": null,
"name": "carver-feeds-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "carver, feeds, api, regulations, data, sdk, regulatory intelligence, risk management, real-time intelligence, risk assessment, compliance monitoring",
"author": null,
"author_email": "Carver Agents <support@carveragents.ai>",
"download_url": null,
"platform": null,
"description": "# Carver Feeds SDK\n\n\n[](https://pypi.org/project/carver-feeds-sdk/)\n[](https://opensource.org/licenses/MIT)\n\nA Python SDK for the Carver Feeds API, enabling seamless access to regulatory feed data with querying, filtering, and data analysis capabilities.\n\n## \ud83c\udfaf Features\n\n- **Comprehensive API Client**: Full support for public Carver Feeds API endpoints with authentication, retry logic, and error handling\n- **DataFrame Integration**: Convert API responses to pandas DataFrames for easy data analysis\n- **Advanced Query Engine**: Fluent API with method chaining for building complex queries\n- **Optimized Performance**: Smart endpoint selection and caching for efficient data access\n- **Type Safety**: Full type hints throughout the codebase for better IDE support\n- **Production Ready**: Comprehensive error handling, logging, and extensive documentation\n\n## \ud83c\udfe2 About The SDK\n\nThis SDK provides programmatic access to [Carver Feeds API](https://app.carveragents.ai/api-docs/), a real-time regulatory intelligence platform. The SDK helps compliance, risk, and legal teams monitor global regulatory developments, track sanctions and mandates, and receive actionable alerts\u2014transforming regulatory monitoring from reactive dashboard checking into proactive intelligence delivery.\n\n## \ud83d\udc65 Who Is This For?\n\n**Compliance teams, risk analysts, and developers** building monitoring tools, compliance dashboards, or automated alert systems for regulatory risk management.\n\n## \ud83d\udca1 Use Cases\n\n- **Regulatory Intelligence**: Track regulatory changes across multiple jurisdictions in real-time\n- **Risk Assessment**: Analyze regulatory trends and emerging requirements affecting your business\n- **Automated Alerting**: Build systems that notify stakeholders when relevant regulations are published\n- **Research & Analysis**: Query historical regulatory data for trend analysis and reporting\n\n## \ud83d\udce6 Installation\n\n```bash\npip install carver-feeds-sdk\n```\n\n## \ud83d\ude80 Quick Start\n\n### 1. Configuration\n\nCreate a `.env` file in your project directory:\n\n```bash\nCARVER_API_KEY=your_api_key_here\nCARVER_BASE_URL=https://app.carveragents.ai # optional\n```\n\n### 2. Basic Usage\n\n```python\n\nfrom dotenv import load_dotenv\nfrom carver_feeds import get_client\n\nload_dotenv()\n\n# Initialize client from environment variables\nclient = get_client()\n\n# Fetch topics\ntopics = client.list_topics()\nprint(f\"Found {len(topics)} topics\")\n\n# Fetch feeds\nfeeds = client.list_feeds()\nprint(f\"Found {len(feeds)} feeds\")\n```\n\n### 3. Using DataFrames\n\n```python\nfrom dotenv import load_dotenv\nfrom carver_feeds import create_data_manager\n\nload_dotenv()\n\n# Create data manager\ndm = create_data_manager()\n\n# Get topics as DataFrame\ntopics_df = dm.get_topics_df()\nprint(topics_df[['id', 'name', 'is_active']].head())\n\n# Get entries for a specific feed\nentries_df = dm.get_entries_df(feed_id=\"feed-123\")\nprint(f\"Found {len(entries_df)} entries\")\n```\n\n### 4. Advanced Querying\n\n```python\nfrom dotenv import load_dotenv\nfrom carver_feeds import create_query_engine\nfrom datetime import datetime\n\nload_dotenv()\n\n# Create query engine\nqe = create_query_engine()\n\n# Build complex query with method chaining\nresults = qe \\\n .filter_by_topic(topic_name=\"Banking\") \\\n .filter_by_date(start_date=datetime(2024, 1, 1)) \\\n .search_entries(\"regulation\") \\\n .to_dataframe()\n\nprint(f\"Found {len(results)} matching entries\")\n\n# Export results\nqe.to_csv(\"results.csv\")\nqe.to_json(\"results.json\")\n```\n\n## \ud83c\udfd7\ufe0f Core Components\n\n### API Client (`CarverFeedsAPIClient`)\n\nLow-level API client with comprehensive error handling:\n\n- X-API-Key authentication\n- Automatic pagination (handles ~10,000+ entries)\n- Exponential backoff retry logic for rate limits\n- Support for all API endpoints\n\n### Data Manager (`FeedsDataManager`)\n\nConverts API responses to pandas DataFrames:\n\n- JSON to DataFrame conversion with schema validation\n- Hierarchical data views (topic \u2192 feed \u2192 entry)\n- Smart endpoint selection for performance\n- Handles topics, feeds, entries\n\n### Query Engine (`EntryQueryEngine`)\n\nHigh-level query interface with fluent API:\n\n- Method chaining for complex queries\n- Filter by topic, feed, date range, and status\n- Keyword search with AND/OR logic across multiple fields\n- Multiple export formats (DataFrame, CSV, JSON, dict)\n- Lazy loading with automatic endpoint optimization\n\n## \ud83d\udcca Data Model\n\nThe SDK works with three main entities in a hierarchical structure:\n\n```\nTopic (regulatory bodies like SEC, SEBI, RBI, etc.)\n \u2193 1:N\nFeed (RSS feeds for each topic)\n \u2193 1:N\nEntry (individual articles/entries)\n```\n\n**Key Fields**:\n- **Topic**: `id`, `name`, `description`, `is_active`, timestamps\n- **Feed**: `id`, `name`, `url`, `topic_id`, `topic_name`, `is_active`, timestamps\n- **Entry**: `id`, `title`, `link`, `content_markdown`, `description`, `published_at`, `feed_id`, `is_active`, timestamps\n\n## \u26a1 Advanced Features\n\n### Keyword Search\n\n```python\n# Single keyword (case-insensitive by default)\nqe.search_entries(\"regulation\").to_dataframe()\n\n# Multiple keywords with OR logic (matches ANY)\nqe.search_entries([\"regulation\", \"compliance\", \"enforcement\"], match_all=False)\n\n# Multiple keywords with AND logic (matches ALL)\nqe.search_entries([\"banking\", \"regulation\"], match_all=True)\n\n# Case-sensitive search\nqe.search_entries(\"SEC\", case_sensitive=True)\n\n# Search specific fields\nqe.search_entries(\"fintech\", search_fields=['entry_title', 'entry_description'])\n```\n\n**Available Search Fields**:\n- `entry_content_markdown` (default, full article content)\n- `entry_title` (headline)\n- `entry_description` (brief summary)\n- `entry_link` (URL)\n\n### Hierarchical Views\n\nBuild denormalized DataFrames combining topic, feed, and entry data:\n\n```python\nfrom carver_feeds import create_data_manager\n\ndm = create_data_manager()\n\n# Topic + Feed hierarchy (fast, no entries)\nhierarchy = dm.get_hierarchical_view(include_entries=False)\n\n# Full hierarchy for a specific feed\nfull = dm.get_hierarchical_view(include_entries=True, feed_id=\"feed-456\")\n\n# Full hierarchy for a topic (all feeds + entries)\ntopic_data = dm.get_hierarchical_view(include_entries=True, topic_id=\"topic-123\")\n```\n\n## \ud83d\udcda Documentation\n\n- **[API Reference](https://github.com/carveragents/carver-feeds-sdk/blob/master/docs/api-reference.md)**: Detailed API endpoint and module reference\n- **[Usage Examples](https://github.com/carveragents/carver-feeds-sdk/blob/master/docs/examples.md)**: A collection of comprehensive examples covering common workflows\n\n## \ud83d\udccb Requirements\n\n- Python 3.10 or higher\n- pandas >= 2.0.0\n- requests >= 2.31.0\n- See [pyproject.toml](pyproject.toml) for complete dependency list\n\n## \ud83d\udd27 Development\n\n### Install for Development\n\n```bash\n# Clone repository\ngit clone https://github.com/carveragents/carver-feeds-sdk.git\ncd carver-feeds-sdk\n\n# Create virtual environment\npython3.10 -m venv .venv\nsource .venv/bin/activate\n\n# Install with dev dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run type checking\nmypy src/carver_feeds\n\n# Format code\nblack src/carver_feeds\nruff check src/carver_feeds\n```\n\n### \ud83d\udea2 Publishing to PyPI\n\n```bash\n# Install packaging tools\npython -m pip install --upgrade build twine\n\n# Clean old artifacts\nrm -rf dist build *.egg-info\n\n# Build source and wheel distributions\npython -m build\n\n# Upload to PyPI (use PYPI_API_TOKEN or .pypirc for credentials)\npython -m twine upload dist/*\n```\n\n### Version Management\n\nWe use [`bumpversion`](https://github.com/c4urself/bumpversion) to keep every version reference in sync.\n\n```bash\n# Install once (included in dev extras)\npython -m pip install bumpversion\n\n# Bump patch/minor/major as needed\nbumpversion patch # or minor / major\n\n# Inspect the changes, update CHANGELOG.md, then build + upload\ngit status\n```\n\nThe `.bumpversion.cfg` file updates `pyproject.toml`, `src/carver_feeds/__version__.py`, and the SDK version strings in the docs in one command. After bumping, add a new changelog entry with the chosen version before publishing.\n\n### Project Structure\n\n```\ncarver-feeds-sdk/\n\u251c\u2500\u2500 src/carver_feeds/ # Main package source\n\u2502 \u251c\u2500\u2500 __init__.py # Public package exports\n\u2502 \u251c\u2500\u2500 __version__.py # Version metadata\n\u2502 \u251c\u2500\u2500 carver_api.py # API client\n\u2502 \u251c\u2500\u2500 data_manager.py # DataFrame construction helpers\n\u2502 \u251c\u2500\u2500 query_engine.py # Query interface\n\u2502 \u2514\u2500\u2500 py.typed # PEP 561 marker for type checking\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 docs/ # Documentation\n\u251c\u2500\u2500 examples/ # Example scripts\n\u251c\u2500\u2500 CHANGELOG.md # Release notes\n\u251c\u2500\u2500 MANIFEST.in # Source distribution manifest\n\u2514\u2500\u2500 pyproject.toml # Package configuration\n```\n\n## \ud83d\udcc8 Performance Optimization\n\n### 1. Filter Before Loading\n\nThe query engine automatically uses optimized endpoints when you filter before loading data:\n\n```python\n# Optimal: Query engine uses get_topic_entries() endpoint\nqe = create_query_engine()\nresults = qe.filter_by_topic(topic_name=\"Banking\").to_dataframe()\n\n# Optimal: Query engine uses get_feed_entries() endpoint\nresults = qe.filter_by_feed(feed_name=\"SEC News\").to_dataframe()\n\n# Less optimal: Loads all ~10,000 entries, then filters\nresults = qe.to_dataframe() # Loads everything first\nfiltered = results[results['topic_name'].str.contains(\"Banking\")]\n```\n\n### 2. Chain Filters Efficiently\n\nApply filters in order of specificity (narrowest first):\n\n```python\n# Good: Narrow by topic first, then apply other filters\nresults = qe \\\n .filter_by_topic(topic_name=\"Banking\") \\\n .filter_by_date(start_date=datetime(2024, 1, 1)) \\\n .search_entries(\"regulation\") \\\n .to_dataframe()\n```\n\n### 3. Reuse Query Engine\n\nData is cached after the first load:\n\n```python\nqe = create_query_engine()\n\n# First query: loads data from API (~30-60 seconds for all entries)\nresults1 = qe.filter_by_topic(topic_name=\"Banking\").to_dataframe()\n\n# Subsequent queries: use cached data (instant)\nresults2 = qe.chain().filter_by_topic(topic_name=\"Healthcare\").to_dataframe()\n```\n\n### 4. Use Data Manager for Simple Queries\n\nFor simple filtering without complex logic, use the Data Manager directly:\n\n```python\n# Faster for simple use cases\ndm = create_data_manager()\nentries = dm.get_entries_df(feed_id='feed-456') # Direct endpoint call\n```\n\n## \u26a0\ufe0f Error Handling\n\nThe SDK provides specific exception types for different error scenarios:\n\n```python\nfrom carver_feeds import get_client, CarverAPIError, AuthenticationError, RateLimitError\n\ntry:\n client = get_client()\n topics = client.list_topics()\nexcept AuthenticationError:\n print(\"Invalid API key. Check your .env file.\")\nexcept RateLimitError:\n print(\"Rate limit exceeded. Please wait before retrying.\")\nexcept CarverAPIError as e:\n print(f\"API error: {e}\")\n```\n\n## \u2705 Best Practices\n\n1. **Use factory functions** for automatic environment configuration:\n ```python\n from carver_feeds import get_client, create_data_manager, create_query_engine\n\n client = get_client() # Automatically loads from .env\n dm = create_data_manager()\n qe = create_query_engine()\n ```\n\n2. **Choose the right component** for your use case:\n - **API Client**: Raw API responses, specific control over requests\n - **Data Manager**: Simple DataFrame operations without complex filtering\n - **Query Engine**: Complex queries with multiple filters and chaining\n\n3. **Handle errors gracefully**:\n ```python\n from carver_feeds import create_query_engine, CarverAPIError\n\n try:\n qe = create_query_engine()\n results = qe.filter_by_topic(topic_name=\"Banking\").to_dataframe()\n\n if len(results) == 0:\n print(\"No results found. Try broadening search criteria.\")\n except CarverAPIError as e:\n print(f\"API error: {e}\")\n ```\n\n4. **Export large result sets** to CSV for external processing:\n ```python\n # For large datasets, export rather than keeping in memory\n results = qe.filter_by_topic(topic_name=\"Banking\")\n results.to_csv(\"banking_entries.csv\") # Saves ~50-100 MB to disk\n ```\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please follow these guidelines:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes with tests\n4. Run the test suite and type checking\n5. Submit a pull request\n\n## \ud83d\udcac Support\n\nFor issues, questions, or feature requests:\n\n- **API Reference**: [docs/api-reference.md](https://github.com/carveragents/carver-feeds-sdk/blob/master/docs/api-reference.md)\n- **Examples**: [docs/examples.md](https://github.com/carveragents/carver-feeds-sdk/blob/master/docs/examples.md)\n- **Issues**: [GitHub Issues](https://github.com/carveragents/carver-feeds-sdk/issues)\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udcdd Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history and release notes.\n\n---\n\n**Note**: This SDK requires a valid Carver API key. Visit [Carver Agents](https://carveragents.ai) to obtain your API key.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for the Carver Feeds API - fetch, analyze, and query regulatory feed data",
"version": "0.1.2",
"project_urls": {
"Documentation": "https://github.com/carveragents/carver-feeds-sdk/blob/master/README.md",
"Homepage": "https://github.com/carveragents/carver-feeds-sdk",
"Issues": "https://github.com/carveragents/carver-feeds-sdk/issues",
"Repository": "https://github.com/carveragents/carver-feeds-sdk"
},
"split_keywords": [
"carver",
" feeds",
" api",
" regulations",
" data",
" sdk",
" regulatory intelligence",
" risk management",
" real-time intelligence",
" risk assessment",
" compliance monitoring"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f091d49c8031882581dc748363c3b7947620b9c18d39638871bc31dab1facf23",
"md5": "057d28697a71293092876612824d2b43",
"sha256": "4bfb6645137d23458570366badc6189759529bd98574701ed6dffe4bdd4b4af9"
},
"downloads": -1,
"filename": "carver_feeds_sdk-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "057d28697a71293092876612824d2b43",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 23778,
"upload_time": "2025-10-28T16:46:46",
"upload_time_iso_8601": "2025-10-28T16:46:46.522359Z",
"url": "https://files.pythonhosted.org/packages/f0/91/d49c8031882581dc748363c3b7947620b9c18d39638871bc31dab1facf23/carver_feeds_sdk-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-28 16:46:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "carveragents",
"github_project": "carver-feeds-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "carver-feeds-sdk"
}
JSON
