diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 000000000..73f9732e7 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +* @Vector897 diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 000000000..9c949236f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,32 @@ +name: Bug report +description: Report a reproducible problem in Globot. +title: "[Bug]: " +labels: [bug, needs-triage] +body: + - type: markdown + attributes: + value: "Thanks for helping improve Globot. Do not include credentials, personal data, or security vulnerabilities." + - type: textarea + id: summary + attributes: + label: What happened? + validations: + required: true + - type: textarea + id: reproduce + attributes: + label: Steps to reproduce + placeholder: "1. ...\n2. ...\n3. ..." + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behaviour + validations: + required: true + - type: input + id: environment + attributes: + label: Environment + placeholder: "OS, Python/Node version, browser, commit SHA" diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..316386439 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Security vulnerability + url: https://github.com/Vector897/Globot/blob/main/SECURITY.md + about: Do not open a public issue for security reports. Follow the security policy. + - name: Support + url: https://github.com/Vector897/Globot/blob/main/SUPPORT.md + about: How to ask questions and get help. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 000000000..fe5c359f0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,21 @@ +name: Feature request +description: Propose an improvement to Globot. +title: "[Feature]: " +labels: [enhancement, needs-triage] +body: + - type: textarea + id: problem + attributes: + label: What problem would this solve? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed approach + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 000000000..2aa87f366 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,14 @@ +version: 2 +updates: + - package-ecosystem: pip + directory: /backend + schedule: + interval: weekly + - package-ecosystem: npm + directory: /frontend + schedule: + interval: weekly + - package-ecosystem: github-actions + directory: / + schedule: + interval: weekly diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000..87586ff4b --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,14 @@ +## Summary + +Describe the problem and the change. + +## Validation + +- [ ] `python -m compileall -q backend` +- [ ] `cd frontend && pnpm build` +- [ ] Documentation updated where needed + +## Safety and data + +- [ ] No credentials, personal data, or private operational data were added. +- [ ] Human review remains required for consequential recommendations. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 000000000..8d9b95e28 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,44 @@ +name: CI + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +jobs: + backend-syntax: + name: Backend syntax + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.11' + - name: Compile Python sources + run: python -m compileall -q backend + + frontend-build: + name: Frontend build + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + with: + version: 11 + - uses: actions/setup-node@v4 + with: + node-version: '20' + cache: pnpm + cache-dependency-path: frontend/pnpm-lock.yaml + - name: Install dependencies + working-directory: frontend + run: pnpm install --frozen-lockfile + - name: Build + working-directory: frontend + run: pnpm build + env: + VITE_CLERK_PUBLISHABLE_KEY: pk_test_ci_placeholder + VITE_API_BASE_URL: http://localhost:8000 diff --git a/.gitignore b/.gitignore index 5c03b089a..3bcbe650a 100644 --- a/.gitignore +++ b/.gitignore @@ -292,11 +292,3 @@ site/ # 如果需要忽略自动生成的迁移文件，取消注释： # backend/alembic/versions/*.py # 但通常建议保留迁移文件 - -# Ignore all markdown files except README.md -*.md -!README.md - - - -.txt \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..bfdf1b183 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,21 @@ +# Agent contribution guidance + +Automated coding agents working in this repository must follow the same standards as human contributors. + +## Scope and safety + +- Prefer small, reviewable changes with tests or a documented validation step. +- Do not add credentials, tokens, personal data, private URLs, local paths, or generated databases to commits. +- Treat model outputs, financial calculations, compliance assessments, and route recommendations as advisory. Do not remove human review or approval controls. +- Do not claim that mock data is live, verified, or production-ready. + +## Required checks + +Run the checks that cover your change before proposing it: + +```bash +python -m compileall -q backend +cd frontend && pnpm build +``` + +Update `README.md` and the relevant documentation whenever setup, configuration, data assumptions, or user-visible behaviour changes. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 000000000..e9021d31f --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,21 @@ +# Changelog + +All notable changes to Globot will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project aims to follow [Semantic Versioning](https://semver.org/). + +## [Unreleased] + +### Added + +- MIT `LICENSE` and community health files (Contributing, Security, Code of Conduct, Governance, Support). +- CI workflow (backend syntax + frontend production build) and Dependabot updates. +- Maintainer-oriented OpenAI/Codex plan and public roadmap under `docs/`. +- Backend / frontend `.env.example` files with safe defaults. +- Typed decision-record schemas for human-reviewed recommendations. + +### Changed + +- Rewrote the README as an OSS decision-support project (badges, architecture, clear mock-data boundaries). +- Removed personal administrator defaults; debug mode is off by default. +- Frontend package renamed to `globot-frontend`; Docker base image aligned to Python 3.11. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..df61be86e --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,23 @@ +# Contributor Covenant Code of Conduct + +## Our pledge + +We pledge to make participation in the Globot community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. + +## Our standards + +Examples of behaviour that contributes to a positive environment include: + +- demonstrating empathy and kindness toward other people; +- respecting differing opinions, viewpoints, and experiences; +- giving and gracefully accepting constructive feedback; +- accepting responsibility and apologising to those affected by mistakes; and +- focusing on what is best for the overall community. + +Examples of unacceptable behaviour include harassment, sexualised language or imagery, personal or political attacks, public or private harassment, publishing others' private information without permission, and other conduct that could reasonably be considered inappropriate in a professional setting. + +## Enforcement + +Community leaders are responsible for clarifying and enforcing these standards. Reports may be made privately through the repository owner's GitHub profile. All complaints will be reviewed and investigated promptly and fairly. Leaders may remove, edit, or reject comments, commits, code, issues, and other contributions that are not aligned with this Code of Conduct. + +This Code of Conduct is adapted from the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..89780240a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,37 @@ +# Contributing to Globot + +Thanks for helping improve Globot. Contributions are welcome in code, documentation, tests, demo scenarios, and design review. + +## Before you begin + +1. Search existing issues and pull requests to avoid duplicate work. +2. For a material change, open an issue first and describe the user problem, proposed approach, and validation plan. +3. Do not include credentials, personal data, confidential shipping records, or licensed data that cannot be redistributed. + +## Development workflow + +1. Fork the repository and create a focused branch from `main`. +2. Keep the change small and explain the behaviour it changes. +3. Update relevant documentation and examples in the same pull request. +4. Run the checks below before requesting review: + + ```bash + python -m compileall -q backend + cd frontend && pnpm build + ``` + +5. In the pull request, state the motivation, how you tested it, and any follow-up work. + +## Pull-request expectations + +- Use clear, descriptive commit and pull-request titles. +- Include tests when changing behaviour; explain why when tests are not practical. +- Keep generated files, local databases, uploads, and secrets out of commits. +- Preserve the human-review boundary for recommendations that could affect logistics, compliance, or financial decisions. +- Be patient and respectful during review. Maintainers may request revisions, defer work, or close changes that do not fit the roadmap. + +## Reporting bugs and proposing features + +Use the GitHub issue templates. A good report includes reproduction steps, expected and actual behaviour, environment details, and a minimal example where possible. Please do not use public issues for security vulnerabilities; follow [SECURITY.md](SECURITY.md) instead. + +By contributing, you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md). diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 000000000..0bbf89371 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,21 @@ +# Governance + +## Maintainer + +The repository owner, **Vector897**, is the primary maintainer and is accountable for roadmap decisions, review, releases, security coordination, and community health. + +## How decisions are made + +Issues and pull requests are the public record for project decisions. The maintainer welcomes proposals and will prioritise work that improves reproducibility, security, documentation, test coverage, accessibility, and the project's decision-support mission. + +For a substantive change, the maintainer may ask for an issue, design note, tests, or a staged implementation. Decisions aim for consensus when possible; if consensus is not reached, the primary maintainer makes the final call and records the rationale in the relevant discussion or pull request. + +## Maintainer responsibilities + +- triage issues and review pull requests; +- keep the default branch and release notes understandable; +- protect contributors and reporters handling security issues; +- enforce the [Code of Conduct](CODE_OF_CONDUCT.md); and +- avoid merging features that bypass human review for consequential recommendations. + +Contributors who demonstrate sustained, constructive maintenance work may be invited to take on additional review responsibilities. diff --git a/LICENSE b/LICENSE new file mode 100644 index 000000000..05e75997b --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Vector897 + +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. diff --git a/README.md b/README.md index a6a14f486..dc9a8809e 100644 --- a/README.md +++ b/README.md @@ -1,209 +1,168 @@ -# 🛡️ Globot Shield: Securing Global Lifelines (v2.2.20260201) +# Globot -> **Google Gemini 3 Hackathon Entry - Powered by Gemini 3.0** +[![CI](https://github.com/Vector897/Globot/actions/workflows/ci.yml/badge.svg)](https://github.com/Vector897/Globot/actions/workflows/ci.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) +[![Python 3.11](https://img.shields.io/badge/Python-3.11-3776AB.svg)](backend/requirements.txt) +[![React + Vite](https://img.shields.io/badge/Frontend-React%20%2B%20Vite-61DAFB.svg)](frontend/package.json) -![Globot Dashboard](ai-sales-mvp/frontend/src/assets/dashboard_preview.png) +**Open-source decision-support workspace for supply-chain disruption review.** -## 📖 Project Overview +Globot helps operators inspect disruption signals, compare route options, review compliance documents, and keep a **human accountable** for every consequential recommendation. It is built as a transparent research and demonstration system, not as an autonomous execution engine. -**Globot** represents a paradigm shift in global trade risk management. Unlike traditional static dashboards, Globot is an **Agentic AI system** that proactively monitors, analyzes, and mitigates supply chain risks in real-time. +> Default demos use mock and synthetic data. Outputs must be independently reviewed before they inform operational, compliance, or financial decisions. -> 💡 *"We are not just optimizing spreadsheets; we are securing the lifelines of the global economy."* +## Why this project matters -### 🌍 Social Value (Potential Impact) +Shipping and trade disruptions affect food, energy, medical supply, and manufacturing lead times. Existing tooling is often either a static dashboard or a black-box model. Globot sits in between: -When Globot helps Maersk reroute quickly during the Red Sea crisis, it means: -- 🌾 **Food supplies in Kenya** remain uninterrupted -- 🔥 **Natural gas in Europe** lasts through the winter -- 🏥 **Emergency hospital equipment** doesn't get stuck at ports +- **Inspectable multi-agent activity** — market, logistics, compliance, and hedging perspectives in one review flow +- **Human-in-the-loop by design** — recommendations cannot be treated as actions without explicit approval +- **Reproducible open demo** — local fixtures and documented scenarios so contributors can verify behaviour +- **Pluggable integrations** — mock sources today; production adapters tomorrow (AIS, news, insurance, market data) -This version (**v2.1.20260131**) is a specially built **"High-Fidelity Mock"** version, designed to ensure absolute stability and high impact during demonstrations. It simulates a realistic "4:55 PM Crisis Scenario" (geopolitical crisis in the Strait of Hormuz) and fully demonstrates the **AI Chain-of-Thought** and **Human-in-the-Loop** decision-making processes powered by **Gemini 3.0**. +The repository is an ecosystem building block for **responsible agentic logistics research**: a shared reference for HITL controls, provenance-friendly summaries, and maintenance-friendly FastAPI + React structure. -## 🌟 Core Features (v2.1 Upgrade) +## Table of contents -### 1. 🧠 Visualized AI Chain-of-Thought +- [Current status](#current-status) +- [Core capabilities](#core-capabilities) +- [Quick start](#quick-start) +- [Configuration](#configuration) +- [Architecture](#architecture) +- [Roadmap](#roadmap) +- [Contributing](#contributing) +- [License](#license) -- **Real-time Reasoning Display**: Shows the AI's thinking process line-by-line like a "typewriter," no longer a black box. -- **Multi-Agent Debate**: Features an "Adversarial Debate" (Red Team vs. Blue Team) to ensure decision robustness. -- **Citations & Provenance**: Every reasoning step is linked to specific documents in the RAG knowledge base or real-time news sources. +## Current status -### 2. 🤖 Multi-Agent Collaboration Engine (5-Agent Reasoning Engine) +Globot is actively maintained as a public research / demonstration project. -Features a team of 5 specialized AI Agents working in synergy: +| Area | Status | +| --- | --- | +| Stars / forks | Tracked on GitHub; community PRs welcome | +| License | [MIT](LICENSE) | +| CI | Backend syntax + frontend production build on `main` and PRs | +| Default data | Mock / synthetic — **not** live trading, sanctions, or execution | +| Production readiness | **Not** production-ready without deployers adding auth, secrets, data licenses, and review controls | -- **🔭 Market Sentinel**: Monitors geopolitical signals from Reuters/Bloomberg (Mock API supports multiple scenarios: Red Sea crisis, port congestion, etc.). -- **🛡️ Financial Hedge Agent**: Real-time analysis of fuel prices, exchange rates, and freight risks. Provides intelligent hedging strategies (futures, options, forwards) for both normal and crisis risk management. Dynamically calculates fuel costs (+$180K) and freight fluctuations after rerouting. -- **🚢 Logistics Orchestrator**: Re-plans routes to avoid conflict zones. -- **📋 Compliance Manager**: Uses **Gemini 3.0's Extended Context Window** to analyze 500-page insurance policies and sanction lists. -- **⚖️ Adversarial Debate**: Red-teams decisions to prevent hallucinations. +## Core capabilities -### 3. 🛰️ Visual Risk Intelligence (Satellite Image Analysis) - NEW +1. **Scenario-driven demo** — reproducible disruption walkthrough with route selection and approval steps +2. **Multi-perspective review** — market signals, route risk, compliance document experiments, hedging calculations +3. **Map-centric visualisation** — Deck.gl-based logistics map for ports, routes, and risk highlighting +4. **Human approval gate** — Approve / details / override path before a recommendation is treated as an action +5. **Optional model providers** — Ollama by default; OpenAI and other providers remain opt-in via server-side env vars -Leverages **Gemini 3.0 Vision** multimodal capabilities: +## Quick start -- **Satellite Image Analysis**: Real-time detection of port congestion, canal blockages, and container accumulation. -- **Suez Canal Scenario**: Early warning for Ever Given-style events (6 hours before official announcements). -- **Visual Evidence**: Embeds satellite screenshots into decisions as reasoning evidence. +### Prerequisites -### 4. 📄 Long Document Compliance Analysis - NEW - -Showcases Gemini's long context window advantages: - -- **500-page Maritime Insurance Policies**: Automated parsing and route compliance verification. -- **OFAC/UN Sanction Lists**: Real-time checks (2M tokens context). -- **MLC 2006 Convention**: Automated verification of crew certifications. - -### 5. �️ Aviation-Grade Logistics Holographic Map (Deck.gl) - -- **Routes & Ports**: Visualizes major global shipping lanes and core ports like Shanghai, Rotterdam, and Los Angeles. -- **Interactive Vessels**: Click on yellow ship icons on the map to view detailed cargo manifests and voyage status. -- **Dynamic Risk**: When a crisis occurs, affected areas highlight and pulse with alerts. - -### 6. 👨‍✈️ Human-in-the-Loop (HITL) - -- **Decision Confirmation**: After the AI makes a recommendation, a human must click **"Approve & Execute"** for it to take effect, reflecting responsible AI principles. -- **Options**: Provides "Details" and "Override" (manual intervention) options. - -### 7. 🔒 Enterprise-Grade Authentication & Security - -- **Multi-channel Login**: Integrated with Clerk, supporting Google, Facebook, LinkedIn social logins, and Email/SMS verification. -- **Admin Console**: A visual dashboard designed specifically for administrators to monitor global system KPIs. -- **Security Whitelist**: Email whitelist system based on environment variables to ensure privacy and security of administrative permissions. - -### 🔌 Pluggable Data Sources - -The **Reasoning Engine** in this project is generic. Current use of Mock data is a Hackathon constraint. Production environments can directly integrate: - -| Data Source | Purpose | Replacement Method | -| :--- | :--- | :--- | -| Bloomberg Terminal API | Real-time market data, geopolitical events | Replace `mock_knowledge_base.py` | -| MarineTraffic API | Real-time AIS vessel tracking | Replace `demo/cot_data.py` | -| Sentinel-2 Satellite API | Port/Canal satellite imagery | Replace `visual_risk_service.py` | -| Reuters/Bing News API | Real-time news feeds | Replace Market Sentinel data source | - -## 🎯 Target Customers - -| Industry | Example Companies | User Roles | -| :--- | :--- | :--- | -| Shipping & Logistics | Maersk, COSCO | NOC Manager, Control Tower Lead | -| High-end Manufacturing | Tesla, Apple | Global Supply Manager, Resiliency PM | -| Commodity Trading | Cargill, Glencore | Commodity Logistics Risk Lead | -| Freight Forwarding | Flexport | Trade Compliance Officer | - -## 🚀 Quick Start - -### 1. Start Backend - -#### Prerequisites - Python 3.11 +- Node.js 20+ +- [pnpm](https://pnpm.io/) (lockfile: `frontend/pnpm-lock.yaml`) -#### Installation Steps +### Backend ```bash -# Enter backend directory cd backend +python -m venv .venv +# Windows PowerShell +.\.venv\Scripts\Activate.ps1 +# macOS/Linux +# source .venv/bin/activate -# Create virtual environment (recommended) -python -m venv venv - -# Activate virtual environment -# Windows PowerShell: -.\venv\Scripts\Activate.ps1 -# Windows CMD: - venv\Scripts\activate.bat -# macOS/Linux: - source venv/bin/activate - -# Install dependencies pip install -r requirements.txt - -# Configure environment variables -# Create a .env file in the backend directory with core configurations: -# CLERK_ISSUER_URL=... -# ADMIN_WHITELIST=... - -# Start server +cp .env.example .env # Windows: copy .env.example .env python start_server.py ``` -_Backend runs at `http://localhost:8000`_ -### 2. Start Frontend +API: `http://localhost:8000` + +### Frontend ```bash cd frontend -npm install +pnpm install --frozen-lockfile +cp .env.example .env # Windows: copy .env.example .env +pnpm dev +``` -# Configure environment variables -# Create a .env file in the frontend directory: -# VITE_CLERK_PUBLISHABLE_KEY=... -# VITE_ADMIN_WHITELIST=... +UI: `http://localhost:5173` -npm run dev -``` -_Frontend runs at `http://localhost:5173`_ +### Demo path -### 3. Demo Path +1. Open `http://localhost:5173/pay` +2. Choose **Watch Demo** → route selection (`/port`) +3. Confirm a route (default Shanghai → Rotterdam) → **Start Simulation** (`/demo`) +4. Follow the activity feed and use **Approve & Execute** only after human review -1. Open browser and visit: `http://localhost:5173/pay` -2. Click **"Watch Demo"** to go to the route selection page (`/port`). -3. Confirm route (default Shanghai -> Rotterdam) and click **"Start Simulation"** to enter the demo (`/demo`). -4. Observe the AI reasoning process and click confirm once the "Approve & Execute" button appears. +## Configuration -## 📂 Key File Descriptions +Copy example env files before local edits. Never commit API keys, Clerk credentials, personal allowlists, uploads, or production data. Defaults contain no credentials and enable no administrator. -- `updates/README.md`: Detailed demo operation steps (Must-read for new users). -- `task.md`: Project development task list. -- `updates/README.md`: Service startup and troubleshooting quick-reference table. +| File | Purpose | +| --- | --- | +| `backend/.env.example` | API, optional LLM providers, Clerk issuer, allowlist | +| `frontend/.env.example` | Vite public Clerk key stub and API base URL | -## 💰 Financial Hedging System (NEW) +`backend/data/` holds demonstration assets. Treat all outputs as illustrative unless you replace those sources with licensed, verified data and add operational controls. -Globot now includes a comprehensive financial risk hedging system for managing: +## Architecture -### Risk Categories -- **Fuel Price Risk**: Hedge marine fuel price fluctuations using futures, options, and swaps. -- **Currency Risk**: Lock in exchange rates via forward contracts and currency swaps. -- **Freight Rate Risk**: Combined strategy of long-term charter contracts and spot market participation. +```text +React / Vite frontend (review UI + map) + | + v +FastAPI backend + | | | + demo risk/route documents & hedging experiments + | + mock scenarios + local knowledge assets +``` -### Features -- ✅ AI-powered risk assessment with Value at Risk (VaR) calculations -- ✅ Automated hedging strategy recommendations (normal & crisis modes) -- ✅ Real-time market data simulation -- ✅ Crisis detection and emergency hedging protocols -- ✅ Multi-instrument portfolio optimization +Longer-term maintainer automation and opt-in OpenAI usage: [docs/OPENAI_API_PLAN.md](docs/OPENAI_API_PLAN.md). -### API Endpoints -```bash -# Health check -GET http://localhost:8000/api/hedge/health +## Project health -# Get market data -GET http://localhost:8000/api/hedge/market-data +| Signal | Detail | +| --- | --- | +| License | OSI-approved MIT | +| Community files | CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, GOVERNANCE, SUPPORT | +| Automation | GitHub Actions CI + Dependabot | +| Maintainer | Primary maintainer [@Vector897](https://github.com/Vector897) with write access | +| Codex plan | [docs/OPENAI_API_PLAN.md](docs/OPENAI_API_PLAN.md) | -# Assess risk exposure -POST http://localhost:8000/api/hedge/assess-risk +## Roadmap -# Get hedging recommendations -POST http://localhost:8000/api/hedge/recommend +See [docs/ROADMAP.md](docs/ROADMAP.md). Near-term priorities: -# Activate crisis hedging -POST http://localhost:8000/api/hedge/crisis-activate +- Repeatable API and scenario tests in CI +- Explicit, opt-in provider integrations with evaluation fixtures +- Provenance and review records for every UI recommendation +- Maintainer automation for issue triage, PR review summaries, release notes, and dependency hygiene -# Generate executive report -POST http://localhost:8000/api/hedge/report -``` +## Contributing + +Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue or PR. -### Documentation -- **API Documentation**: `backend/docs/HEDGING_API.md` -- **Strategy Guide**: `backend/docs/HEDGING_STRATEGY_GUIDE.md` -- **Claude Skill**: `backend/claude_skill/financial_hedging/SKILL.md` +| Doc | Purpose | +| --- | --- | +| [SECURITY.md](SECURITY.md) | Vulnerability reporting | +| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Community standards | +| [GOVERNANCE.md](GOVERNANCE.md) | Maintainer decision-making | +| [SUPPORT.md](SUPPORT.md) | How to get help | +| [CHANGELOG.md](CHANGELOG.md) | Notable changes | +| [AGENTS.md](AGENTS.md) | Guidance for automated coding agents | + +Local checks before review: -### Quick Test ```bash -cd backend -python test_hedging_system.py +python -m compileall -q backend +cd frontend && pnpm build ``` ---- +## License + +Globot is released under the [MIT License](LICENSE). -**Maintainer**: Vector897 -**License**: MIT +**Primary maintainer:** [Vector897](https://github.com/Vector897) diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000..6051cf227 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,22 @@ +# Security policy + +## Supported versions + +Security fixes are applied to the latest `main` branch. Releases are not yet versioned; users of older forks should update to the latest commit before reporting an issue. + +## Reporting a vulnerability + +Please do **not** open a public issue for a suspected vulnerability. Report it privately to the repository owner through the contact method in the GitHub profile, with: + +- a clear description and affected component; +- steps to reproduce or a minimal proof of concept; +- potential impact; and +- any suggested mitigation. + +The maintainer will acknowledge a report within seven days where possible, investigate privately, and coordinate a fix before public disclosure. Please give maintainers reasonable time to remediate before publishing details. + +## Security boundaries + +Globot is a demonstration and research project. It must not be deployed with wildcard cross-origin access, default credentials, personal allowlists, or unreviewed data sources. Deployers are responsible for authentication, least-privilege access, secret management, input validation, dependency updates, logging controls, and review of any model-assisted output. + +Never commit API keys, Clerk credentials, tokens, user uploads, or operational data. If you discover an exposed secret, revoke or rotate it immediately and report it privately. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 000000000..2d1fb7c78 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,8 @@ +# Getting support + +- **Questions and ideas:** open a GitHub Discussion or an issue with the `question` label. +- **Bug reports:** use the bug-report issue template and include reproducible steps. +- **Feature requests:** use the feature-request issue template and describe the problem before proposing a solution. +- **Security vulnerabilities:** follow [SECURITY.md](SECURITY.md); do not disclose them publicly. + +Globot is maintained in available volunteer time. Please provide enough context for another contributor to reproduce the problem and allow reasonable time for a response. diff --git a/backend/.env.example b/backend/.env.example new file mode 100644 index 000000000..b9c3c8eb3 --- /dev/null +++ b/backend/.env.example @@ -0,0 +1,18 @@ +# Application +DATABASE_URL=postgresql://user:password@localhost:5432/globot +LOG_LEVEL=INFO +DEBUG=false + +# Authentication and access control. Leave the allowlist empty for local demo use. +CLERK_ISSUER_URL= +ADMIN_WHITELIST= + +# Optional model providers. Keep all credentials out of source control. +LLM_PROVIDER=ollama +OLLAMA_BASE_URL=http://localhost:11434 +OLLAMA_MODEL=qwen2.5:latest +OPENAI_API_KEY= +OPENAI_BASE_URL= +OPENAI_MODEL=gpt-4o-mini +GOOGLE_API_KEY= +GOOGLE_MAPS_API_KEY= diff --git a/backend/Dockerfile b/backend/Dockerfile index 090ef9f2a..9a044748d 100644 --- a/backend/Dockerfile +++ b/backend/Dockerfile @@ -1,4 +1,4 @@ -FROM python:3.10-slim +FROM python:3.11-slim WORKDIR /app diff --git a/backend/config.py b/backend/config.py index 74f0dd898..82a0a8774 100644 --- a/backend/config.py +++ b/backend/config.py @@ -16,7 +16,7 @@ class Settings(BaseSettings): ) # 数据库 - database_url: str = "postgresql://user:password@localhost:5432/dji_sales_mvp" + database_url: str = "postgresql://user:password@localhost:5432/globot" # LLM选择: ollama 或 openai llm_provider: str = "ollama" @@ -56,11 +56,11 @@ class Settings(BaseSettings): # Clerk配置 clerk_issuer_url: Optional[str] = None - admin_whitelist: str = "thaumatext@gmail.com" + admin_whitelist: str = "" # 系统配置 log_level: str = "INFO" - debug: bool = True + debug: bool = False @lru_cache() diff --git a/backend/core/reasoning_schemas.py b/backend/core/reasoning_schemas.py index 48535f684..e569a4b0c 100644 Binary files a/backend/core/reasoning_schemas.py and b/backend/core/reasoning_schemas.py differ diff --git a/docs/OPENAI_API_PLAN.md b/docs/OPENAI_API_PLAN.md new file mode 100644 index 000000000..3df09066a --- /dev/null +++ b/docs/OPENAI_API_PLAN.md @@ -0,0 +1,58 @@ +# OpenAI / Codex maintenance plan + +## Purpose + +Globot is a maintained open-source decision-support prototype for supply-chain disruption review. If granted Codex for Open Source API credits (and ChatGPT Pro with Codex), the primary maintainer will use them for **real repository maintenance** first, and for **opt-in product experiments** second. + +This plan is intentionally concrete: credits should reduce review load and raise code quality without removing human accountability. + +## How API credits will be used + +### 1. Pull-request review automation (primary) + +- Summarise diffs for large frontend map / backend agent changes +- Flag missing tests, secret leaks, and HITL-control regressions +- Draft structured review checklists; a human maintainer must approve or request changes + +### 2. Issue triage and contributor onboarding + +- Classify bugs vs questions vs features +- Detect incomplete reproduction steps and draft respectful follow-ups for maintainer edit +- Propose “good first issue” labels for safer entry points into the codebase + +### 3. Release and documentation workflows + +- Draft changelog entries and migration notes from merged PRs +- Keep README / ROADMAP / SECURITY wording aligned with behaviour changes +- Generate dependency-update risk notes when Dependabot opens PRs + +### 4. Opt-in product assistance (secondary, server-side only) + +- Environment-configured assistance for summarising **fixture documents** and explaining scenario evidence in the demo path +- No OpenAI key in the client bundle; no model output may execute operational, compliance, or financial actions +- All such UI content labelled as model-assisted and reviewable + +### 5. Security-oriented review (Codex Security interest) + +- Prioritise auth surfaces, CORS, env handling, upload paths, and dependency CVEs when access is granted +- Coordinate fixes privately per [SECURITY.md](../SECURITY.md) when needed + +## Guardrails and evaluation + +| Guardrail | Rule | +| --- | --- | +| Credentials | Server-side only; never committed | +| Data | Representative, non-sensitive fixtures for development and evaluation | +| Accountability | Humans remain responsible for merges, security disclosure, and consequential recommendations | +| Labelling | Model-assisted content is labelled; sources/provenance retained where available | +| Metrics | Track triage accuracy, review usefulness, latency, and maintainer acceptance before expanding scope | + +## Success criteria + +Credits are successful if, within two release cycles, Globot shows: + +1. Faster, more consistent PR review notes with no increase in merge regressions +2. Clearer issue responses and fewer stalled “needs info” tickets +3. Documented evaluation results for any opt-in product experiment, including known failure modes + +Integration configuration, evaluation results, limitations, and breaking changes will be recorded in public pull requests and release notes. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 000000000..18ec934d5 --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,31 @@ +# Roadmap + +This roadmap describes public priorities for Globot. Items may be reordered as contributors join and as evaluation results arrive. Status is tracked through GitHub issues and pull requests. + +## Near term (next 1–2 months) + +- [ ] Expand CI beyond syntax/build: FastAPI route smoke tests and key scenario calculation fixtures +- [ ] Document every mock data boundary in the UI and API responses +- [ ] Add an explicit “provenance” panel for sources that back a recommendation summary +- [ ] Harden contribution path: first-time contributor labels, clearer issue templates, dependency update cadence via Dependabot +- [ ] Optional OpenAI-assisted **maintainer** workflows (issue triage drafts, PR review checklists) with human approval before any reply is posted — see [OPENAI_API_PLAN.md](OPENAI_API_PLAN.md) + +## Mid term (3–6 months) + +- [ ] Pluggable adapters for news / AIS / document corpora behind the same review contracts +- [ ] Evaluation harness for model-assisted summaries (faithfulness, latency, maintainer acceptance) +- [ ] Accessibility pass on high-traffic demo screens +- [ ] Versioned releases with changelog-driven notes and tagged GitHub Releases +- [ ] Codex Security–style review for dependency and auth surfaces when appropriate + +## Longer term + +- [ ] Shared OSS reference patterns for HITL logistics decision support +- [ ] Community scenarios contributed under clearly licensed sample data +- [ ] Optional multi-maintainer review rotation as contributor load grows + +## Non-goals + +- Autonomous execution against live trading, booking, or payment systems +- Shipping production credentials or personal allowlists in the repository +- Claiming mock demos as live sanctions / market truth diff --git a/frontend/.env.example b/frontend/.env.example index fd61ea009..06b89e980 100644 --- a/frontend/.env.example +++ b/frontend/.env.example @@ -1,2 +1,3 @@ # Clerk Configuration VITE_CLERK_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx +VITE_API_BASE_URL=http://localhost:8000 diff --git a/frontend/package.json b/frontend/package.json index 805fc23fc..c46074c8f 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -1,5 +1,5 @@ { - "name": "dji-sales-frontend", + "name": "globot-frontend", "private": true, "version": "1.0.0", "type": "module", @@ -105,10 +105,5 @@ "react-dom": { "optional": true } - }, - "pnpm": { - "overrides": { - "vite": "6.3.5" - } } -} \ No newline at end of file +} diff --git a/frontend/pnpm-lock.yaml b/frontend/pnpm-lock.yaml index 6f16ead75..b7487e5ec 100644 --- a/frontend/pnpm-lock.yaml +++ b/frontend/pnpm-lock.yaml @@ -1848,66 +1848,79 @@ packages: resolution: {integrity: sha512-Rn3n+FUk2J5VWx+ywrG/HGPTD9jXNbicRtTM11e/uorplArnXZYsVifnPPqNNP5BsO3roI4n8332ukpY/zN7rQ==} cpu: [arm] os: [linux] + libc: [glibc] '@rollup/rollup-linux-arm-musleabihf@4.55.1': resolution: {integrity: sha512-grPNWydeKtc1aEdrJDWk4opD7nFtQbMmV7769hiAaYyUKCT1faPRm2av8CX1YJsZ4TLAZcg9gTR1KvEzoLjXkg==} cpu: [arm] os: [linux] + libc: [musl] '@rollup/rollup-linux-arm64-gnu@4.55.1': resolution: {integrity: sha512-a59mwd1k6x8tXKcUxSyISiquLwB5pX+fJW9TkWU46lCqD/GRDe9uDN31jrMmVP3feI3mhAdvcCClhV8V5MhJFQ==} cpu: [arm64] os: [linux] + libc: [glibc] '@rollup/rollup-linux-arm64-musl@4.55.1': resolution: {integrity: sha512-puS1MEgWX5GsHSoiAsF0TYrpomdvkaXm0CofIMG5uVkP6IBV+ZO9xhC5YEN49nsgYo1DuuMquF9+7EDBVYu4uA==} cpu: [arm64] os: [linux] + libc: [musl] '@rollup/rollup-linux-loong64-gnu@4.55.1': resolution: {integrity: sha512-r3Wv40in+lTsULSb6nnoudVbARdOwb2u5fpeoOAZjFLznp6tDU8kd+GTHmJoqZ9lt6/Sys33KdIHUaQihFcu7g==} cpu: [loong64] os: [linux] + libc: [glibc] '@rollup/rollup-linux-loong64-musl@4.55.1': resolution: {integrity: sha512-MR8c0+UxAlB22Fq4R+aQSPBayvYa3+9DrwG/i1TKQXFYEaoW3B5b/rkSRIypcZDdWjWnpcvxbNaAJDcSbJU3Lw==} cpu: [loong64] os: [linux] + libc: [musl] '@rollup/rollup-linux-ppc64-gnu@4.55.1': resolution: {integrity: sha512-3KhoECe1BRlSYpMTeVrD4sh2Pw2xgt4jzNSZIIPLFEsnQn9gAnZagW9+VqDqAHgm1Xc77LzJOo2LdigS5qZ+gw==} cpu: [ppc64] os: [linux] + libc: [glibc] '@rollup/rollup-linux-ppc64-musl@4.55.1': resolution: {integrity: sha512-ziR1OuZx0vdYZZ30vueNZTg73alF59DicYrPViG0NEgDVN8/Jl87zkAPu4u6VjZST2llgEUjaiNl9JM6HH1Vdw==} cpu: [ppc64] os: [linux] + libc: [musl] '@rollup/rollup-linux-riscv64-gnu@4.55.1': resolution: {integrity: sha512-uW0Y12ih2XJRERZ4jAfKamTyIHVMPQnTZcQjme2HMVDAHY4amf5u414OqNYC+x+LzRdRcnIG1YodLrrtA8xsxw==} cpu: [riscv64] os: [linux] + libc: [glibc] '@rollup/rollup-linux-riscv64-musl@4.55.1': resolution: {integrity: sha512-u9yZ0jUkOED1BFrqu3BwMQoixvGHGZ+JhJNkNKY/hyoEgOwlqKb62qu+7UjbPSHYjiVy8kKJHvXKv5coH4wDeg==} cpu: [riscv64] os: [linux] + libc: [musl] '@rollup/rollup-linux-s390x-gnu@4.55.1': resolution: {integrity: sha512-/0PenBCmqM4ZUd0190j7J0UsQ/1nsi735iPRakO8iPciE7BQ495Y6msPzaOmvx0/pn+eJVVlZrNrSh4WSYLxNg==} cpu: [s390x] os: [linux] + libc: [glibc] '@rollup/rollup-linux-x64-gnu@4.55.1': resolution: {integrity: sha512-a8G4wiQxQG2BAvo+gU6XrReRRqj+pLS2NGXKm8io19goR+K8lw269eTrPkSdDTALwMmJp4th2Uh0D8J9bEV1vg==} cpu: [x64] os: [linux] + libc: [glibc] '@rollup/rollup-linux-x64-musl@4.55.1': resolution: {integrity: sha512-bD+zjpFrMpP/hqkfEcnjXWHMw5BIghGisOKPj+2NaNDuVT+8Ds4mPf3XcPHuat1tz89WRL+1wbcxKY3WSbiT7w==} cpu: [x64] os: [linux] + libc: [musl] '@rollup/rollup-openbsd-x64@4.55.1': resolution: {integrity: sha512-eLXw0dOiqE4QmvikfQ6yjgkg/xDM+MdU9YJuP4ySTibXU0oAvnEWXt7UDJmD4UkYialMfOGFPJnIHSe/kdzPxg==} @@ -1977,24 +1990,28 @@ packages: engines: {node: '>= 10'} cpu: [arm64] os: [linux] + libc: [glibc] '@tailwindcss/oxide-linux-arm64-musl@4.1.12': resolution: {integrity: sha512-V8pAM3s8gsrXcCv6kCHSuwyb/gPsd863iT+v1PGXC4fSL/OJqsKhfK//v8P+w9ThKIoqNbEnsZqNy+WDnwQqCA==} engines: {node: '>= 10'} cpu: [arm64] os: [linux] + libc: [musl] '@tailwindcss/oxide-linux-x64-gnu@4.1.12': resolution: {integrity: sha512-xYfqYLjvm2UQ3TZggTGrwxjYaLB62b1Wiysw/YE3Yqbh86sOMoTn0feF98PonP7LtjsWOWcXEbGqDL7zv0uW8Q==} engines: {node: '>= 10'} cpu: [x64] os: [linux] + libc: [glibc] '@tailwindcss/oxide-linux-x64-musl@4.1.12': resolution: {integrity: sha512-ha0pHPamN+fWZY7GCzz5rKunlv9L5R8kdh+YNvP5awe3LtuXb5nRi/H27GeL2U+TdhDOptU7T6Is7mdwh5Ar3A==} engines: {node: '>= 10'} cpu: [x64] os: [linux] + libc: [musl] '@tailwindcss/oxide-wasm32-wasi@4.1.12': resolution: {integrity: sha512-4tSyu3dW+ktzdEpuk6g49KdEangu3eCYoqPhWNsZgUhyegEda3M9rG0/j1GV/JjVVsj+lG7jWAyrTlLzd/WEBg==} @@ -3162,24 +3179,28 @@ packages: engines: {node: '>= 12.0.0'} cpu: [arm64] os: [linux] + libc: [glibc] lightningcss-linux-arm64-musl@1.30.1: resolution: {integrity: sha512-jmUQVx4331m6LIX+0wUhBbmMX7TCfjF5FoOH6SD1CttzuYlGNVpA7QnrmLxrsub43ClTINfGSYyHe2HWeLl5CQ==} engines: {node: '>= 12.0.0'} cpu: [arm64] os: [linux] + libc: [musl] lightningcss-linux-x64-gnu@1.30.1: resolution: {integrity: sha512-piWx3z4wN8J8z3+O5kO74+yr6ze/dKmPnI7vLqfSqI8bccaTGY5xiSGVIJBDd5K5BHlvVLpUB3S2YCfelyJ1bw==} engines: {node: '>= 12.0.0'} cpu: [x64] os: [linux] + libc: [glibc] lightningcss-linux-x64-musl@1.30.1: resolution: {integrity: sha512-rRomAK7eIkL+tHY0YPxbc5Dra2gXlI63HL+v1Pdi1a3sC+tJTcFrHX+E86sulgAXeI7rSzDYhPSeHHjqFhqfeQ==} engines: {node: '>= 12.0.0'} cpu: [x64] os: [linux] + libc: [musl] lightningcss-win32-arm64-msvc@1.30.1: resolution: {integrity: sha512-mSL4rqPi4iXq5YVqzSsJgMVFENoa4nGTT/GjO2c0Yl9OuQfPsIfncvLrEW6RbbB24WtZ3xP/2CCmI3tNkNV4oA==} @@ -3470,8 +3491,8 @@ packages: picocolors@1.1.1: resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==} - picomatch@4.0.3: - resolution: {integrity: sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==} + picomatch@4.0.5: + resolution: {integrity: sha512-RvwwcruNjI1ncT5xRakeyS9Lf8lcItv34KD+aif+VH9kduAyfYBipGh12274xtenIPZ119/R9BdTBa8gAwSh0A==} engines: {node: '>=12'} point-in-polygon-hao@1.2.4: @@ -4182,8 +4203,8 @@ packages: tinycolor2@1.6.0: resolution: {integrity: sha512-XPaBkWQJdsf3pLKJV9p4qN/S+fm2Oj8AIPo1BTUhg5oxkvm9+SVEGFdhyOz7tTdUTfvxMiAs4sp6/eZO2Ew+pw==} - tinyglobby@0.2.15: - resolution: {integrity: sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==} + tinyglobby@0.2.17: + resolution: {integrity: sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==} engines: {node: '>=12.0.0'} tinyqueue@3.0.0: @@ -7286,9 +7307,9 @@ snapshots: dependencies: strnum: 1.1.2 - fdir@6.5.0(picomatch@4.0.3): + fdir@6.5.0(picomatch@4.0.5): optionalDependencies: - picomatch: 4.0.3 + picomatch: 4.0.5 fecha@4.2.3: {} @@ -8009,7 +8030,7 @@ snapshots: picocolors@1.1.1: {} - picomatch@4.0.3: {} + picomatch@4.0.5: {} point-in-polygon-hao@1.2.4: dependencies: @@ -8879,10 +8900,10 @@ snapshots: tinycolor2@1.6.0: {} - tinyglobby@0.2.15: + tinyglobby@0.2.17: dependencies: - fdir: 6.5.0(picomatch@4.0.3) - picomatch: 4.0.3 + fdir: 6.5.0(picomatch@4.0.5) + picomatch: 4.0.5 tinyqueue@3.0.0: {} @@ -9005,11 +9026,11 @@ snapshots: vite@6.3.5(@types/node@25.0.9)(jiti@2.6.1)(lightningcss@1.30.1)(terser@5.46.0): dependencies: esbuild: 0.25.12 - fdir: 6.5.0(picomatch@4.0.3) - picomatch: 4.0.3 + fdir: 6.5.0(picomatch@4.0.5) + picomatch: 4.0.5 postcss: 8.5.6 rollup: 4.55.1 - tinyglobby: 0.2.15 + tinyglobby: 0.2.17 optionalDependencies: '@types/node': 25.0.9 fsevents: 2.3.3 diff --git a/frontend/pnpm-workspace.yaml b/frontend/pnpm-workspace.yaml new file mode 100644 index 000000000..442d6b46d --- /dev/null +++ b/frontend/pnpm-workspace.yaml @@ -0,0 +1,8 @@ +# pnpm 11+ settings (package.json "pnpm" field is ignored in v11) +overrides: + vite: 6.3.5 + +allowBuilds: + esbuild: true + '@clerk/shared': true + '@tailwindcss/oxide': true