cite-agent 1.0.0__tar.gz

cite_agent-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nocturnal Archive
+
+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.

cite_agent-1.0.0/MANIFEST.in

@@ -0,0 +1,16 @@
+include README.md
+include LICENSE
+include requirements.txt
+include requirements-dev.txt
+recursive-include docs *.md
+recursive-include nocturnal_archive *.py *.txt *.md *.json
+recursive-include tools *.py
+recursive-include tests *.py
+prune .github
+prune .claude
+prune .venv
+exclude .env*
+exclude *.log
+exclude __pycache__
+exclude *.pyc
+exclude .DS_Store

cite_agent-1.0.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: cite-agent
+Version: 1.0.0
+Summary: AI Research Assistant - Backend-Only Distribution
+Home-page: https://github.com/Spectating101/cite-agent
+Author: Cite-Agent Team
+Author-email: contact@citeagent.dev
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: keyring>=24.3.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Cite-Agent
+
+> A fast, affordable AI research assistant with built-in citation capabilities
+
+**Cite-Agent** is a terminal-based AI assistant designed for research and finance, offering 70B model access at half the cost of comparable services.
+
+---
+
+## 🎯 What is Cite-Agent?
+
+Cite-Agent is an AI-powered research tool that:
+- Answers complex questions using state-of-the-art 70B language models
+- Provides accurate, source-grounded responses (hence "cite")
+- Executes code (Python, R, SQL) for data analysis
+- Operates through a beautiful terminal interface
+- Costs $10/month (vs $20+ for Claude/ChatGPT)
+
+---
+
+## ✨ Key Features
+
+### 🧠 **Powerful AI**
+- Access to Llama 3.3 70B via Cerebras & Groq
+- Multi-provider fallback for 99.9% uptime
+- 50 queries/day (50,000 tokens)
+- 2-5 second response times
+
+### 🎓 **Truth-Seeking**
+- Explicitly designed to correct user errors
+- Admits uncertainty instead of guessing
+- Cites sources and reasoning
+- Anti-appeasement prompts
+
+### 💻 **Code Execution**
+- Python, R, and SQL support
+- Data analysis and visualization
+- Financial calculations
+- Research automation
+
+### 🔒 **Secure & Private**
+- API keys never leave the backend
+- JWT-based authentication
+- Rate limiting per user
+- HTTPS-only communication
+
+### 📊 **Analytics**
+- Track your usage
+- Monitor token consumption
+- View query history
+- Download statistics
+
+---
+
+## 💰 Pricing
+
+| Plan | Price | Queries/Day | Features |
+|------|-------|-------------|----------|
+| **Student** | $10/month (300 NTD) | 50 | Full access |
+| **Public** | $10/month (400 NTD) | 50 | Full access |
+
+**Beta**: First 50 users get 3 months free
+
+---
+
+## 🚀 Quick Start
+
+### For Users
+
+1. **Download** for your OS:
+   - [Windows](https://cite-agent-api.herokuapp.com/api/downloads/windows)
+   - [macOS](https://cite-agent-api.herokuapp.com/api/downloads/macos)
+   - [Linux](https://cite-agent-api.herokuapp.com/api/downloads/linux)
+
+2. **Install** the downloaded package
+
+3. **Run** `cite-agent` in your terminal
+
+4. **Register** with email + password
+
+5. **Start asking questions!**
+
+### For Developers
+
+See [DEVELOPMENT.md](./docs/DEVELOPMENT.md) for setup instructions.
+
+---
+
+## 🏗️ Architecture
+
+```
+User's Machine                Backend (Heroku)              AI Providers
+┌─────────────┐              ┌──────────────┐              ┌──────────┐
+│             │              │              │              │          │
+│   Terminal  │─────────────▶│   FastAPI    │─────────────▶│ Cerebras │
+│     UI      │              │     API      │              │  (70B)   │
+│             │◀─────────────│              │◀─────────────│          │
+│   (cite_    │              │  - Auth      │              └──────────┘
+│   agent/)   │              │  - Rate      │              
+│             │              │    Limiting  │              ┌──────────┐
+└─────────────┘              │  - Analytics │              │          │
+                             │  - Proxy     │─────────────▶│   Groq   │
+                             │              │              │  (70B)   │
+                             └──────────────┘              │          │
+                                    │                      └──────────┘
+                             ┌──────────────┐
+                             │  PostgreSQL  │
+                             │   Database   │
+                             └──────────────┘
+```
+
+### Components
+
+**Frontend (cite_agent/)**
+- Terminal UI using `rich` library
+- JWT authentication
+- Query management
+- Local session storage
+
+**Backend (cite-agent-api/)**
+- FastAPI REST API
+- User authentication & rate limiting
+- Multi-provider LLM routing
+- Analytics & tracking
+- PostgreSQL database
+
+**AI Providers**
+- **Primary**: Cerebras (14,400 RPD × 3 keys = 43,200/day)
+- **Backup**: Groq (1,000 RPD × 3 keys = 3,000/day)
+- **Total capacity**: ~46,000 queries/day
+
+---
+
+## 📖 Documentation
+
+- **[DEVELOPMENT.md](./docs/DEVELOPMENT.md)** - Developer setup guide
+- **[DEPLOYMENT.md](./DEPLOYMENT.md)** - How to deploy (Heroku)
+- **[API_REFERENCE.md](./docs/API_REFERENCE.md)** - API endpoints
+- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - System design details
+- **[ROADMAP.md](./ROADMAP.md)** - Future plans
+
+---
+
+## 🛠️ Tech Stack
+
+**Frontend**
+- Python 3.13+
+- `rich` for terminal UI
+- `httpx` for async HTTP
+- `pydantic` for data validation
+
+**Backend**
+- FastAPI
+- PostgreSQL
+- JWT authentication
+- Multi-provider LLM integration
+
+**AI Providers**
+- Cerebras Inference API
+- Groq Cloud
+- Cloudflare Workers AI (fallback)
+- OpenRouter (fallback)
+
+**Deployment**
+- Heroku (backend + database)
+- GitHub Releases (installers)
+
+---
+
+## 🤝 Contributing
+
+We're not accepting contributions yet (private beta), but stay tuned!
+
+---
+
+## 📜 License
+
+Proprietary - All rights reserved
+
+---
+
+## 📧 Support
+
+- **Email**: s1133958@mail.yzu.edu.tw
+- **Issues**: Coming soon
+- **Documentation**: See `/docs` directory
+
+---
+
+## 🙏 Acknowledgments
+
+- **Cerebras** for generous free tier (14,400 RPD)
+- **Groq** for fast 70B inference
+- **GitHub Student Pack** for free hosting credits
+- **FastAPI** for excellent async framework
+
+---
+
+**Built with ❤️ for researchers and analysts**
+
+*Cite-Agent - Because accuracy matters more than agreeableness*

cite_agent-1.0.0/README.md

@@ -0,0 +1,200 @@
+# Cite-Agent
+
+> A fast, affordable AI research assistant with built-in citation capabilities
+
+**Cite-Agent** is a terminal-based AI assistant designed for research and finance, offering 70B model access at half the cost of comparable services.
+
+---
+
+## 🎯 What is Cite-Agent?
+
+Cite-Agent is an AI-powered research tool that:
+- Answers complex questions using state-of-the-art 70B language models
+- Provides accurate, source-grounded responses (hence "cite")
+- Executes code (Python, R, SQL) for data analysis
+- Operates through a beautiful terminal interface
+- Costs $10/month (vs $20+ for Claude/ChatGPT)
+
+---
+
+## ✨ Key Features
+
+### 🧠 **Powerful AI**
+- Access to Llama 3.3 70B via Cerebras & Groq
+- Multi-provider fallback for 99.9% uptime
+- 50 queries/day (50,000 tokens)
+- 2-5 second response times
+
+### 🎓 **Truth-Seeking**
+- Explicitly designed to correct user errors
+- Admits uncertainty instead of guessing
+- Cites sources and reasoning
+- Anti-appeasement prompts
+
+### 💻 **Code Execution**
+- Python, R, and SQL support
+- Data analysis and visualization
+- Financial calculations
+- Research automation
+
+### 🔒 **Secure & Private**
+- API keys never leave the backend
+- JWT-based authentication
+- Rate limiting per user
+- HTTPS-only communication
+
+### 📊 **Analytics**
+- Track your usage
+- Monitor token consumption
+- View query history
+- Download statistics
+
+---
+
+## 💰 Pricing
+
+| Plan | Price | Queries/Day | Features |
+|------|-------|-------------|----------|
+| **Student** | $10/month (300 NTD) | 50 | Full access |
+| **Public** | $10/month (400 NTD) | 50 | Full access |
+
+**Beta**: First 50 users get 3 months free
+
+---
+
+## 🚀 Quick Start
+
+### For Users
+
+1. **Download** for your OS:
+   - [Windows](https://cite-agent-api.herokuapp.com/api/downloads/windows)
+   - [macOS](https://cite-agent-api.herokuapp.com/api/downloads/macos)
+   - [Linux](https://cite-agent-api.herokuapp.com/api/downloads/linux)
+
+2. **Install** the downloaded package
+
+3. **Run** `cite-agent` in your terminal
+
+4. **Register** with email + password
+
+5. **Start asking questions!**
+
+### For Developers
+
+See [DEVELOPMENT.md](./docs/DEVELOPMENT.md) for setup instructions.
+
+---
+
+## 🏗️ Architecture
+
+```
+User's Machine                Backend (Heroku)              AI Providers
+┌─────────────┐              ┌──────────────┐              ┌──────────┐
+│             │              │              │              │          │
+│   Terminal  │─────────────▶│   FastAPI    │─────────────▶│ Cerebras │
+│     UI      │              │     API      │              │  (70B)   │
+│             │◀─────────────│              │◀─────────────│          │
+│   (cite_    │              │  - Auth      │              └──────────┘
+│   agent/)   │              │  - Rate      │              
+│             │              │    Limiting  │              ┌──────────┐
+└─────────────┘              │  - Analytics │              │          │
+                             │  - Proxy     │─────────────▶│   Groq   │
+                             │              │              │  (70B)   │
+                             └──────────────┘              │          │
+                                    │                      └──────────┘
+                             ┌──────────────┐
+                             │  PostgreSQL  │
+                             │   Database   │
+                             └──────────────┘
+```
+
+### Components
+
+**Frontend (cite_agent/)**
+- Terminal UI using `rich` library
+- JWT authentication
+- Query management
+- Local session storage
+
+**Backend (cite-agent-api/)**
+- FastAPI REST API
+- User authentication & rate limiting
+- Multi-provider LLM routing
+- Analytics & tracking
+- PostgreSQL database
+
+**AI Providers**
+- **Primary**: Cerebras (14,400 RPD × 3 keys = 43,200/day)
+- **Backup**: Groq (1,000 RPD × 3 keys = 3,000/day)
+- **Total capacity**: ~46,000 queries/day
+
+---
+
+## 📖 Documentation
+
+- **[DEVELOPMENT.md](./docs/DEVELOPMENT.md)** - Developer setup guide
+- **[DEPLOYMENT.md](./DEPLOYMENT.md)** - How to deploy (Heroku)
+- **[API_REFERENCE.md](./docs/API_REFERENCE.md)** - API endpoints
+- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - System design details
+- **[ROADMAP.md](./ROADMAP.md)** - Future plans
+
+---
+
+## 🛠️ Tech Stack
+
+**Frontend**
+- Python 3.13+
+- `rich` for terminal UI
+- `httpx` for async HTTP
+- `pydantic` for data validation
+
+**Backend**
+- FastAPI
+- PostgreSQL
+- JWT authentication
+- Multi-provider LLM integration
+
+**AI Providers**
+- Cerebras Inference API
+- Groq Cloud
+- Cloudflare Workers AI (fallback)
+- OpenRouter (fallback)
+
+**Deployment**
+- Heroku (backend + database)
+- GitHub Releases (installers)
+
+---
+
+## 🤝 Contributing
+
+We're not accepting contributions yet (private beta), but stay tuned!
+
+---
+
+## 📜 License
+
+Proprietary - All rights reserved
+
+---
+
+## 📧 Support
+
+- **Email**: s1133958@mail.yzu.edu.tw
+- **Issues**: Coming soon
+- **Documentation**: See `/docs` directory
+
+---
+
+## 🙏 Acknowledgments
+
+- **Cerebras** for generous free tier (14,400 RPD)
+- **Groq** for fast 70B inference
+- **GitHub Student Pack** for free hosting credits
+- **FastAPI** for excellent async framework
+
+---
+
+**Built with ❤️ for researchers and analysts**
+
+*Cite-Agent - Because accuracy matters more than agreeableness*

cite_agent-1.0.0/cite_agent/__distribution__.py

@@ -0,0 +1,7 @@
+"""
+This is a DISTRIBUTION build.
+Local LLM calling code has been removed.
+All queries must go through the centralized backend.
+"""
+DISTRIBUTION_BUILD = True
+BACKEND_ONLY = True

cite_agent-1.0.0/cite_agent/__init__.py

@@ -0,0 +1,66 @@
+"""
+Nocturnal Archive - Beta Agent
+
+A Groq-powered research and finance co-pilot with deterministic tooling and
+prior stacks preserved only in Git history, kept out of the runtime footprint.
+"""
+
+from .enhanced_ai_agent import EnhancedNocturnalAgent, ChatRequest, ChatResponse
+
+__version__ = "0.9.0b1"
+__author__ = "Nocturnal Archive Team"
+__email__ = "contact@nocturnal.dev"
+
+__all__ = [
+    "EnhancedNocturnalAgent",
+    "ChatRequest", 
+    "ChatResponse"
+]
+
+# Package metadata
+PACKAGE_NAME = "nocturnal-archive"
+PACKAGE_VERSION = __version__
+PACKAGE_DESCRIPTION = "Beta CLI agent for finance + research workflows"
+PACKAGE_URL = "https://github.com/Spectating101/nocturnal-archive"
+
+def get_version():
+    """Get the package version"""
+    return __version__
+
+def quick_start():
+    """Print quick start instructions"""
+    print("""
+🚀 Nocturnal Archive Quick Start
+================================
+
+1. Install the package and CLI:
+   pip install nocturnal-archive
+
+2. Configure your Groq key:
+   nocturnal --setup
+
+3. Ask a question:
+   nocturnal "Compare Apple and Microsoft net income this quarter"
+
+4. Prefer embedding in code? Minimal example:
+   ```python
+   import asyncio
+   from nocturnal_archive import EnhancedNocturnalAgent, ChatRequest
+
+   async def main():
+       agent = EnhancedNocturnalAgent()
+       await agent.initialize()
+
+       response = await agent.process_request(ChatRequest(question="List repo workspace files"))
+       print(response.response)
+
+       await agent.close()
+
+   asyncio.run(main())
+   ```
+
+Full installation instructions live in docs/INSTALL.md.
+""")
+
+if __name__ == "__main__":
+    quick_start()

cite_agent-1.0.0/cite_agent/account_client.py

@@ -0,0 +1,130 @@
+"""Account provisioning utilities for the Nocturnal Archive CLI."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+
+class AccountProvisioningError(RuntimeError):
+    """Raised when account provisioning fails."""
+
+
+@dataclass(frozen=True)
+class AccountCredentials:
+    """User account credentials for backend authentication.
+
+    Production mode: User gets JWT tokens, NOT API keys.
+    Backend has the API keys, user just authenticates with JWT.
+    """
+    account_id: str
+    email: str
+    auth_token: str  # JWT for backend authentication
+    refresh_token: str
+    telemetry_token: str
+    issued_at: Optional[str] = None
+
+    @classmethod
+    def from_payload(cls, email: str, payload: Dict[str, Any]) -> "AccountCredentials":
+        try:
+            return cls(
+                account_id=str(payload["accountId"]),
+                email=email,
+                auth_token=str(payload["authToken"]),
+                refresh_token=str(payload.get("refreshToken", "")),
+                telemetry_token=str(payload.get("telemetryToken", "")),
+                issued_at=str(payload.get("issuedAt", "")) or None,
+            )
+        except KeyError as exc:  # pragma: no cover - defensive guard
+            raise AccountProvisioningError(
+                f"Account provisioning payload missing field: {exc!s}"  # noqa: TRY200
+            ) from exc
+
+
+class AccountClient:
+    """Minimal client for authenticating against the control plane.
+
+    If ``NOCTURNAL_CONTROL_PLANE_URL`` is unset the client falls back to an
+    offline deterministic token generator so local development and CI remain
+    hermetic.
+    """
+
+    def __init__(self, base_url: Optional[str] = None, timeout: int = 10):
+        self.base_url = (
+            base_url
+            or os.getenv("NOCTURNAL_CONTROL_PLANE_URL")
+            or "https://cite-agent-api-720dfadd602c.herokuapp.com"
+        )
+        self.timeout = timeout
+
+    def provision(self, email: str, password: str) -> AccountCredentials:
+        if self.base_url:
+            payload = self._request_credentials(email, password)
+            return AccountCredentials.from_payload(email=email, payload=payload)
+        return self._generate_offline_credentials(email, password)
+
+    # -- internal helpers -------------------------------------------------
+    def _request_credentials(self, email: str, password: str) -> Dict[str, Any]:
+        try:  # pragma: no cover - requires network
+            import requests  # type: ignore
+        except Exception as exc:  # pragma: no cover - executed when requests missing
+            raise AccountProvisioningError(
+                "The 'requests' package is required for control-plane authentication"
+            ) from exc
+
+        endpoint = self.base_url.rstrip("/") + "/api/beta/login"
+        body = {"email": email, "password": password, "client": "cli"}
+        try:
+            response = requests.post(endpoint, json=body, timeout=self.timeout)
+        except Exception as exc:  # pragma: no cover - network failure
+            raise AccountProvisioningError("Failed to reach control plane") from exc
+
+        if response.status_code >= 400:
+            detail = self._extract_error_detail(response)
+            raise AccountProvisioningError(
+                f"Authentication failed (status {response.status_code}): {detail}"
+            )
+
+        try:
+            payload = response.json()
+        except ValueError as exc:  # pragma: no cover - invalid JSON
+            raise AccountProvisioningError("Control plane returned invalid JSON") from exc
+
+        if not isinstance(payload, dict):  # pragma: no cover - sanity guard
+            raise AccountProvisioningError("Control plane response must be an object")
+        return payload
+
+    @staticmethod
+    def _extract_error_detail(response: Any) -> str:
+        try:  # pragma: no cover - best effort decoding
+            data = response.json()
+            if isinstance(data, dict) and data.get("detail"):
+                return str(data["detail"])
+        except Exception:
+            pass
+        return response.text.strip() or "unknown error"
+
+    @staticmethod
+    def _generate_offline_credentials(email: str, password: str) -> AccountCredentials:
+        seed = f"{email.lower()}::{password}"
+        digest = hashlib.sha256(seed.encode("utf-8")).hexdigest()
+        auth_token = digest[12:44]
+        refresh_token = digest[44:]
+        telemetry_token = digest[24:56]
+        return AccountCredentials(
+            account_id=digest[:12],
+            email=email,
+            auth_token=auth_token,
+            refresh_token=refresh_token,
+            telemetry_token=telemetry_token,
+            issued_at=None,
+        )
+
+
+__all__ = [
+    "AccountClient",
+    "AccountCredentials",
+    "AccountProvisioningError",
+]