navaia-code 1.0.50__tar.gz

navaia_code-1.0.50/.env.example

@@ -0,0 +1,40 @@
+# Navaia Code — LLM provider configuration
+# Copy to .env and fill in your values.
+
+# Which provider to use. One of: openrouter | internal | qwen | ollama
+NAVAIA_PROVIDER=openrouter
+
+# --- OpenRouter (cloud) ---
+OPENROUTER_API_KEY=sk-or-v1-your-key-here
+# NAVAIA_OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+# Default is gpt-oss-120b.
+# Swap for a different one by uncommenting and editing:
+# NAVAIA_OPENROUTER_MODEL=gpt-oss-120b
+# NAVAIA_OPENROUTER_MODEL=minimax/minimax-m2
+# NAVAIA_OPENROUTER_MODEL=anthropic/claude-sonnet-4.6
+# NAVAIA_OPENROUTER_MODEL=openai/gpt-4o
+# NAVAIA_OPENROUTER_TIMEOUT=120
+
+# --- Internal vLLM (no API key needed) ---
+# NAVAIA_INTERNAL_BASE_URL=https://ngx.tawakkalna.nic.gov.sa/v1
+# NAVAIA_INTERNAL_MODEL=/models/gpt-oss-120b
+# NAVAIA_INTERNAL_TIMEOUT=500
+# NAVAIA_INTERNAL_VERIFY_SSL=false
+
+# --- Local Qwen (or any OpenAI-compatible server you host) ---
+# Works with vLLM, llama.cpp --server, LM Studio, text-generation-webui, SGLang, etc.
+# Start your server first, then point these at it:
+#   vLLM:             python -m vllm.entrypoints.openai.api_server --model Qwen/Qwen2.5-7B-Instruct --port 8000
+#   llama.cpp:        ./server -m qwen2.5-7b-instruct-q4.gguf --port 8080
+#   LM Studio:        enable "Local Server" tab (default :1234)
+# NAVAIA_QWEN_BASE_URL=http://localhost:8000/v1
+# NAVAIA_QWEN_MODEL=Qwen/Qwen2.5-7B-Instruct
+# NAVAIA_QWEN_TIMEOUT=300
+# NAVAIA_QWEN_VERIFY_SSL=true
+# QWEN_API_KEY=empty            # most local servers don't check this
+
+# --- Ollama (local, default port 11434) ---
+# Run `ollama pull qwen2.5:7b` then `ollama serve`, then:
+# NAVAIA_OLLAMA_BASE_URL=http://localhost:11434/v1
+# NAVAIA_OLLAMA_MODEL=qwen2.5:7b
+# NAVAIA_OLLAMA_TIMEOUT=300

navaia_code-1.0.50/.genexa/commands/code.md

@@ -0,0 +1,161 @@
+---
+name: code
+description: How to approach any coding task — plan a todo list, tell the user, do the work, and verify every change with a shell command before claiming success.
+---
+
+# /code — Disciplined Coding Workflow
+
+You are about to write or change code. Many small mistakes come from skipping
+structure: jumping to an edit before understanding the file, claiming a change
+landed without checking, or doing several steps silently and losing the user.
+Follow the workflow below **every time** you do a coding task. Do not skip
+steps "because the task looks small" — the workflow is what keeps small tasks
+from turning into broken ones.
+
+---
+
+## 1. Understand before you touch
+
+Before writing or editing any file:
+
+1. **Restate the task** in one or two sentences so the user can correct you
+   early if you misunderstood.
+2. **Read the relevant files first.** Use the `Read` tool on the exact file
+   you intend to change. If you do not know which file, use `Grep` / `Glob`
+   to locate it. Never edit a file you have not read in this session.
+3. **Identify the smallest correct change.** Do not refactor surrounding
+   code, do not "improve" unrelated logic, do not add features that were
+   not requested.
+
+If anything is ambiguous, ask the user one focused question instead of
+guessing.
+
+---
+
+## 2. Make a todo list — and show it
+
+For any task with **more than one step** (which is almost every coding task),
+use the `TodoWrite` tool to record the plan **before** you start editing.
+
+Rules for the todo list:
+
+- One concrete action per item. Bad: "fix bug". Good:
+  "Add `--retry` flag to `genexa/cli.py:parse_args`".
+- Order items in the sequence you will actually do them.
+- Include a final verification item (see step 4).
+- Mark exactly **one** item as `in_progress` at a time. Mark it `completed`
+  the moment that step is done — do not batch completions at the end.
+
+**Tell the user the plan.** After calling `TodoWrite`, write a short message
+to the user that says, in plain prose, what you are about to do. Example:
+
+> Here's the plan:
+> 1. Read `genexa/foo.py` to find the handler.
+> 2. Add a `timeout` parameter with default `30`.
+> 3. Update the one call site in `genexa/bar.py`.
+> 4. Run the test file to confirm nothing broke.
+
+Then start step 1. Whenever you move to the next item, update the todo list
+with `TodoWrite` and briefly tell the user which step you are on. The user
+should always know which step is active without having to ask.
+
+---
+
+## 3. Make the change
+
+For each item on the todo list:
+
+- Use `Edit` for modifying existing files. Use `Write` only for creating new
+  files or full rewrites — `Write` will overwrite. You **must** have used
+  `Read` on the file first.
+- Keep the diff minimal. Only change what the step calls for.
+- Preserve existing style: indentation, quoting, import order, type-hint
+  conventions. Match the file you are editing.
+- Do not add comments, docstrings, or type annotations to code you did not
+  change.
+- Do not add error handling for situations that cannot happen, and do not
+  add backwards-compatibility shims unless the user asked.
+
+---
+
+## 4. Verify every change with a shell command (mandatory)
+
+After **every** file write or edit, run a `Bash` command that proves the
+change is actually on disk and correct. Never claim "added" or "done" based
+on the tool's success message alone — the tool can succeed and the content
+can still be wrong (wrong path, wrong indent, partial replacement, stale
+content from a tool error).
+
+Pick the verification that fits the change. Examples:
+
+- **Added a new file** → confirm it exists and inspect it:
+  ```
+  ls -la <path> && wc -l <path> && sed -n '1,40p' <path>
+  ```
+- **Added a function / symbol** → grep for the new symbol in the file:
+  ```
+  grep -n "def my_new_function" <path>
+  ```
+- **Edited an existing line** → grep for the new content AND confirm the
+  old content is gone:
+  ```
+  grep -n "new_text" <path>
+  grep -n "old_text" <path>     # should print nothing
+  ```
+- **Added an import or config key** → grep for it in the actual file.
+- **New CLI flag / behavior** → run the command and check the output:
+  ```
+  python -m genexa --help | grep -- --retry
+  ```
+- **Python change** → at minimum, byte-compile to catch syntax errors:
+  ```
+  python -m py_compile <path>
+  ```
+  If tests exist for the area, run only the relevant ones:
+  ```
+  pytest tests/test_foo.py -k my_change -q
+  ```
+
+If verification fails:
+
+1. **Stop.** Do not move to the next todo item.
+2. Re-read the file with `Read` to see the real current state.
+3. Diagnose the root cause — wrong path, wrong `old_string`, indentation
+   mismatch, etc. Do not retry the identical action blindly.
+4. Fix it, then verify again.
+
+Only mark the todo item `completed` once the verification command shows the
+expected result.
+
+---
+
+## 5. Keep the user informed
+
+Communicate proactively but tersely:
+
+- Announce the plan once, after `TodoWrite` (step 2).
+- When you move to a new step, say which step in one short line.
+- When verification passes, say so in one short line (e.g. "Verified:
+  `grep` shows the new import on line 12.").
+- When verification fails, say so plainly and describe what you will do
+  next.
+- At the very end, give a short summary: which files changed, what each
+  change does, and how you verified it.
+
+Do **not** narrate every keystroke, do not paste the full file back, and do
+not summarize what the user can already see in the diff.
+
+---
+
+## 6. Finishing
+
+Before you tell the user the task is complete:
+
+- [ ] Every todo item is `completed` (none `in_progress`, none `pending`).
+- [ ] Every file change has a passing verification command on the record.
+- [ ] No unrelated files were modified.
+- [ ] No secrets, API keys, or credentials were added to source.
+- [ ] If you ran tests, they passed; if you did not, you said so honestly.
+
+Then give the final summary to the user. If anything is incomplete, say so
+explicitly — never claim success you have not verified.

navaia_code-1.0.50/.genexa/commands/testSkill.md

@@ -0,0 +1,12 @@
+---
+description: A throwaway skill used to verify slash-command discovery and dispatch.
+---
+
+# testSkill
+
+You are running the testSkill command. Respond with exactly one line:
+
+`TESTSKILL_OK <args>`
+
+where `<args>` is whatever was passed after /testSkill (or `NONE` if no args).
+Do not explain anything. Do not add any other text.

navaia_code-1.0.50/.gitignore

@@ -0,0 +1,18 @@
+.venv/
+__pycache__/
+*.pyc
+.env
+dist/
+build/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.ruff_cache/
+.DS_Store
+~/.navaia/
+
+p.enc
+recovered_model.zip

navaia_code-1.0.50/BUILDING_AGENT_TEAMS.md

@@ -0,0 +1,206 @@
+# Building Agent Teams with Navaia
+
+> Onboarding guide for the **Navaia Code** + **NavaiaForge SDK** stack.
+> If you've just been added as a collaborator, start here.
+
+---
+
+## The two repos, and how they fit together
+
+You have access to two repos that together form the Navaia development stack:
+
+| Repo | What it is | Stack |
+|---|---|---|
+| [`NavaiaSolutions/navaia-code-main`](https://github.com/NavaiaSolutions/navaia-code-main) | **Navaia Code** — a self-hosted terminal AI coding agent. Your AI pair-programmer for writing SDK integrations, scripts, and infrastructure. | Python (Textual TUI) |
+| [`NavaiaSolutions/navaia-forge-sdk`](https://github.com/NavaiaSolutions/navaia-forge-sdk) | **NavaiaForge SDK** — the official SDK to build, deploy, and orchestrate AI workforces on the NavaiaForge platform. | TypeScript + Python |
+
+### How they integrate
+
+```
+┌──────────────────────────────┐        ┌──────────────────────────────┐
+│  navaia-code-main            │        │  navaia-forge-sdk            │
+│  (your dev tool)             │        │  (what you build with)       │
+│                              │ ─────▶ │                              │
+│  AI pair-programmer in your  │ writes │  Programmatic API to create  │
+│  terminal. 50+ tools, MCP,   │ code   │  workforces, agents, tasks,  │
+│  any OpenAI-compatible LLM.  │        │  knowledge, observability.   │
+└──────────────────────────────┘        └──────────────────────────────┘
+                                                       │
+                                                       ▼
+                                        Calls the NavaiaForge platform
+                                        (api.navaia.com) → spawns and
+                                        runs your agent teams.
+```
+
+- **navaia-forge-sdk** is the product. Your shipped work lives here.
+- **navaia-code-main** is internal tooling — install once, use it to write SDK code faster. Not required to ship, but recommended.
+- Loop: open Navaia Code in the SDK repo → tell it what to build → it edits files, runs tests, opens PRs → you ship faster workforces.
+
+---
+
+## Setup (≈5 minutes)
+
+### 1. Clone both repos
+
+```bash
+git clone git@github.com:NavaiaSolutions/navaia-forge-sdk.git
+git clone git@github.com:NavaiaSolutions/navaia-code-main.git
+```
+
+### 2. Install Navaia Code (the dev tool)
+
+```bash
+cd navaia-code-main
+./setup.sh --global          # symlinks `navaia` into ~/.local/bin
+cp .env.example .env
+# Edit .env: set OPENROUTER_API_KEY (or your provider key)
+navaia                        # launch interactive UI
+```
+
+Provider options live in `.env`: OpenRouter (cloud, easiest), Ollama (local), vLLM/llama.cpp/LM Studio, or an internal vLLM deployment.
+
+### 3. Install the SDK (the product)
+
+```bash
+cd navaia-forge-sdk
+
+# TypeScript
+cd packages/typescript && npm install && npm test
+
+# Python
+cd packages/python && pip install -e ".[dev]" && pytest
+```
+
+### 4. Use them together
+
+From inside `navaia-forge-sdk/`:
+
+```bash
+navaia                        # opens Navaia Code in the SDK repo
+> "Add a retry helper to the Python tasks client and tests for it."
+```
+
+Navaia Code will read the codebase, write the change on a feature branch, run tests, and prepare a PR.
+
+---
+
+## Build your first agent team
+
+### TypeScript
+
+```ts
+import { NavaiaForge } from "@navaia/forge";
+
+const nf = new NavaiaForge({
+  apiKey: process.env.NAVAIA_API_KEY!,
+  baseUrl: "https://api.navaia.com",
+});
+
+const workforce = await nf.workforces.create({ name: "Research Crew" });
+
+const researcher = await nf.agents.create({
+  workforce_id: workforce.id,
+  name: "Researcher",
+  role: "research",
+  instructions: "Find and summarize info on any topic.",
+  model_provider: "anthropic",
+  model_name: "sonnet",
+});
+
+const task = await nf.tasks.create({
+  workforce_id: workforce.id,
+  agent_id: researcher.id,
+  title: "Summarize AI trends in 2026",
+});
+
+console.log((await nf.tasks.waitForCompletion(task.id)).result);
+```
+
+### Python
+
+```python
+from navaia_forge import NavaiaForgeClient
+
+client = NavaiaForgeClient(
+    base_url="https://api.navaia.com",
+    api_key="nf_your_api_key",
+)
+
+workforce = client.workforces.create(name="Research Crew")
+
+researcher = client.agents.create(
+    workforce_id=workforce["id"],
+    name="Researcher",
+    role="research",
+    instructions="Find and summarize info on any topic.",
+    model_provider="anthropic",
+    model_name="sonnet",
+)
+
+task = client.tasks.create(
+    workforce_id=workforce["id"],
+    agent_id=researcher["id"],
+    title="Summarize AI trends in 2026",
+)
+
+print(client.tasks.wait_for_completion(task["id"])["result"])
+```
+
+See the SDK repo's `examples/` and `templates/` directories for ready-to-fork workforces (multi-agent crews, RAG-powered support bots, etc.).
+
+---
+
+## SDK surface area
+
+The SDK gives you full access to the NavaiaForge API:
+
+| Resource | Use it for |
+|---|---|
+| **Workforces** | Create and manage AI workforces (collections of agents) |
+| **Agents** | Configure agents with roles, instructions, and models |
+| **Tasks** | Submit tasks, approve/reject, retry, poll for results |
+| **Conversations** | Chat with agents in real-time |
+| **Knowledge** | Upload documents for RAG-powered agents |
+| **Templates** | Browse and instantiate pre-built workforce templates |
+| **Observability** | Monitor token usage, costs, and performance metrics |
+| **Integrations** | Connect third-party services |
+
+---
+
+## Branch workflow (enforced)
+
+Three branches are protected on both repos: **`main`**, **`develop`**, **`release`**.
+
+- ❌ Direct pushes to `main` / `develop` / `release` are **rejected**.
+- ✅ Branch off `develop`, push, open a PR.
+- ✅ PR needs 1 approval and all conversations resolved before merge.
+- ✅ Only the maintainer (RekAlrasheed) can merge into the protected branches.
+
+```bash
+# In either repo
+git checkout develop && git pull
+git checkout -b feat/your-feature
+# ... edit, commit ...
+git push -u origin feat/your-feature
+gh pr create --base develop          # PR into develop, NOT main
+```
+
+**Flow:** feature branches → `develop` → cut to `release` → merge to `main` for tagged releases.
+
+### Commit style
+
+Conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `chore:`, `perf:`, `ci:`.
+
+```
+feat(tasks): add exponential-backoff retry to wait_for_completion
+```
+
+---
+
+## Need help?
+
+- Open a GitHub issue on the relevant repo.
+- Platform endpoint: `https://api.navaia.com` — ask the maintainer for an API key.
+- Provider config / Navaia Code questions: see this repo's `README.md` and `PLAN.md`.
+
+Welcome aboard. Now go build a workforce.

navaia_code-1.0.50/DEPLOYMENT.md

@@ -0,0 +1,179 @@
+# Deployment
+
+How to ship Genexa Code to internal users and capture usage.
+
+---
+
+## 1. Architecture
+
+```
+┌──────────────────────────┐
+│ Dev laptop               │
+│  genexa CLI (pipx)       │
+│  ~/.genexa/config.toml   │
+└──┬───────┬───────┬───────┘
+   │ LLM   │ OTLP  │ telemetry events
+   ▼       ▼       ▼
+ Providers Phoenix TWK backend
+                   (optional)
+```
+
+- Distribution: **internal git repo** — users clone, run a script. No URL hosting, no IT.
+- Observability: pick one (or both) — **Phoenix tracing** (recommended, no backend work) or **TWK backend telemetry** (custom events table).
+
+---
+
+## 2. Distribution mode (pick one)
+
+End-user flow is identical in both. Only difference is whether installed files are readable Python.
+
+| | Mode A — Source as-is | Mode B — PyArmor obfuscated |
+|---|---|---|
+| Source visible to user | Yes | No (encrypted bytecode) |
+| Same upgrade UX | yes | yes |
+| Extra build step | None | `pyarmor gen` in CI |
+| Repo users clone | `genexa-code` | `genexa-dist` (built artifact repo) |
+
+---
+
+## 3. End-user flow
+
+### First install (one time)
+
+```bash
+git clone https://<repo>.git ~/.genexa/src
+cd ~/.genexa/src && ./install.sh
+```
+
+`install.sh` verifies Python ≥ 3.12, installs `pipx` if missing, runs `pipx install .`, then `genexa init` for config.
+
+### Use
+
+```bash
+genexa                    # interactive TUI
+genexa -p "fix this bug"  # one-shot
+```
+
+### Upgrade
+
+```bash
+genexa upgrade
+```
+
+Pulls the cloned repo, reinstalls, prints version diff:
+
+```
+Current: 1.0.50  →  Latest: 1.0.51
+Done.
+```
+
+Startup also shows a non-blocking banner when a newer tag exists.
+
+### Uninstall
+
+```bash
+pipx uninstall genexa-code && rm -rf ~/.genexa
+```
+
+---
+
+## 4. Observability (pick one or both)
+
+### Option 1 — Phoenix tracing (Easiest)
+
+Phoenix instrumentation runs **inside the CLI**. Each user's LLM calls emit OTLP traces directly to the internal Phoenix collector. No backend changes.
+
+Captures: full LLM calls (prompts, completions, tokens, latency, model, errors), tool calls, tagged under project `"Genexa-Code"`. Per-user via `install_id` attribute.
+
+Needs: deps `arize-phoenix-otel` + `openinference-instrumentation-openai`, one `register()` call at startup, config:
+
+```toml
+[phoenix]
+enabled = true
+endpoint = "https://phoenix.corp.internal"
+```
+
+Kill switch: `GENEXA_PHOENIX_ENABLED=0`.
+
+### Option 2 — Genexa backend telemetry (custom events)
+
+CLI POSTs anonymized usage events to a new endpoint in the TWK QA Portal backend. Stored in Postgres for custom dashboards.
+
+Captures: session counts, token totals, provider/model mix, error types, version, OS. **No prompts or content.**
+
+Needs:
+- **Backend:** new SQLAlchemy model + alembic migration for `genexa_telemetry_events`, new router `POST /api/v1/genexa-telemetry/events`, PAT auth (reuse existing PAT pattern), one line in `main.py` to register router.
+- **CLI:** `genexa/telemetry/` module (client + disk spool + retry), event hooks in the query engine, config:
+
+```toml
+[telemetry]
+enabled = true
+endpoint = "https://<twk-host>/genexa/api/v1/genexa-telemetry/events"
+pat = "<from TWK portal>"
+```
+
+Kill switch: `GENEXA_TELEMETRY=0`.
+
+### When to pick which
+
+- **Phoenix only** — fastest to ship, best for debugging quality issues, reuses existing infra.
+- **Backend only** — when more data and dashboard needed, recieving whats needed only. 
+- **Both** — Phoenix for engineering, backend for PM/usage dashboards.
+
+---
+
+## 5. Release flow
+
+Single source of truth: `version` in `pyproject.toml`. Git tags as `v<version>`.
+
+### Mode A
+
+1. Bump `version` in `pyproject.toml`.
+2. Commit + `git tag v1.0.51 && git push --tags`.
+
+End users get it on next `genexa upgrade`.
+
+### Mode B
+
+CI on tag in `genexa-code`:
+
+1. Build with `pyarmor gen`.
+2. Push artifact tree + matching tag to `genexa-dist` repo.
+
+End users (pointed at `genexa-dist`) get it on next `genexa upgrade`.
+
+---
+
+## 6. Build checklist
+
+Nothing on this list exists yet.
+
+**Genexa Code repo (always):**
+- [ ] `install.sh` at repo root.
+- [ ] `genexa init` subcommand (config wizard).
+- [ ] `genexa upgrade` subcommand (git pull + reinstall + version diff).
+
+**If using Phoenix:**
+- [ ] `genexa/observability/phoenix.py` (setup + opt-in via env/config).
+- [ ] Phoenix deps in `pyproject.toml`.
+
+**If using TWK backend telemetry:**
+- [ ] `genexa/telemetry/` module (client + spool).
+- [ ] TWK backend: model + migration + router + main.py wiring.
+- [ ] PAT-issuing UI in the TWK frontend.
+
+**Mode B only:**
+- [ ] `genexa-dist` repo on internal git.
+- [ ] CI job that runs PyArmor and pushes to `genexa-dist` on tag.
+
+---
+
+## 7. Rollback
+
+```bash
+cd ~/.genexa/src
+git checkout v<old-version>
+pipx install . --force
+```
+
+Repo-wide: move tag back; users get the older version on next `genexa upgrade`.

navaia_code-1.0.50/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: navaia-code
+Version: 1.0.50
+Summary: Navaia Code — AI coding agent, built in Python
+Requires-Python: >=3.12
+Requires-Dist: aiofiles>=23.2.0
+Requires-Dist: arabic-reshaper>=3.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: openai>=1.30.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: python-bidi>=0.6.0
+Requires-Dist: python-dotenv>=1.1.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: rich>=13.9.0
+Requires-Dist: textual>=0.80.0
+Requires-Dist: tiktoken>=0.7.0
+Requires-Dist: typer>=0.12.0