Metadata-Version: 2.4
Name: citnega
Version: 0.6.0
Summary: Local-first agentic assistant — terminal UI and pluggable agent runtime
Project-URL: Homepage, https://github.com/8prabhat/citnega
Project-URL: Repository, https://github.com/8prabhat/citnega
Project-URL: Issues, https://github.com/8prabhat/citnega/issues
Author: Citnega contributors
License: MIT
Keywords: agent,agentic,ai,assistant,llm,terminal,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Terminals
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20
Requires-Dist: alembic>=1.14
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=25.0
Requires-Dist: platformdirs>=4.3
Requires-Dist: pydantic-settings>=2.7
Requires-Dist: pydantic>=2.10
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: structlog>=25.0
Requires-Dist: textual>=8.2
Requires-Dist: tiktoken>=0.8
Requires-Dist: typer>=0.15
Provides-Extra: adk
Requires-Dist: google-adk>=0.1; extra == 'adk'
Provides-Extra: all
Requires-Dist: crewai>=0.70; extra == 'all'
Requires-Dist: google-adk>=0.1; extra == 'all'
Requires-Dist: langgraph>=0.2; extra == 'all'
Provides-Extra: crewai
Requires-Dist: crewai>=0.70; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: freezegun>=1.5; extra == 'dev'
Requires-Dist: hypothesis>=6.130; extra == 'dev'
Requires-Dist: import-linter>=2.5; extra == 'dev'
Requires-Dist: mypy>=1.15; extra == 'dev'
Requires-Dist: pre-commit>=4.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
Requires-Dist: pytest>=9.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: sqlite-utils>=3.38; extra == 'dev'
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.2; extra == 'langgraph'
Description-Content-Type: text/markdown

# Citnega

**Citnega** is a local-first agentic assistant — a full-featured terminal UI backed by a production-grade agent runtime. It runs conversations, calls tools in parallel, compiles plans, and routes tasks to specialists, all from a single `citnega` command.

```
pip install citnega
citnega
```

---

## Features

- **Terminal UI** built on [Textual](https://textual.textualize.io/) — keyboard-driven, themeable, no browser required
- **Pluggable framework adapters** — swap between `direct` (built-in), Google ADK, LangGraph, or CrewAI without changing application code
- **Parallel tool execution** — independent tool calls fan out concurrently via `asyncio.TaskGroup`
- **Plan mode** — draft → approve → execute multi-step plans with a structured compiler and scheduler
- **Persistent knowledge base** — full-text search, tagging, and session-scoped KB retrieval
- **Workspace overlay** — drop custom agents, tools, workflows, and skills into a workfolder; they override built-ins by name
- **Conversation compaction** — automatic summarisation keeps context within token budget
- **Policy enforcement** — file path bounds, network controls, approval gates, per-tool overrides
- **Circuit breaker** per model provider with configurable thresholds and cooldown

---

## Installation

```bash
# Core (direct adapter, built-in tools)
pip install citnega

# With Google ADK support
pip install "citnega[adk]"

# With LangGraph
pip install "citnega[langgraph]"

# With CrewAI
pip install "citnega[crewai]"

# Everything
pip install "citnega[all]"
```

Requires Python 3.11+.

---

## Quick Start

```bash
# Launch the TUI
citnega

# New session directly
citnega --session my-project

# Headless CLI
citnega-cli run --session my-session --prompt "Summarise the latest changes in this repo"

# List sessions
citnega-cli session list
```

### TUI keyboard shortcuts

| Key | Action |
|-----|--------|
| `Enter` | Send message |
| `↑` / `↓` | Browse input history |
| `/` | Start a slash command |
| `Ctrl+K` | Open command palette |
| `Ctrl+Y` | Copy last response |
| `Ctrl+L` | Clear chat |
| `Ctrl+C` | Quit |

### Slash commands

| Command | Description |
|---------|-------------|
| `/model [id]` | Show or switch the active model |
| `/mode [name]` | Switch session mode (`chat`, `plan`, `explore`, …) |
| `/think [on\|off\|auto]` | Toggle extended thinking |
| `/compact` | Compact conversation history |
| `/sessions` | List all sessions |
| `/new` | Start a new session |
| `/rename <name>` | Rename current session |
| `/setworkfolder <path>` | Point to a workfolder |
| `/createtool` | Scaffold a new custom tool |
| `/createagent` | Scaffold a new custom agent |
| `/createworkflow` | Scaffold a new workflow |
| `/help` | List all commands |

---

## Configuration

Config lives in the platform app-home directory:

| Platform | Path |
|----------|------|
| macOS | `~/Library/Application Support/citnega/config/` |
| Linux | `~/.local/share/citnega/config/` |
| Windows | `%APPDATA%\citnega\config\` |

Key files:

- `settings.toml` — runtime, session, model, logging, workspace, policy settings
- `models.yaml` — model registry (providers, priorities, thinking flags)

All settings can also be set via environment variables with the `CITNEGA_` prefix:

```bash
CITNEGA_RUNTIME__DEFAULT_MODEL_ID=gpt-4o citnega
CITNEGA_NEXTGEN__PLANNING_ENABLED=true citnega
```

### Minimal `settings.toml`

```toml
[runtime]
default_model_id = "gpt-4o"
local_only       = false

[workspace]
workfolder_path = "/home/you/my-citnega-workspace"
```

---

## Workfolder

A workfolder is a directory that extends Citnega with your own agents, tools, and workflows. Workfolder callables override built-ins of the same name.

```
my-workspace/
├── agents/          # custom agent modules
├── tools/           # custom tool modules
├── workflows/       # YAML or Python workflow definitions
├── skills/          # SKILL.md bundles
└── memory/          # runtime state (sessions, KB, logs, artifacts)
    ├── db/
    ├── sessions/
    ├── kb/
    └── logs/
```

Set the path via `/setworkfolder` in the TUI, or in `settings.toml`:

```toml
[workspace]
workfolder_path = "/absolute/path/to/workspace"
```

### Custom tool example

```python
# my-workspace/tools/summarise.py
from citnega.packages.protocol.interfaces.tool import ITool, ToolResult

class SummariseTool(ITool):
    name        = "summarise"
    description = "Summarise a block of text in one paragraph."

    async def invoke(self, input, ctx):
        text = input.get("text", "")
        # ... call your model / logic here
        return ToolResult(output=summary)
```

---

## Built-in Tools

| Tool | Description |
|------|-------------|
| `read_file` | Read a file from disk |
| `write_file` | Write or create a file |
| `edit_file` | Apply targeted edits to a file |
| `list_dir` | List directory contents |
| `search_files` | Full-text search across a file tree |
| `run_shell` | Execute a shell command |
| `git_ops` | Git status, diff, log, commit, push |
| `web_search` | Search the web (requires provider) |
| `read_kb` | Retrieve from the persistent knowledge base |
| `write_kb` | Save a note or document to the KB |
| `repo_map` | Generate a structural map of a repository |
| `quality_gate` | Run linters and type-checkers |
| `test_matrix` | Discover and run test suites |

---

## Architecture

```
apps/
  tui/       — Textual TUI (ChatScreen, widgets, controllers)
  cli/       — Typer CLI (citnega-cli)
packages/
  bootstrap/ — Dependency composition and startup
  runtime/   — CoreRuntime, ApplicationService, SessionManager
  adapters/  — Framework adapters (direct, ADK, LangGraph, CrewAI)
  agents/    — Built-in agents (conversation, planner, specialist)
  tools/     — Built-in tools
  planning/  — PlanCompiler, PlanScheduler, TaskClassifier
  execution/ — ExecutionEngine (parallel batch runner)
  strategy/  — StrategySpec, SkillLoader, MentalModelCompiler
  capabilities/ — CapabilityRegistry and descriptors
  model_gateway/ — Provider abstraction, retry, circuit breaker
  context/   — Context assembly pipeline (handlers, token budget)
  kb/        — Knowledge base (SQLite FTS5)
  workspace/ — Workfolder loader and overlay
  config/    — Pydantic settings, TOML loaders
  protocol/  — Shared interfaces, events, models (no deps)
```

The `protocol` package defines all interfaces and events; every other package depends on it but not on each other, enforcing a clean dependency graph.

---

## Development

```bash
git clone https://github.com/8prabhat/citnega.git
cd citnega
uv sync --all-extras
uv run citnega
```

### Tests

```bash
uv run pytest                    # full suite
uv run pytest tests/unit/        # unit tests only
uv run pytest tests/integration/ # integration tests
uv run pytest --cov --cov-report=term-missing
```

### Linting

```bash
uv run ruff check .
uv run mypy packages apps --ignore-missing-imports
uv run lint-imports --config import-linter.ini
```

### Release

Tag a version to trigger automated PyPI publishing via GitHub Actions:

```bash
git tag v0.6.0
git push origin v0.6.0
```

The `release.yml` workflow builds the wheel, runs tests, and publishes to PyPI using trusted publishing (OIDC — no API token required).

---

## License

MIT © 2025 Citnega contributors
