Metadata-Version: 2.5
Name: generative-agent-assistant
Version: 0.2.0
Summary: Decision-oriented agent runtime with explicit approvals, inspectable history, optional independent checking and a built-in web UI.
Project-URL: Homepage, https://github.com/xualbert83/generative-agent-assistant
Project-URL: Repository, https://github.com/xualbert83/generative-agent-assistant
Project-URL: Issues, https://github.com/xualbert83/generative-agent-assistant/issues
Author-email: Albert Xu <xualbert83@outlook.com>
License-Expression: MIT
License-File: LICENSE
License-File: NOTICE.md
Keywords: agent,chatbot,fastapi,llm,mcp,react,sse
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: <3.13,>=3.12
Requires-Dist: aiohttp>=3.14.4
Requires-Dist: aiosqlite>=0.22.1
Requires-Dist: anyio>=4.14.1
Requires-Dist: asyncpg<0.32,>=0.31
Requires-Dist: certifi>=2026.10.19
Requires-Dist: cryptography>=50.0.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: jsonschema>=4.26.0
Requires-Dist: langfuse<3,>=2
Requires-Dist: loguru>=0.7.3
Requires-Dist: mammoth>=1.12.0
Requires-Dist: markdownify>=1.2.3
Requires-Dist: mcp<2,>=1.30.0
Requires-Dist: minio>=7.2.20
Requires-Dist: multidict>=6.9.1
Requires-Dist: nacos-sdk-python==3.2.0
Requires-Dist: pillow>=13.0.0
Requires-Dist: pwdlib[argon2]>=0.3.0
Requires-Dist: pyjwt<3,>=2.15.0
Requires-Dist: pymupdf4llm>=1.28.0
Requires-Dist: python-multipart>=0.0.32
Requires-Dist: pyyaml>=6.0
Requires-Dist: sqlalchemy[asyncio]<2.1,>=2.0.52
Requires-Dist: taskiq-redis>=1.2.3
Requires-Dist: taskiq>=0.12.4
Requires-Dist: urllib3>=2.8.0
Requires-Dist: uvicorn[standard]>=0.30.0
Description-Content-Type: text/markdown

<div align="center">

![GCA: Make work inspectable](https://raw.githubusercontent.com/xualbert83/generative-agent-assistant/main/docs/assets/gca-hero.svg)

# GCA

### Autonomous work. Explicit permissions. Inspectable outcomes.

An open source, decision-oriented agent runtime for work you need to understand and control.

[![PyPI](https://img.shields.io/pypi/v/generative-agent-assistant)](https://pypi.org/project/generative-agent-assistant/)
[![Python](https://img.shields.io/badge/python-3.12-blue)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

[Quickstart](#quickstart) · [Capabilities](#what-makes-gca-different) · [Architecture](#architecture) · [Security](SECURITY.md) · [中文介绍](docs/README.zh-CN.md)

</div>

GCA combines a model-driven agent loop, human approval, persistent history and a built-in web interface. Connect your own model and tools; keep control over what the agent can execute and inspect the records behind its answers.

Its design keeps four things distinct: **what was proposed, what was authorized, what executed, and what the evidence supports**. A successful tool call is recorded separately from a verified outcome.

## Quickstart

Use **Python 3.12** in a virtual environment:

```bash
python3.12 -m venv .venv
source .venv/bin/activate
pip install --upgrade generative-agent-assistant
gca init
gca serve
```

Open **http://127.0.0.1:8001** and register a local account.

The wizard asks for an OpenAI-compatible API base URL, model name and API key. Secret prompts do not echo their values. Use `gca doctor` to check configuration and optional integrations.

Configuration and basic local data live in `~/.gca`. To choose another directory, run `gca init --home /path/to/gca-home` and use the same `--home` for `doctor` and `serve`. An upgrade retains this directory; it does not embed it in the package.

## What makes GCA different

| Capability | What it gives you |
|---|---|
| **Model-driven execution** | The model chooses tools, gathers results and adjusts its approach inside a bounded loop. |
| **Explicit human approval** | Controlled actions wait for a decision bound to server-held parameters. Rejection does not authorize a replacement action. |
| **Inspectable decisions** | Where recorded, view candidates, public reasons, expectations and observed results with source locations. Missing facts stay missing. |
| **Work documents for complex tasks** | Separate action and checking documents retain useful goals, progress, evidence summaries and unresolved items. |
| **Independent internal checking** | An optional checking unit uses a restricted tool pool and returns findings to the action loop. It is off by default and has deployment prerequisites. |
| **History on demand** | The agent can query authorized history and source records. History does not silently become new permission or current business truth. |
| **Bring your own tools** | Connect MCP services; generic file, search and delegation tools are included. Domain integrations remain under your control. |
| **One web application** | Chat, approvals, decision history, session observation and memory views are served with the Python package. |

### Things to try

- “Compare these two approaches, explain the tradeoff, and ask me before making the change.”
- “Read my workspace files, prepare a report, and identify what you could not verify.”
- “Find my earlier decision about this task and show the supporting records.”

Available behavior depends on configured tools and storage. The last example's ledger-backed history needs PostgreSQL; missing evidence must not be invented.

## Choose your deployment

| Deployment | Included behavior | You provide |
|---|---|---|
| **Local quickstart** | Authenticated chat, streaming, SQLite session history, generic tools and the web UI | Your model endpoint |
| **Ledger-backed runtime** | PostgreSQL journals, Claim records, decision/history views and persistent personal memory | Provisioned PostgreSQL with the required owner/runtime roles |
| **Background processing** | Asynchronous work and supported command execution | Redis, Taskiq worker and a supported sandbox/runner |
| **File ingestion** | Upload and parsing services | Configured MinIO and applicable parsing services |
| **Enhanced complex tasks** | Task packages, work documents and independent internal checking | PostgreSQL, trusted material storage and compatible model/tool configuration; explicit enablement |

See [deployment and upgrade notes](docs/deployment.md). SQL resources are **empty-schema code**, not user data. Installing the package does not initialize a real PostgreSQL database or grant database privileges.

**The enhanced workflow is disabled by default.** It adds model calls and latency; this release does not claim it improves every task. A requested check that is unavailable must be reported as unmet.

## Architecture

```mermaid
flowchart LR
    U[User goal and authorization] --> A[Action loop]
    A <--> W[Action work document]
    A --> P[Permission and approval gates]
    P --> T[Authorized tools]
    T --> E[Observed results and source records]
    E --> A
    A --> S[Candidate submission]
    S --> C[Optional independent checking loop]
    C <--> D[Checking work document]
    C -->|Specific gaps| A
    C --> R[Controller validates receipt and limits]
    S -->|Ordinary path| R
    R --> F[Deliver, wait, or explain what remains]
```

Models make semantic judgments; program boundaries govern identity, tool availability, permission, versions and bounded continuation. Work documents organize useful context. Raw tool and resource records remain the evidence behind them.

For business applications, connect authorized Ontology views and actions through your integration layer. This release supplies a general runtime; it contains no enterprise Ontology, proprietary business rules or ready-made business data pipeline.

## Connect MCP tools

Edit `$GCA_HOME/mcp.json` and connect a server you operate or trust:

```json
{"servers": [{"id": "my-tools", "url": "http://127.0.0.1:9001/mcp", "enabled": true, "modes": ["agent"]}]}
```

External tool output is not authorization, and tool availability is not a security guarantee. Do not commit real service URLs, authentication headers or credentials.

## Security

The CLI defaults to loopback, generates a deployment-specific JWT secret and writes owner-only configuration. File tools require a bound user workspace and reject traversal and cross-user access. Command execution requires a supported platform boundary; obsolete or unsupported settings disable the capability. There is no automatic unsandboxed fallback.

Release archives use explicit inclusion rules and exclude runtime configuration, databases and logs. Read the [security policy](SECURITY.md), [maintenance cases](docs/security/maintenance-cases.md) and [release validation](docs/security/release-validation.md). These document specific controls and tests, not unconditional safety certification.

## Development

```bash
git clone https://github.com/xualbert83/generative-agent-assistant.git
cd generative-agent-assistant
uv sync --group dev
./scripts/gate.sh
uv build
```

Tests use temporary runtime directories. Never use production credentials or customer data in a test. See [CONTRIBUTING.md](CONTRIBUTING.md).

## License and attribution

GCA's original source is released under the **MIT License**. You may use, modify and redistribute it, including commercially, subject to retaining the copyright and permission notice. The software is provided without warranty; full legal terms are in [LICENSE](LICENSE).

Bundled third-party components retain their own licenses. ECharts, marked, DOMPurify and Source Serif 4 are covered by their respective notices and are not relicensed as GCA code. See [NOTICE](NOTICE.md) and the notices shipped inside the package.

Maintained by **Albert Xu**. Read the [changelog](CHANGELOG.md) or [open an issue](https://github.com/xualbert83/generative-agent-assistant/issues).
