cite-agent 1.3.9__py3-none-any.whl → 1.4.3__py3-none-any.whl

cite_agent/unpaywall_client.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""
+Unpaywall Integration - Find Legal Open Access PDFs
+Unpaywall.org provides free, legal access to millions of research papers
+"""
+
+import logging
+from typing import Optional, Dict, Any
+import aiohttp
+import asyncio
+
+logger = logging.getLogger(__name__)
+
+
+class UnpaywallClient:
+    """
+    Client for Unpaywall API - finds legal open access versions of papers
+
+    Unpaywall indexes 30M+ open access papers from:
+    - University repositories
+    - Author websites
+    - Preprint servers (arXiv, bioRxiv)
+    - Journal websites
+
+    Usage:
+        client = UnpaywallClient(email="your@email.edu")
+        pdf_url = await client.get_pdf_url(doi="10.1234/example")
+    """
+
+    BASE_URL = "https://api.unpaywall.org/v2"
+
+    def __init__(self, email: str = "research@cite-agent.com"):
+        """
+        Initialize Unpaywall client
+
+        Args:
+            email: Your email (required by Unpaywall API for rate limiting)
+        """
+        self.email = email
+        self.timeout = aiohttp.ClientTimeout(total=10)
+
+    async def get_pdf_url(self, doi: str) -> Optional[str]:
+        """
+        Get free, legal PDF URL for a paper by DOI
+
+        Args:
+            doi: DOI of the paper (e.g., "10.1016/j.cell.2023.01.001")
+
+        Returns:
+            PDF URL if open access version exists, None otherwise
+
+        Example:
+            >>> client = UnpaywallClient()
+            >>> url = await client.get_pdf_url("10.1371/journal.pone.0000001")
+            >>> print(url)
+            'https://journals.plos.org/plosone/article/file?id=10.1371/...'
+        """
+        try:
+            # Clean DOI
+            doi = doi.strip().replace("https://doi.org/", "")
+
+            url = f"{self.BASE_URL}/{doi}"
+            params = {"email": self.email}
+
+            async with aiohttp.ClientSession(timeout=self.timeout) as session:
+                async with session.get(url, params=params) as response:
+                    if response.status == 404:
+                        logger.debug(f"DOI not found in Unpaywall: {doi}")
+                        return None
+
+                    if response.status != 200:
+                        logger.warning(f"Unpaywall API error {response.status} for DOI: {doi}")
+                        return None
+
+                    data = await response.json()
+                    return self._extract_best_pdf_url(data)
+
+        except asyncio.TimeoutError:
+            logger.warning(f"Unpaywall timeout for DOI: {doi}")
+            return None
+        except Exception as e:
+            logger.error(f"Unpaywall error for DOI {doi}: {e}")
+            return None
+
+    async def get_full_metadata(self, doi: str) -> Optional[Dict[str, Any]]:
+        """
+        Get full metadata including all OA locations
+
+        Returns:
+            {
+                'is_oa': bool,
+                'best_oa_location': {...},
+                'oa_locations': [...],
+                'doi': str,
+                'title': str,
+                'year': int,
+                ...
+            }
+        """
+        try:
+            doi = doi.strip().replace("https://doi.org/", "")
+            url = f"{self.BASE_URL}/{doi}"
+            params = {"email": self.email}
+
+            async with aiohttp.ClientSession(timeout=self.timeout) as session:
+                async with session.get(url, params=params) as response:
+                    if response.status != 200:
+                        return None
+                    return await response.json()
+
+        except Exception as e:
+            logger.error(f"Unpaywall metadata error: {e}")
+            return None
+
+    def _extract_best_pdf_url(self, unpaywall_data: Dict[str, Any]) -> Optional[str]:
+        """
+        Extract the best PDF URL from Unpaywall response
+        Preference: publisher version > accepted manuscript > submitted manuscript
+        """
+        if not unpaywall_data.get('is_oa'):
+            return None
+
+        # Try best OA location first
+        best_location = unpaywall_data.get('best_oa_location')
+        if best_location:
+            pdf_url = best_location.get('url_for_pdf') or best_location.get('url')
+            if pdf_url and pdf_url.endswith('.pdf'):
+                return pdf_url
+
+        # Try all OA locations
+        oa_locations = unpaywall_data.get('oa_locations', [])
+        for location in oa_locations:
+            # Prefer publisher or repository versions
+            version = location.get('version', '')
+            if version in ('publishedVersion', 'acceptedVersion'):
+                pdf_url = location.get('url_for_pdf') or location.get('url')
+                if pdf_url:
+                    return pdf_url
+
+        # Fallback: any PDF URL
+        for location in oa_locations:
+            pdf_url = location.get('url_for_pdf') or location.get('url')
+            if pdf_url:
+                return pdf_url
+
+        return None
+
+    async def batch_get_pdfs(self, dois: list[str]) -> Dict[str, Optional[str]]:
+        """
+        Get PDF URLs for multiple DOIs in parallel
+
+        Args:
+            dois: List of DOIs
+
+        Returns:
+            Dict mapping DOI -> PDF URL (or None if not available)
+
+        Example:
+            >>> client = UnpaywallClient()
+            >>> dois = ["10.1371/journal.pone.0000001", "10.1038/s41586-023-06221-2"]
+            >>> results = await client.batch_get_pdfs(dois)
+            >>> print(results)
+            {
+                '10.1371/journal.pone.0000001': 'https://...',
+                '10.1038/s41586-023-06221-2': None  # Paywalled
+            }
+        """
+        tasks = [self.get_pdf_url(doi) for doi in dois]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        output = {}
+        for doi, result in zip(dois, results):
+            if isinstance(result, Exception):
+                output[doi] = None
+            else:
+                output[doi] = result
+
+        return output
+
+    async def check_availability(self, doi: str) -> Dict[str, Any]:
+        """
+        Check if paper is available and get status
+
+        Returns:
+            {
+                'is_available': bool,
+                'access_type': str,  # 'open_access' | 'paywalled' | 'unknown'
+                'pdf_url': str | None,
+                'version': str | None,  # 'publishedVersion' | 'acceptedVersion' | etc
+                'license': str | None
+            }
+        """
+        metadata = await self.get_full_metadata(doi)
+
+        if not metadata:
+            return {
+                'is_available': False,
+                'access_type': 'unknown',
+                'pdf_url': None,
+                'version': None,
+                'license': None
+            }
+
+        is_oa = metadata.get('is_oa', False)
+        best_location = metadata.get('best_oa_location')
+
+        if is_oa and best_location:
+            return {
+                'is_available': True,
+                'access_type': 'open_access',
+                'pdf_url': self._extract_best_pdf_url(metadata),
+                'version': best_location.get('version'),
+                'license': best_location.get('license')
+            }
+        else:
+            return {
+                'is_available': False,
+                'access_type': 'paywalled',
+                'pdf_url': None,
+                'version': None,
+                'license': None
+            }
+
+
+# Global instance
+unpaywall = UnpaywallClient()

{cite_agent-1.3.9.dist-info → cite_agent-1.4.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cite-agent
-Version: 1.3.9
+Version: 1.4.3
 Summary: Terminal AI assistant for academic research with citation verification
 Home-page: https://github.com/Spectating101/cite-agent
 Author: Cite-Agent Team
@@ -194,6 +194,11 @@ cite-agent "我的p值是0.05，這顯著嗎？"
 cite-agent "天空是藍色的嗎？"
 ```
 
+#### Runtime Controls
+
+- Responses render immediately—there’s no artificial typing delay.
+- Press `Ctrl+C` while the agent is thinking or streaming to interrupt and ask a different question on the spot.
+
 ### Python API Reference
 
 #### EnhancedNocturnalAgent
@@ -436,6 +441,15 @@ export NOCTURNAL_DEBUG=1
 cite-agent "your query"
 ```
 
+### Documentation
+
+For developers and contributors:
+- **[SYSTEM_STATUS.md](SYSTEM_STATUS.md)** - Current system status, test results, how to run
+- **[ARCHITECTURE_EXPLAINED.md](ARCHITECTURE_EXPLAINED.md)** - Why the codebase is complex
+- **[CHANGELOG.md](CHANGELOG.md)** - Version history and changes
+- **[INSTALL.md](INSTALL.md)** - Detailed installation instructions
+- **[TESTING.md](TESTING.md)** - How to run tests
+
 ### Support
 
 - **Documentation**: [Full docs](https://docs.cite-agent.com)

cite_agent-1.4.3.dist-info/RECORD

@@ -0,0 +1,62 @@
+cite_agent/__init__.py,sha256=HAm9GEsbvdyGpF0tV5vygG5RjSF9k7sDiyh4SO-QxKo,1634
+cite_agent/__main__.py,sha256=6x3lltwG-iZHeQbN12rwvdkPDfd2Rmdk71tOOaC89Mw,179
+cite_agent/__version__.py,sha256=BqOI5y46o1G1RWC9bF1DPL-YM68lGYPmZt1pn6FZFZs,22
+cite_agent/account_client.py,sha256=yLuzhIJoIZuXHXGbaVMzDxRATQwcy-wiaLnUrDuwUhI,5725
+cite_agent/action_first_mode.py,sha256=-ntbEzT1kdgjTKDmnoyS93LzEmfrxr0Pdu6QQ5aHqUo,5312
+cite_agent/adaptive_providers.py,sha256=kfO-8fN9IyCE61zyDpQn3dck2h5ZgQ3ghLI2NnA2JUw,15740
+cite_agent/agent_backend_only.py,sha256=H4DH4hmKhT0T3rQLAb2xnnJVjxl3pOZaljL9r6JndFY,6314
+cite_agent/archive_api_client.py,sha256=Az0ts2LN9tzgeHMOkj2zXRAOqElIo4BGrzry8FwPsEA,5921
+cite_agent/ascii_plotting.py,sha256=lk8BaECs6fmjtp4iH12G09-frlRehAN7HLhHt2crers,8570
+cite_agent/auth.py,sha256=5EveDbJ_j5U78HmQE9CCkEwXT8hRCVg29wzTLB8KmM0,9793
+cite_agent/auto_expander.py,sha256=xoHH8hX8th49TISQGyKPGLJk0Dn-KgKkbcXFPKvjMPw,2501
+cite_agent/backend_only_client.py,sha256=WqLF8x7aXTro2Q3ehqKMsdCg53s6fNk9Hy86bGxqmmw,2561
+cite_agent/cache.py,sha256=1fs97FAf6r-xGgUHQ3CCvhP5y0DDH86bUc0apMDUHBc,11591
+cite_agent/circuit_breaker.py,sha256=igET6Sz0hHaRZlBjNJi6qp714Ng7VGCzq4Fpdv_8qqQ,13159
+cite_agent/citation_network.py,sha256=EyFIeYdr8aHmxMUNPEnPH4DRe0ScTAp6Qn5T_xDmCLQ,13194
+cite_agent/cli.py,sha256=yKXLEX2LliTZpvNdwf7EadfN7uwTUNw8O2KsBKQxHok,42741
+cite_agent/cli_conversational.py,sha256=U3DiFE8Is8jZCQpR2fiMUGc7uJUAVALUOsTGusUSQBU,15002
+cite_agent/cli_enhanced.py,sha256=EAaSw9qtiYRWUXF6_05T19GCXlz9cCSz6n41ASnXIPc,7407
+cite_agent/cli_workflow.py,sha256=4oS_jW9D8ylovXbEFdsyLQONt4o0xxR4Xatfcc4tnBs,11641
+cite_agent/confidence_calibration.py,sha256=3c5uHl_czs2xcO-COOco8t0WNPfuXgMHTHoSjOirxOc,12720
+cite_agent/conversation_archive.py,sha256=FV1EpcYTc732Oc5oc7EbrpaxUQkSNxP-KCEKbr8k2GA,4965
+cite_agent/dashboard.py,sha256=VGV5XQU1PnqvTsxfKMcue3j2ri_nvm9Be6O5aVays_w,10502
+cite_agent/deduplication.py,sha256=eXMA65U7pO2tQWmRbrA1oFoYsSsPaSNVxFkt--rQnZg,9824
+cite_agent/enhanced_ai_agent.py,sha256=xyGbyYuSC-3ZXPIpVPmQ1sYfVU57DDDX-ImSSXZjuvQ,259657
+cite_agent/error_handler.py,sha256=fFNNzfOnicsbVkYNj-NZZj8JuFuVi_PzT_ig8ucG-30,9598
+cite_agent/execution_safety.py,sha256=T6zS9_tmLwDa0aGGnGm06-T59KcS7o8PQpoBQkrrgy0,11732
+cite_agent/full_paper_reader.py,sha256=3UWpahwu9d55HCpOwcLBJvjfoj2lBV8xm-atIsMBAEM,9019
+cite_agent/observability.py,sha256=U8ha4jT7ih0dl6_tIlSr6xz68MHrR3N69xt4eBNveRg,14479
+cite_agent/offline_mode.py,sha256=dfY4dzsHVC4VWdcIIS_5vB-w_DA3Cgmk-MoA4-rR_6g,10969
+cite_agent/paper_comparator.py,sha256=RcHn2V07VOKP9yamCTbEiQbOfcFb2lXuZ672pnsd6q8,12631
+cite_agent/paper_summarizer.py,sha256=uxJg1RupDMSgok5omAnBy3OH4MsXbauTljwklJum8ak,14220
+cite_agent/pdf_extractor.py,sha256=-BElF6Vvl-XoZ3a_RwxIcs6Aqvp3UOpSapHGIJidTqA,12643
+cite_agent/proactive_boundaries.py,sha256=r1UFzFuukHzPKi1Yp1PBRgE4HGRV8SLmDPZBn9ZiEDY,8129
+cite_agent/project_detector.py,sha256=fPl5cLTy_oyufqrQ7RJ5IRVdofZoPqDRaQXW6tRtBJc,6086
+cite_agent/quality_gate.py,sha256=LLVL7c-jVw5G7Iu7P6jazgtt-N5KHlVtmzVGiQBzEAM,15194
+cite_agent/rate_limiter.py,sha256=-0fXx8Tl4zVB4O28n9ojU2weRo-FBF1cJo9Z5jC2LxQ,10908
+cite_agent/request_queue.py,sha256=wvC4mNw-K39tnFiMun9Ii2icZ-1xnacbkfUiVU_-424,13684
+cite_agent/response_enhancer.py,sha256=NwUkAMmbYhuW3JTAy2jz8CADdnviOPfkwYxm_a04pM4,9228
+cite_agent/response_formatter.py,sha256=Do5VhqTHC7L7e-wBGgrySXCx8UlUVKjC_F9Qw6sP-fk,14108
+cite_agent/response_pipeline.py,sha256=ktjOvfAHNlIMKi_Wn__-kzL60XfTZEtHt61YZybAWlA,10719
+cite_agent/response_style_enhancer.py,sha256=6jKdP4HjJ3_BNi-ryAmmAh14VSQPqZ-cFRjBbaEQGB0,9577
+cite_agent/self_healing.py,sha256=fkqprNNB47RFA7ZkgcqPbllHl2VlWl7r7Z9LLunV_3A,15145
+cite_agent/session_manager.py,sha256=B0MXSOsXdhO3DlvTG7S8x6pmGlYEDvIZ-o8TZM23niQ,9444
+cite_agent/setup_config.py,sha256=3m2e3gw0srEWA0OygdRo64r-8HK5ohyXfct0c__CF3s,16817
+cite_agent/similarity_finder.py,sha256=AWQv4n_PnKB5CW9eTcp1Qcz53jz7MMhyM6i_2zT_E4Q,18219
+cite_agent/streaming_ui.py,sha256=7MoiXvwzkoB8-TnvEU658gqKJgQVG_PuzNMCc9JH_iM,8005
+cite_agent/telemetry.py,sha256=55kXdHvI24ZsEkbFtihcjIfJt2oiSXcEpLzTxQ3KCdQ,2916
+cite_agent/thinking_blocks.py,sha256=Jseqv_y9VoV4KoVfQUSDDwd4orRPG6vnLq-aiqyXu3M,10375
+cite_agent/tool_orchestrator.py,sha256=Bgd70gtvLOYEyx0prFiKR9EYRqsDZroJR0vJG2dxT80,13538
+cite_agent/trend_analyzer.py,sha256=rdaAq0WN4DoJ6hTLOCKCavVXcuINBgrlug8OFQBzUO4,18900
+cite_agent/ui.py,sha256=r1OAeY3NSeqhAjJYmEBH9CaennBuibFAz1Mur6YF80E,6134
+cite_agent/unpaywall_client.py,sha256=sBw4ienLbzF8HMZw_hKHCiqFoXOVvOj-Jt5r1aBnmCs,7395
+cite_agent/updater.py,sha256=udoAAN4gBKAvKDV7JTh2FJO_jIhNk9bby4x6n188MEY,8458
+cite_agent/web_search.py,sha256=FZCuNO7MAITiOIbpPbJyt2bzbXPzQla-9amJpnMpW_4,6520
+cite_agent/workflow.py,sha256=a0YC0Mzz4or1C5t2gZcuJBQ0uMOZrooaI8eLu2kkI0k,15086
+cite_agent/workflow_integration.py,sha256=A9ua0DN5pRtuU0cAwrUTGvqt2SXKhEHQbrHx16EGnDM,10910
+cite_agent-1.4.3.dist-info/licenses/LICENSE,sha256=XJkyO4IymhSUniN1ENY6lLrL2729gn_rbRlFK6_Hi9M,1074
+cite_agent-1.4.3.dist-info/METADATA,sha256=5qRVIPffckAaInNqrnaZnkbapUrtUIcp_csKpCb-20I,12859
+cite_agent-1.4.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+cite_agent-1.4.3.dist-info/entry_points.txt,sha256=bJ0u28nFIxQKH1PWQ2ak4PV-FAjhoxTC7YADEdDenFw,83
+cite_agent-1.4.3.dist-info/top_level.txt,sha256=NNfD8pxDZzBK8tjDIpCs2BW9Va-OQ5qUFbEx0SgmyIE,11
+cite_agent-1.4.3.dist-info/RECORD,,

cite_agent-1.3.9.dist-info/RECORD

@@ -1,32 +0,0 @@
-cite_agent/__init__.py,sha256=wAXV2v8nNOmIAd0rh8196ItBl9hHWBVOBl5Re4VB77I,1645
-cite_agent/__main__.py,sha256=6x3lltwG-iZHeQbN12rwvdkPDfd2Rmdk71tOOaC89Mw,179
-cite_agent/__version__.py,sha256=SaWgUI6v92kVfF_Qdoxbfc38bwA34RuDGZmXMqa5g3c,22
-cite_agent/account_client.py,sha256=yLuzhIJoIZuXHXGbaVMzDxRATQwcy-wiaLnUrDuwUhI,5725
-cite_agent/agent_backend_only.py,sha256=H4DH4hmKhT0T3rQLAb2xnnJVjxl3pOZaljL9r6JndFY,6314
-cite_agent/ascii_plotting.py,sha256=lk8BaECs6fmjtp4iH12G09-frlRehAN7HLhHt2crers,8570
-cite_agent/auth.py,sha256=YtoGXKwcLkZQbop37iYYL9BzRWBRPlt_D9p71VGViS4,9833
-cite_agent/backend_only_client.py,sha256=WqLF8x7aXTro2Q3ehqKMsdCg53s6fNk9Hy86bGxqmmw,2561
-cite_agent/cli.py,sha256=edXwkxOvDJgQBJr5L2w5fREzqxi10-Iti5Es5gV7pmU,43249
-cite_agent/cli_conversational.py,sha256=RAmgRNRyB8gQ8QLvWU-Tt23j2lmA34rQNT5F3_7SOq0,11141
-cite_agent/cli_enhanced.py,sha256=EAaSw9qtiYRWUXF6_05T19GCXlz9cCSz6n41ASnXIPc,7407
-cite_agent/cli_workflow.py,sha256=4oS_jW9D8ylovXbEFdsyLQONt4o0xxR4Xatfcc4tnBs,11641
-cite_agent/conversation_archive.py,sha256=FV1EpcYTc732Oc5oc7EbrpaxUQkSNxP-KCEKbr8k2GA,4965
-cite_agent/dashboard.py,sha256=VGV5XQU1PnqvTsxfKMcue3j2ri_nvm9Be6O5aVays_w,10502
-cite_agent/enhanced_ai_agent.py,sha256=kXtZjcpGU6pXnC209BluOgytVEftwVB5Pcbxe3Y6-XY,243565
-cite_agent/project_detector.py,sha256=fPl5cLTy_oyufqrQ7RJ5IRVdofZoPqDRaQXW6tRtBJc,6086
-cite_agent/rate_limiter.py,sha256=-0fXx8Tl4zVB4O28n9ojU2weRo-FBF1cJo9Z5jC2LxQ,10908
-cite_agent/session_manager.py,sha256=B0MXSOsXdhO3DlvTG7S8x6pmGlYEDvIZ-o8TZM23niQ,9444
-cite_agent/setup_config.py,sha256=3m2e3gw0srEWA0OygdRo64r-8HK5ohyXfct0c__CF3s,16817
-cite_agent/streaming_ui.py,sha256=N6TWOo7GVQ_Ynfw73JCfrdGcLIU-PwbS3GbsHQHegmg,7810
-cite_agent/telemetry.py,sha256=55kXdHvI24ZsEkbFtihcjIfJt2oiSXcEpLzTxQ3KCdQ,2916
-cite_agent/ui.py,sha256=r1OAeY3NSeqhAjJYmEBH9CaennBuibFAz1Mur6YF80E,6134
-cite_agent/updater.py,sha256=udoAAN4gBKAvKDV7JTh2FJO_jIhNk9bby4x6n188MEY,8458
-cite_agent/web_search.py,sha256=FZCuNO7MAITiOIbpPbJyt2bzbXPzQla-9amJpnMpW_4,6520
-cite_agent/workflow.py,sha256=a0YC0Mzz4or1C5t2gZcuJBQ0uMOZrooaI8eLu2kkI0k,15086
-cite_agent/workflow_integration.py,sha256=A9ua0DN5pRtuU0cAwrUTGvqt2SXKhEHQbrHx16EGnDM,10910
-cite_agent-1.3.9.dist-info/licenses/LICENSE,sha256=XJkyO4IymhSUniN1ENY6lLrL2729gn_rbRlFK6_Hi9M,1074
-cite_agent-1.3.9.dist-info/METADATA,sha256=G7UmQPgIHXxS-6hgiWml8L7U23XsLb7JlB0nh0NVxo4,12231
-cite_agent-1.3.9.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-cite_agent-1.3.9.dist-info/entry_points.txt,sha256=bJ0u28nFIxQKH1PWQ2ak4PV-FAjhoxTC7YADEdDenFw,83
-cite_agent-1.3.9.dist-info/top_level.txt,sha256=NNfD8pxDZzBK8tjDIpCs2BW9Va-OQ5qUFbEx0SgmyIE,11
-cite_agent-1.3.9.dist-info/RECORD,,