Metadata-Version: 2.4
Name: agentculture-cli
Version: 0.8.0
Summary: Workshop and scaffolding CLI for practical AI efficiency: learn core AI concepts, build your first agents, create useful CLIs, and adopt agent-first development patterns
Project-URL: Homepage, https://github.com/agentculture/culture-guide
Project-URL: Issues, https://github.com/agentculture/culture-guide/issues
Author: AgentCulture
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.12
Requires-Dist: strands-agents[openai]
Requires-Dist: telegram-agent[telegram]
Description-Content-Type: text/markdown

# culture-guide

Workshop and scaffolding CLI for practical AI efficiency: learn core AI concepts, build your first agents, create useful CLIs, and adopt agent-first development patterns

## What you get

- **An agent-first CLI** cited from [teken](https://github.com/agentculture/teken)
  (`afi-cli`) — the runtime package has no third-party dependencies.
- **A mesh identity** — `culture.yaml` (`suffix` + `backend`) and the matching
  prompt file for that backend (this repo ships `backend: colleague` →
  `AGENTS.colleague.md`; `claude` → `CLAUDE.md`, `acp` → `AGENTS.md`,
  `gemini` → `GEMINI.md`).
- **The canonical guildmaster skill kit** (11 skills) under `.claude/skills/`,
  vendored cite-don't-import. See [`docs/skill-sources.md`](docs/skill-sources.md).
- **A build + deploy baseline** — pytest, lint, the agent-first rubric gate, and
  PyPI Trusted Publishing wired into GitHub Actions.
- **The named paradigm** — [`docs/culture.md`](docs/culture.md) names the culture
  every cloned agent inherits (agent-first CLI, cite-don't-import, learn→teach,
  the all-backends rule, converge-don't-vibe, …) and cites where each tenet is
  enforced. Addressable from the CLI: `culture-guide explain culture`.

## Quickstart

```bash
uv sync
uv run pytest -n auto                 # run the test suite
uv run culture-guide whoami            # identity from culture.yaml
uv run culture-guide learn             # self-teaching prompt (add --json)
uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
```

## CLI

| Verb | What it does |
|------|--------------|
| `whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
| `learn` | Print a structured self-teaching prompt. |
| `explain <path>` | Markdown docs for any noun/verb path. |
| `overview` | Read-only descriptive snapshot of the agent. |
| `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
| `cli overview` | Describe the CLI surface itself. |

Every command supports `--json`. Results go to stdout, errors/diagnostics to
stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
error, `3+` reserved.

## Make it your own

1. Rename the package `culture_guide/` and the `culture-guide`
   CLI/dist name throughout `pyproject.toml`, the package, `tests/`,
   `sonar-project.properties`, and this `README.md`. The name is hard-coded in
   ~100 places, so list every occurrence first — see the `git grep` discovery
   command in [`CLAUDE.md`](CLAUDE.md), the authoritative rename procedure.
2. Edit `culture.yaml` with your `suffix` and `backend`.
3. Rewrite `CLAUDE.md` for your agent and run `/init`.
4. Re-vendor only the skills you need from guildmaster (see
   [`docs/skill-sources.md`](docs/skill-sources.md)).

See [`CLAUDE.md`](CLAUDE.md) for the full conventions (version-bump-every-PR,
the `cicd` PR lane, deploy setup).

## Constant Colleague (Telegram responder)

A supervised, reset-surviving Telegram responder managed from the culture-guide CLI; it listens to a group and answers via an OpenAI/vLLM agent loop (strands-agents), colleague-swappable later.

### Configure

Set these environment variables (via `.env` or your shell):

- `TELEGRAM_AGENT_BOT_TOKEN` — your Telegram bot token
- `CONSTANT_COLLEAGUE_CHAT_ID` — the Telegram group/chat ID to listen on
- `COLLEAGUE_BASE_URL` — OpenAI-compatible endpoint (default `http://localhost:8001/v1`)
- `COLLEAGUE_MODEL` — model name to use
- `CONSTANT_COLLEAGUE_BOT_USERNAME` — the bot's display username
- `CONSTANT_COLLEAGUE_POLL_INTERVAL` — seconds between getUpdates polls

### Run

```bash
culture-guide listen start      # install + enable systemd --user unit (survives reboot)
culture-guide listen status     # is it live?
culture-guide listen stop
culture-guide listen restart
culture-guide listen logs       # prints the journalctl --user command
```

### How it works

Pipeline: telegram-agent (receive getUpdates + send) → relevance gate (tag-override bypass; else reranker B → chat A cascade on the lobes vLLM endpoint; A-only fallback) → strands-agents agent loop (the mind) → reply; per-chat memory via eidetic; supervised by a systemd --user unit with lingering so it resumes after a server reset.

This added two runtime deps (telegram-agent[telegram], strands-agents[openai]) — culture-guide is no longer zero-third-party-dep.

## License

Apache 2.0 — see [`LICENSE`](LICENSE).
