gcontext-ai 0.2.1__tar.gz

gcontext_ai-0.2.1/LICENSE

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

gcontext_ai-0.2.1/PKG-INFO

@@ -0,0 +1,285 @@
+Metadata-Version: 2.4
+Name: gcontext-ai
+Version: 0.2.1
+Summary: gcontext — file-based knowledge protocol for AI agents
+License-Expression: MIT
+Project-URL: Homepage, https://gcontext.ai
+Project-URL: Repository, https://github.com/bleak-ai/gcontext
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic
+Requires-Dist: pyyaml
+Requires-Dist: simple-term-menu
+Dynamic: license-file
+
+# gcontext
+
+**Context engineering for AI agents.**
+
+Build context like you build code: modular, version-controlled, composable.
+
+---
+
+## The problem
+
+AI agents fail for the same reason large codebases fail: **implicit state.**
+
+Prompts become undocumented architecture. Instructions drift between conversations. Context duplicates across files. Memory becomes unreliable. Every session starts with "let me remind you how our deploy works."
+
+This isn't a model problem. It's an engineering problem.
+
+Most teams solve it by writing longer prompts, pasting more docs, or hoping the agent remembers. That works until it doesn't, and it stops working fast.
+
+**gcontext treats context as infrastructure.**
+
+---
+
+## Before and after
+
+**Without structured context:**
+- Giant system prompts nobody maintains
+- Copy-pasted docs that go stale
+- "Remember, our Stripe webhook is at..." every session
+- Agent hallucinates because it can't find what it needs
+- Context bloat kills quality on long tasks
+- Tribal knowledge lives in one person's prompt history
+
+**With gcontext:**
+
+```
+context/
+  modules-repo/
+    stripe/            → API keys, webhooks, how to query invoices
+    postgres/          → schema, migrations, connection details
+    deploy-pipeline/   → step-by-step release to production
+    bug-triage/        → how to investigate and classify issues
+```
+
+Each module is a self-contained unit of context. Load what the task needs, unload what it doesn't. The agent navigates to what's relevant. Nothing else enters the window.
+
+![gcontext demo](demo/gcontext-claude-demo.gif)
+
+---
+
+## Install
+
+```bash
+curl -LsSf https://gcontext.ai/gcontext/install.sh | sh
+```
+
+<details>
+<summary>Alternative methods</summary>
+
+```bash
+# Via uv
+uv tool install gcontext
+
+# Via pip
+pip install gcontext
+```
+</details>
+
+## Quick start
+
+**1. Initialize your workspace**
+
+```bash
+$ gcontext init
+
+context/
+  llms.txt
+  integrations/
+  workflows/
+  tasks/
+```
+
+**2. Add an integration**
+
+```
+$ claude → "Add a postgres integration"
+
+Creating context/integrations/postgres/
+  info.md        ← context about the integration
+  llms.txt       ← navigation for the agent
+  module.yaml    ← secrets: [PG_URL]
+✓ Module created. Requires PG_URL to populate.
+```
+
+**3. Provide the secret it needs**
+
+```bash
+# Add PG_URL to your .env file
+echo "PG_URL=postgres://..." >> .env
+```
+
+**4. The agent fills in the context**
+
+```
+$ claude → "Explore the postgres integration and add the info to postgres/info.md"
+
+Connecting with PG_URL...
+  Found 12 tables, 47 columns, 8 relationships
+  Writing schema to info.md
+✓ Module ready. Agent knows your database.
+```
+
+**5. Query your data, add context anytime**
+
+```
+$ claude → "How many users signed up this week?"
+
+Reads info.md → already knows users table has created_at
+47 users. Free: 31, Pro: 12, Enterprise: 4
+```
+
+Need more context? The agent can add new modules anytime.
+
+---
+
+## How it works: composable context
+
+gcontext introduces one core mechanic: **composable context**.
+
+Modules are independent units of knowledge: an API integration, a deployment procedure, a bug investigation. Each contains plain markdown and a navigation index (`llms.txt`) the agent uses to find what it needs.
+
+```
+agent reads system.md
+  └─ follows llms.txt index
+       ├─ stripe/llms.txt    → "here's how Stripe works here"
+       ├─ postgres/llms.txt  → "here's the database"
+       └─ deploy/llms.txt    → "here's how to ship"
+            └─ steps.md      → the actual procedure
+```
+
+**Navigation, not retrieval.** The agent walks a knowledge tree. It doesn't search a vector space. Deterministic, inspectable, reproducible.
+
+You version-control your code. You version-control your docs. Now version-control what your AI agent knows.
+
+## Module kinds
+
+| Kind | What it captures | Lifecycle | Example |
+|------|-----------------|-----------|---------|
+| **Integration** | How to use an external service, API, or database | Permanent: lives as long as the service does | Stripe, Postgres, GitHub, Slack |
+| **Workflow** | A repeatable procedure that improves over time | Long-lived: gets better with each run | Deploy to prod, triage bugs, onboard a teammate |
+| **Task** | A bounded piece of work with progress tracking | Disposable: done when the work is done | Fix billing bug, migrate auth, ship feature X |
+
+Different shapes for different lifecycles. They coexist and compose.
+
+---
+
+## Real workflows
+
+**Software engineering team**
+
+```
+context/
+  modules-repo/
+    postgres/          → schema, connection, query patterns
+    github/            → repo structure, PR conventions, CI
+    deploy-pipeline/   → release steps, rollback procedures
+    fix-billing-bug/   → task: reproduce, investigate, fix, verify
+```
+
+The agent reads the database schema, understands CI, follows the deploy playbook, and tracks progress on the billing fix, all from structured context.
+
+**Support automation**
+
+```
+context/
+  modules-repo/
+    zendesk/           → API access, ticket categories, macros
+    stripe/            → subscription lookup, refund procedures
+    knowledge-base/    → product docs, known issues, FAQ
+    escalation/        → workflow: when and how to escalate
+```
+
+An agent triaging tickets reads the Zendesk integration, checks Stripe for billing context, references the KB, and follows escalation rules, without a 10,000-token system prompt.
+
+**Content pipeline**
+
+```
+context/
+  modules-repo/
+    cms/               → API, content models, publishing flow
+    brand-voice/       → tone guidelines, examples, anti-patterns
+    analytics/         → what performs, audience segments
+    weekly-newsletter/ → task: this week's edition
+```
+
+**Claude Code / Cursor workflow**
+
+```
+context/
+  modules-repo/
+    codebase/          → architecture, conventions, key paths
+    cloudflare/        → DNS, workers, deployment targets
+    monitoring/        → Grafana dashboards, alert rules
+    ship-v2-auth/      → task: migrate auth with progress tracking
+```
+
+Point your coding agent at the workspace. It navigates to the module it needs per task: your codebase conventions when writing code, your deploy integration when shipping, your monitoring setup when debugging production.
+
+---
+
+## What gcontext is not
+
+gcontext is not:
+
+- **A vector database.** No embeddings. The agent navigates a file tree, not a similarity search.
+- **A memory model.** No implicit memory. Context is explicit, human-curated, version-controlled.
+- **A replacement for RAG.** Complementary. gcontext structures the knowledge RAG can retrieve from.
+- **An autonomous agent framework.** No agent runtime. Works with the agent you already use.
+- **Another orchestration layer.** No workflow engine. Just structured, navigable knowledge.
+
+**gcontext is a context engineering toolkit.** It gives your agent a composable knowledge base it can navigate itself.
+
+---
+
+## Why the filesystem
+
+> "Why not just use a vector database / memory layer?"
+
+| | Filesystem (gcontext) | Vector DB / Memory |
+|---|---|---|
+| **Version control** | `git diff`, `git blame`, full history | Requires custom versioning |
+| **Inspectability** | Open a folder, read the files | Query an API, decode embeddings |
+| **Determinism** | Same files = same context, every time | Similarity search varies |
+| **Human readability** | It's markdown | It's vectors |
+| **Composability** | Load/unload modules like imports | Rebuild index on every change |
+| **Tooling** | Works with every editor, CI, linter | Needs specialized tooling |
+| **Portability** | Copy the folder | Export, migrate, re-index |
+
+The filesystem is the most universal, inspectable, composable storage layer that exists. Your agent's context should be as maintainable as the code it operates on.
+
+---
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `gcontext init` | Create a new workspace |
+| `gcontext new <kind> <name>` | Scaffold a module |
+| `gcontext load <name> [...]` | Activate modules in the workspace |
+| `gcontext unload <name>` | Deactivate a module |
+| `gcontext ls` | List all modules and their status |
+| `gcontext env` | Check if required secrets are set |
+| `gcontext validate [name]` | Verify module structure |
+
+## Works with everything
+
+gcontext produces plain markdown files with a navigable index. Any AI that reads files can use it:
+
+Claude Code, Cursor, Windsurf, Copilot, ChatGPT, Codex. If it reads files, it reads gcontext.
+
+## Secrets
+
+Modules can declare required environment variables. Values go in `.env` (gitignored). Run `gcontext env` to check what's missing.
+
+## gcontext Cloud
+
+For a web UI with built-in AI chat, visual module editor, secrets management, and more, see [gcontext Cloud](https://gcontext.ai).
+
+---
+
+Built by [Bleak AI](https://bleakai.com) | [gcontext.ai](https://gcontext.ai)

gcontext_ai-0.2.1/README.md

@@ -0,0 +1,270 @@
+# gcontext
+
+**Context engineering for AI agents.**
+
+Build context like you build code: modular, version-controlled, composable.
+
+---
+
+## The problem
+
+AI agents fail for the same reason large codebases fail: **implicit state.**
+
+Prompts become undocumented architecture. Instructions drift between conversations. Context duplicates across files. Memory becomes unreliable. Every session starts with "let me remind you how our deploy works."
+
+This isn't a model problem. It's an engineering problem.
+
+Most teams solve it by writing longer prompts, pasting more docs, or hoping the agent remembers. That works until it doesn't, and it stops working fast.
+
+**gcontext treats context as infrastructure.**
+
+---
+
+## Before and after
+
+**Without structured context:**
+- Giant system prompts nobody maintains
+- Copy-pasted docs that go stale
+- "Remember, our Stripe webhook is at..." every session
+- Agent hallucinates because it can't find what it needs
+- Context bloat kills quality on long tasks
+- Tribal knowledge lives in one person's prompt history
+
+**With gcontext:**
+
+```
+context/
+  modules-repo/
+    stripe/            → API keys, webhooks, how to query invoices
+    postgres/          → schema, migrations, connection details
+    deploy-pipeline/   → step-by-step release to production
+    bug-triage/        → how to investigate and classify issues
+```
+
+Each module is a self-contained unit of context. Load what the task needs, unload what it doesn't. The agent navigates to what's relevant. Nothing else enters the window.
+
+![gcontext demo](demo/gcontext-claude-demo.gif)
+
+---
+
+## Install
+
+```bash
+curl -LsSf https://gcontext.ai/gcontext/install.sh | sh
+```
+
+<details>
+<summary>Alternative methods</summary>
+
+```bash
+# Via uv
+uv tool install gcontext
+
+# Via pip
+pip install gcontext
+```
+</details>
+
+## Quick start
+
+**1. Initialize your workspace**
+
+```bash
+$ gcontext init
+
+context/
+  llms.txt
+  integrations/
+  workflows/
+  tasks/
+```
+
+**2. Add an integration**
+
+```
+$ claude → "Add a postgres integration"
+
+Creating context/integrations/postgres/
+  info.md        ← context about the integration
+  llms.txt       ← navigation for the agent
+  module.yaml    ← secrets: [PG_URL]
+✓ Module created. Requires PG_URL to populate.
+```
+
+**3. Provide the secret it needs**
+
+```bash
+# Add PG_URL to your .env file
+echo "PG_URL=postgres://..." >> .env
+```
+
+**4. The agent fills in the context**
+
+```
+$ claude → "Explore the postgres integration and add the info to postgres/info.md"
+
+Connecting with PG_URL...
+  Found 12 tables, 47 columns, 8 relationships
+  Writing schema to info.md
+✓ Module ready. Agent knows your database.
+```
+
+**5. Query your data, add context anytime**
+
+```
+$ claude → "How many users signed up this week?"
+
+Reads info.md → already knows users table has created_at
+47 users. Free: 31, Pro: 12, Enterprise: 4
+```
+
+Need more context? The agent can add new modules anytime.
+
+---
+
+## How it works: composable context
+
+gcontext introduces one core mechanic: **composable context**.
+
+Modules are independent units of knowledge: an API integration, a deployment procedure, a bug investigation. Each contains plain markdown and a navigation index (`llms.txt`) the agent uses to find what it needs.
+
+```
+agent reads system.md
+  └─ follows llms.txt index
+       ├─ stripe/llms.txt    → "here's how Stripe works here"
+       ├─ postgres/llms.txt  → "here's the database"
+       └─ deploy/llms.txt    → "here's how to ship"
+            └─ steps.md      → the actual procedure
+```
+
+**Navigation, not retrieval.** The agent walks a knowledge tree. It doesn't search a vector space. Deterministic, inspectable, reproducible.
+
+You version-control your code. You version-control your docs. Now version-control what your AI agent knows.
+
+## Module kinds
+
+| Kind | What it captures | Lifecycle | Example |
+|------|-----------------|-----------|---------|
+| **Integration** | How to use an external service, API, or database | Permanent: lives as long as the service does | Stripe, Postgres, GitHub, Slack |
+| **Workflow** | A repeatable procedure that improves over time | Long-lived: gets better with each run | Deploy to prod, triage bugs, onboard a teammate |
+| **Task** | A bounded piece of work with progress tracking | Disposable: done when the work is done | Fix billing bug, migrate auth, ship feature X |
+
+Different shapes for different lifecycles. They coexist and compose.
+
+---
+
+## Real workflows
+
+**Software engineering team**
+
+```
+context/
+  modules-repo/
+    postgres/          → schema, connection, query patterns
+    github/            → repo structure, PR conventions, CI
+    deploy-pipeline/   → release steps, rollback procedures
+    fix-billing-bug/   → task: reproduce, investigate, fix, verify
+```
+
+The agent reads the database schema, understands CI, follows the deploy playbook, and tracks progress on the billing fix, all from structured context.
+
+**Support automation**
+
+```
+context/
+  modules-repo/
+    zendesk/           → API access, ticket categories, macros
+    stripe/            → subscription lookup, refund procedures
+    knowledge-base/    → product docs, known issues, FAQ
+    escalation/        → workflow: when and how to escalate
+```
+
+An agent triaging tickets reads the Zendesk integration, checks Stripe for billing context, references the KB, and follows escalation rules, without a 10,000-token system prompt.
+
+**Content pipeline**
+
+```
+context/
+  modules-repo/
+    cms/               → API, content models, publishing flow
+    brand-voice/       → tone guidelines, examples, anti-patterns
+    analytics/         → what performs, audience segments
+    weekly-newsletter/ → task: this week's edition
+```
+
+**Claude Code / Cursor workflow**
+
+```
+context/
+  modules-repo/
+    codebase/          → architecture, conventions, key paths
+    cloudflare/        → DNS, workers, deployment targets
+    monitoring/        → Grafana dashboards, alert rules
+    ship-v2-auth/      → task: migrate auth with progress tracking
+```
+
+Point your coding agent at the workspace. It navigates to the module it needs per task: your codebase conventions when writing code, your deploy integration when shipping, your monitoring setup when debugging production.
+
+---
+
+## What gcontext is not
+
+gcontext is not:
+
+- **A vector database.** No embeddings. The agent navigates a file tree, not a similarity search.
+- **A memory model.** No implicit memory. Context is explicit, human-curated, version-controlled.
+- **A replacement for RAG.** Complementary. gcontext structures the knowledge RAG can retrieve from.
+- **An autonomous agent framework.** No agent runtime. Works with the agent you already use.
+- **Another orchestration layer.** No workflow engine. Just structured, navigable knowledge.
+
+**gcontext is a context engineering toolkit.** It gives your agent a composable knowledge base it can navigate itself.
+
+---
+
+## Why the filesystem
+
+> "Why not just use a vector database / memory layer?"
+
+| | Filesystem (gcontext) | Vector DB / Memory |
+|---|---|---|
+| **Version control** | `git diff`, `git blame`, full history | Requires custom versioning |
+| **Inspectability** | Open a folder, read the files | Query an API, decode embeddings |
+| **Determinism** | Same files = same context, every time | Similarity search varies |
+| **Human readability** | It's markdown | It's vectors |
+| **Composability** | Load/unload modules like imports | Rebuild index on every change |
+| **Tooling** | Works with every editor, CI, linter | Needs specialized tooling |
+| **Portability** | Copy the folder | Export, migrate, re-index |
+
+The filesystem is the most universal, inspectable, composable storage layer that exists. Your agent's context should be as maintainable as the code it operates on.
+
+---
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `gcontext init` | Create a new workspace |
+| `gcontext new <kind> <name>` | Scaffold a module |
+| `gcontext load <name> [...]` | Activate modules in the workspace |
+| `gcontext unload <name>` | Deactivate a module |
+| `gcontext ls` | List all modules and their status |
+| `gcontext env` | Check if required secrets are set |
+| `gcontext validate [name]` | Verify module structure |
+
+## Works with everything
+
+gcontext produces plain markdown files with a navigable index. Any AI that reads files can use it:
+
+Claude Code, Cursor, Windsurf, Copilot, ChatGPT, Codex. If it reads files, it reads gcontext.
+
+## Secrets
+
+Modules can declare required environment variables. Values go in `.env` (gitignored). Run `gcontext env` to check what's missing.
+
+## gcontext Cloud
+
+For a web UI with built-in AI chat, visual module editor, secrets management, and more, see [gcontext Cloud](https://gcontext.ai).
+
+---
+
+Built by [Bleak AI](https://bleakai.com) | [gcontext.ai](https://gcontext.ai)

gcontext_ai-0.2.1/core/__init__.py

@@ -0,0 +1 @@
+# empty package marker